org.jboss.netty.bootstrap

## Class ClientBootstrap

- java.lang.Object
- - org.jboss.netty.bootstrap.Bootstrap
  - - org.jboss.netty.bootstrap.ClientBootstrap

- All Implemented Interfaces:
    ExternalResourceReleasable

      public class ClientBootstrap
      extends Bootstrap

  A helper class which creates a new client-side `Channel` and makes a connection attempt.

  ### Configuring a channel

  `Options` are used to configure a channel:

       ClientBootstrap b = ...;

       // Options for a new channel
       b.setOption("remoteAddress", new InetSocketAddress("example.com", 8080));
       b.setOption("tcpNoDelay", true);
       b.setOption("receiveBufferSize", 1048576);

  For the detailed list of available options, please refer to `ChannelConfig` and its sub-types.

  ### Configuring a 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)`.

       ClientBootstrap 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:

       ClientBootstrap 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

  `ClientBootstrap` 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 `ClientBootstrap`. Therefore, it is OK to create as many `ClientBootstrap` instances as you want with the same `ChannelFactory` to apply different settings for different `Channel`s.

- - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ChannelFuture` | `bind(SocketAddress localAddress)` Attempts to bind a channel with the specified `localAddress`. later the channel can be connected to a remoteAddress by calling `Channel.connect(SocketAddress)`.This method is useful where bind and connect need to be done in separate steps.
    `ChannelFuture` | `connect()` Attempts a new connection with the current `"remoteAddress"` and `"localAddress"` option.
    `ChannelFuture` | `connect(SocketAddress remoteAddress)` Attempts a new connection with the specified `remoteAddress` and the current `"localAddress"` option.
    `ChannelFuture` | `connect(SocketAddress remoteAddress, SocketAddress localAddress)` Attempts a new connection with the specified `remoteAddress` and the specified `localAddress`.

    - ### Methods inherited from class org.jboss.netty.bootstrap.Bootstrap

      `getFactory, getOption, getOptions, getPipeline, getPipelineAsMap, getPipelineFactory, releaseExternalResources, setFactory, 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

    - #### ClientBootstrap

          public ClientBootstrap()

      Creates a new instance with no `ChannelFactory` set. `Bootstrap.setFactory(ChannelFactory)` must be called before any I/O operation is requested.

    - #### ClientBootstrap

          public ClientBootstrap(ChannelFactory channelFactory)

      Creates a new instance with the specified initial `ChannelFactory`.

  - ### Method Detail

    - #### connect

          public ChannelFuture connect()

      Attempts a new connection with the current `"remoteAddress"` and `"localAddress"` option. If the `"localAddress"` option is not set, the local address of a new channel is determined automatically. This method is similar to the following code:

           ClientBootstrap b = ...;
           b.connect(b.getOption("remoteAddress"), b.getOption("localAddress"));

      Returns:
        a future object which notifies when this connection attempt succeeds or fails
      Throws:
        `IllegalStateException` - if `"remoteAddress"` option was not set
        `ClassCastException` - if `"remoteAddress"` or `"localAddress"` option's value is neither a `SocketAddress` nor `null`
        `ChannelPipelineException` - if this bootstrap's `pipelineFactory` failed to create a new `ChannelPipeline`

    - #### connect

          public ChannelFuture connect(SocketAddress remoteAddress)

      Attempts a new connection with the specified `remoteAddress` and the current `"localAddress"` option. If the `"localAddress"` option is not set, the local address of a new channel is determined automatically. This method is identical with the following code:

           ClientBootstrap b = ...;
           b.connect(remoteAddress, b.getOption("localAddress"));

      Returns:
        a future object which notifies when this connection attempt succeeds or fails
      Throws:
        `ClassCastException` - if `"localAddress"` option's value is neither a `SocketAddress` nor `null`
        `ChannelPipelineException` - if this bootstrap's `pipelineFactory` failed to create a new `ChannelPipeline`

    - #### connect

          public ChannelFuture connect(SocketAddress remoteAddress,
                              SocketAddress localAddress)

      Attempts a new connection with the specified `remoteAddress` and the specified `localAddress`. If the specified local address is `null`, the local address of a new channel is determined automatically.
      Returns:
        a future object which notifies when this connection attempt succeeds or fails
      Throws:
        `ChannelPipelineException` - if this bootstrap's `pipelineFactory` failed to create a new `ChannelPipeline`

    - #### bind

          public ChannelFuture bind(SocketAddress localAddress)

      Attempts to bind a channel with the specified `localAddress`. later the channel can be connected to a remoteAddress by calling `Channel.connect(SocketAddress)`.This method is useful where bind and connect need to be done in separate steps. This can also be useful if you want to set an attachment to the `Channel` via `Channel.setAttachment(Object)` so you can use it after the `bind(SocketAddress)` was done.
      For example:

            ChannelFuture bindFuture = bootstrap.bind(new InetSocketAddress("192.168.0.15", 0));
            Channel channel = bindFuture.getChannel();
            channel.setAttachment(dataObj);
            bootstrap.connect(new InetSocketAddress("192.168.0.30", 8080));

      You can use it then in your handlers like this:

            public class YourHandler extends SimpleChannelUpstreamHandler {
                public void channelConnected(ChannelHandlerContext ctx, ChannelStateEvent e) throws Exception {
                    Object dataObject = ctx.getChannel().getAttachment();
                }
            }

      Returns:
        a future object which notifies when this bind attempt succeeds or fails
      Throws:
        `ChannelPipelineException` - if this bootstrap's `pipelineFactory` failed to create a new `ChannelPipeline`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.