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.

  • Field Details

  • Constructor Details

  • Method Details

    • 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