Package org.jboss.netty.bootstrap

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

    • 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:
        java.lang.IllegalStateException - if the factory is already set
        java.lang.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:
        java.lang.IllegalStateException - if "localAddress" option was not set
        java.lang.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​(java.net.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:
        java.lang.IllegalStateException - if "localAddress" option was not set
        java.lang.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​(java.net.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