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

Version:
  $Rev: 2337 $, $Date: 2010-07-07 13:32:10 +0900 (Wed, 07 Jul 2010) $
Author:
  The Netty Project, Trustin Lee

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

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

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