Package org.jboss.netty.bootstrap
Class ServerBootstrap
- java.lang.Object
-
- org.jboss.netty.bootstrap.Bootstrap
-
- org.jboss.netty.bootstrap.ServerBootstrap
-
- All Implemented Interfaces:
ExternalResourceReleasable
public class ServerBootstrap extends Bootstrap
A helper class which creates a new server-sideChannel
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
viabind()
andbind(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:ServerBootstrap
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 aChannelPipelineFactory
by callingBootstrap.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:
ServerBootstrap
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 oneChannel
s or run a server that accepts incoming connections to create its child channels.Applying different settings for different
Channel
sServerBootstrap
is just a helper class. It neither allocates nor manages any resources. What manages the resources is theChannelFactory
implementation you specified in the constructor ofServerBootstrap
. Therefore, it is OK to create as manyServerBootstrap
instances as you want with the sameChannelFactory
to apply different settings for differentChannel
s.
-
-
Constructor Summary
Constructors Constructor Description ServerBootstrap()
Creates a new instance with noChannelFactory
set.ServerBootstrap(ChannelFactory channelFactory)
Creates a new instance with the specified initialChannelFactory
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description Channel
bind()
Creates a new channel which is bound to the local address which was specified in the current"localAddress"
option.Channel
bind(SocketAddress localAddress)
Creates a new channel which is bound to the specified local address.ChannelFuture
bindAsync()
Bind a channel asynchronous to the local address specified in the current"localAddress"
option.ChannelFuture
bindAsync(SocketAddress localAddress)
Bind a channel asynchronous to the specified local address.ChannelHandler
getParentHandler()
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, releaseExternalResources, setOption, setOptions, setPipeline, setPipelineAsMap, setPipelineFactory, shutdown
-
-
-
-
Constructor Detail
-
ServerBootstrap
public ServerBootstrap()
Creates a new instance with noChannelFactory
set.setFactory(ChannelFactory)
must be called before any I/O operation is requested.
-
ServerBootstrap
public ServerBootstrap(ChannelFactory channelFactory)
Creates a new instance with the specified initialChannelFactory
.
-
-
Method Detail
-
setFactory
public void setFactory(ChannelFactory factory)
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
public ChannelHandler 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
public void setParentHandler(ChannelHandler parentHandler)
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
public Channel 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
public Channel bind(SocketAddress localAddress)
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
public ChannelFuture 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
public ChannelFuture bindAsync(SocketAddress localAddress)
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
-
-