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

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

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, shutdown

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.

For an instance, a user can set an attachment to the Channel via Channel.setAttachment(Object) before beginning a connection attempt so that the user can access the attachment once the connection is established:

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

The attachment can be accessed then in the handler like the following:

  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