Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `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.

Version:
  $Rev: 2344 $, $Date: 2010-07-07 16:55:37 +0900 (Wed, 07 Jul 2010) $
Author:
  The Netty Project, Trustin Lee

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

Method Summary
`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.
`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 `ChannelFactory` 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`

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 `ChannelFactory` 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:
    `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"));

  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.

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008-2010 JBoss, a division of Red Hat, Inc.. All Rights Reserved.