Package org.jboss.netty.bootstrap
Class ServerBootstrap
java.lang.Object
org.jboss.netty.bootstrap.Bootstrap
org.jboss.netty.bootstrap.ServerBootstrap
- All Implemented Interfaces:
ExternalResourceReleasable
A helper class which creates a new server-side Applying different settings for different
Channel
and accepts
incoming connections.
Only for connection oriented transports
This bootstrap is for connection oriented transports only such as TCP/IP and local transport. UseConnectionlessBootstrap
instead for
connectionless transports. Do not use this helper if you are using a
connectionless transport such as UDP/IP which does not accept an incoming
connection but receives messages by itself without creating a child channel.
Parent channel and its children
A parent channel is a channel which is supposed to accept incoming connections. It is created by this bootstrap'sChannelFactory
via
bind()
and bind(SocketAddress)
.
Once successfully bound, the parent channel starts to accept incoming connections, and the accepted connections become the children of the parent channel.
Configuring channels
Options
are used to configure both a
parent channel and its child channels. To configure the child channels,
prepend "child."
prefix to the actual option names of a child
channel:
For the detailed list of available options, please refer toServerBootstrap
b = ...; // Options for a parent channel b.setOption("localAddress", newInetSocketAddress
(8080)); b.setOption("reuseAddress", true); // Options for its children b.setOption("child.tcpNoDelay", true); b.setOption("child.receiveBufferSize", 1048576);
ChannelConfig
and its sub-types.
Configuring a parent channel pipeline
It is rare to customize the pipeline of a parent channel because what it is supposed to do is very typical. However, you might want to add a handler to deal with some special needs such as degrading the process UID from a superuser to a normal user and changing the current VM security manager for better security. To support such a case, theparentHandler
property is
provided.
Configuring a child channel pipeline
Every channel has its ownChannelPipeline
and you can configure it
in two ways.
The recommended approach is to specify a ChannelPipelineFactory
by
calling Bootstrap.setPipelineFactory(ChannelPipelineFactory)
.
ServerBootstrap
b = ...; b.setPipelineFactory(new MyPipelineFactory()); public class MyPipelineFactory implementsChannelPipelineFactory
{ publicChannelPipeline
getPipeline() throws Exception { // Create and configure a new pipeline for a new channel.ChannelPipeline
p =Channels
.pipeline(); p.addLast("encoder", new EncodingHandler()); p.addLast("decoder", new DecodingHandler()); p.addLast("logic", new LogicHandler()); return p; } }
The alternative approach, which works only in a certain situation, is to use the default pipeline and let the bootstrap to shallow-copy the default pipeline for each new channel:
Please note 'shallow-copy' here means that the addedServerBootstrap
b = ...;ChannelPipeline
p = b.getPipeline(); // Add handlers to the default pipeline. p.addLast("encoder", new EncodingHandler()); p.addLast("decoder", new DecodingHandler()); p.addLast("logic", new LogicHandler());
ChannelHandler
s
are not cloned but only their references are added to the new pipeline.
Therefore, you cannot use this approach if you are going to open more than
one Channel
s or run a server that accepts incoming connections to
create its child channels.
Applying different settings for different Channel
s
ServerBootstrap
is just a helper class. It neither allocates nor
manages any resources. What manages the resources is the
ChannelFactory
implementation you specified in the constructor of
ServerBootstrap
. Therefore, it is OK to create as many
ServerBootstrap
instances as you want with the same
ChannelFactory
to apply different settings for different
Channel
s.-
Nested Class Summary
Nested Classes -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new instance with noChannelFactory
set.ServerBootstrap
(ChannelFactory channelFactory) Creates a new instance with the specified initialChannelFactory
. -
Method Summary
Modifier and TypeMethodDescriptionbind()
Creates a new channel which is bound to the local address which was specified in the current"localAddress"
option.bind
(SocketAddress localAddress) Creates a new channel which is bound to the specified local address.Bind a channel asynchronous to the local address specified in the current"localAddress"
option.bindAsync
(SocketAddress localAddress) Bind a channel asynchronous to the specified local address.Returns an optionalChannelHandler
which intercepts an event of a newly bound server-side channel which accepts incoming connections.void
setFactory
(ChannelFactory factory) Sets theServerChannelFactory
that will be used to perform an I/O operation.void
setParentHandler
(ChannelHandler parentHandler) Sets an optionalChannelHandler
which intercepts an event of a newly bound server-side channel which accepts incoming connections.Methods inherited from class org.jboss.netty.bootstrap.Bootstrap
getFactory, getOption, getOptions, getPipeline, getPipelineAsMap, getPipelineFactory, isOrderedMap, releaseExternalResources, setOption, setOptions, setPipeline, setPipelineAsMap, setPipelineFactory, shutdown
-
Field Details
-
parentHandler
-
-
Constructor Details
-
ServerBootstrap
public ServerBootstrap()Creates a new instance with noChannelFactory
set.setFactory(ChannelFactory)
must be called before any I/O operation is requested. -
ServerBootstrap
Creates a new instance with the specified initialChannelFactory
.
-
-
Method Details
-
setFactory
Sets theServerChannelFactory
that will be used to perform an I/O operation. This method can be called only once and can't be called at all if the factory was specified in the constructor.- Overrides:
setFactory
in classBootstrap
- Throws:
IllegalStateException
- if the factory is already setIllegalArgumentException
- if the specifiedfactory
is not aServerChannelFactory
-
getParentHandler
Returns an optionalChannelHandler
which intercepts an event of a newly bound server-side channel which accepts incoming connections.- Returns:
- the parent channel handler.
null
if no parent channel handler is set.
-
setParentHandler
Sets an optionalChannelHandler
which intercepts an event of a newly bound server-side channel which accepts incoming connections.- Parameters:
parentHandler
- the parent channel handler.null
to unset the current parent channel handler.
-
bind
Creates a new channel which is bound to the local address which was specified in the current"localAddress"
option. This method is similar to the following code:ServerBootstrap
b = ...; b.bind(b.getOption("localAddress"));- Returns:
- a new bound channel which accepts incoming connections
- Throws:
IllegalStateException
- if"localAddress"
option was not setClassCastException
- if"localAddress"
option's value is neither aSocketAddress
nornull
ChannelException
- if failed to create a new channel and bind it to the local address
-
bind
Creates a new channel which is bound to the specified local address. This operation will block until the channel is bound.- Returns:
- a new bound channel which accepts incoming connections
- Throws:
ChannelException
- if failed to create a new channel and bind it to the local address
-
bindAsync
Bind a channel asynchronous to the local address specified in the current"localAddress"
option. This method is similar to the following code:ServerBootstrap
b = ...; b.bindAsync(b.getOption("localAddress"));- Returns:
- a new
ChannelFuture
which will be notified once the Channel is bound and accepts incoming connections - Throws:
IllegalStateException
- if"localAddress"
option was not setClassCastException
- if"localAddress"
option's value is neither aSocketAddress
nornull
ChannelException
- if failed to create a new channel and bind it to the local address
-
bindAsync
Bind a channel asynchronous to the specified local address.- Returns:
- a new
ChannelFuture
which will be notified once the Channel is bound and accepts incoming connections
-