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-side 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. Use ConnectionlessBootstrap 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's ChannelFactory 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:

 ServerBootstrap b = ...;

 // Options for a parent channel
 b.setOption("localAddress", new InetSocketAddress(8080));
 b.setOption("reuseAddress", true);

 // Options for its children
 b.setOption("child.tcpNoDelay", true);
 b.setOption("child.receiveBufferSize", 1048576);
 

For the detailed list of available options, please refer to 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, the parentHandler property is provided.

Configuring a child channel pipeline

Every channel has its own ChannelPipeline 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 implements ChannelPipelineFactory {
   public ChannelPipeline 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());
 

Please note 'shallow-copy' here means that the added ChannelHandlers 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 Channels or run a server that accepts incoming connections to create its child channels.

Applying different settings for different Channels

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 Channels.

Constructor Summary

Constructors

Constructor and Description
ServerBootstrap() Creates a new instance with no ChannelFactory set.
ServerBootstrap(ChannelFactory channelFactory) Creates a new instance with the specified initial ChannelFactory.

Method Summary

Methods

Modifier and Type	Method and 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 optional ChannelHandler which intercepts an event of a newly bound server-side channel which accepts incoming connections.
void	setFactory(ChannelFactory factory) Sets the ServerChannelFactory that will be used to perform an I/O operation.
void	setParentHandler(ChannelHandler parentHandler) Sets an optional ChannelHandler 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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerBootstrap

public ServerBootstrap()

Creates a new instance with no ChannelFactory 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 initial ChannelFactory.

Method Detail

setFactory

public void setFactory(ChannelFactory factory)

Sets the ServerChannelFactory 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 class Bootstrap

Throws:

IllegalStateException - if the factory is already set

IllegalArgumentException - if the specified factory is not a ServerChannelFactory

getParentHandler

public ChannelHandler getParentHandler()

Returns an optional ChannelHandler 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 optional ChannelHandler 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"));
 

This operation will block until the channel is bound.

Returns:

a new bound channel which accepts incoming connections

Throws:

IllegalStateException - if "localAddress" option was not set

ClassCastException - if "localAddress" option's value is neither a SocketAddress nor null

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 set

ClassCastException - if "localAddress" option's value is neither a SocketAddress nor null

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