Package 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-sideChannel
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", newInetSocketAddress
("example.com", 8080)); b.setOption("tcpNoDelay", true); b.setOption("receiveBufferSize", 1048576);ChannelConfig
and its sub-types.Configuring a channel pipeline
Every channel has its ownChannelPipeline
and you can configure it in two ways. The recommended approach is to specify aChannelPipelineFactory
by callingBootstrap.setPipelineFactory(ChannelPipelineFactory)
.ClientBootstrap
b = ...; b.setPipelineFactory(new MyPipelineFactory()); public class MyPipelineFactory implementsChannelPipelineFactory
{ publicChannelPipeline
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());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 oneChannel
s or run a server that accepts incoming connections to create its child channels.Applying different settings for different
Channel
sClientBootstrap
is just a helper class. It neither allocates nor manages any resources. What manages the resources is theChannelFactory
implementation you specified in the constructor ofClientBootstrap
. Therefore, it is OK to create as manyClientBootstrap
instances as you want with the sameChannelFactory
to apply different settings for differentChannel
s.
-
-
Constructor Summary
Constructors Constructor Description ClientBootstrap()
Creates a new instance with noChannelFactory
set.ClientBootstrap(ChannelFactory channelFactory)
Creates a new instance with the specified initialChannelFactory
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ChannelFuture
bind(java.net.SocketAddress localAddress)
Attempts to bind a channel with the specifiedlocalAddress
.ChannelFuture
connect()
Attempts a new connection with the current"remoteAddress"
and"localAddress"
option.ChannelFuture
connect(java.net.SocketAddress remoteAddress)
Attempts a new connection with the specifiedremoteAddress
and the current"localAddress"
option.ChannelFuture
connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
Attempts a new connection with the specifiedremoteAddress
and the specifiedlocalAddress
.-
Methods inherited from class org.jboss.netty.bootstrap.Bootstrap
getFactory, getOption, getOptions, getPipeline, getPipelineAsMap, getPipelineFactory, isOrderedMap, releaseExternalResources, setFactory, setOption, setOptions, setPipeline, setPipelineAsMap, setPipelineFactory, shutdown
-
-
-
-
Constructor Detail
-
ClientBootstrap
public ClientBootstrap()
Creates a new instance with noChannelFactory
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 initialChannelFactory
.
-
-
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:
java.lang.IllegalStateException
- if"remoteAddress"
option was not setjava.lang.ClassCastException
- if"remoteAddress"
or"localAddress"
option's value is neither aSocketAddress
nornull
ChannelPipelineException
- if this bootstrap'spipelineFactory
failed to create a newChannelPipeline
-
connect
public ChannelFuture connect(java.net.SocketAddress remoteAddress)
Attempts a new connection with the specifiedremoteAddress
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:
java.lang.ClassCastException
- if"localAddress"
option's value is neither aSocketAddress
nornull
ChannelPipelineException
- if this bootstrap'spipelineFactory
failed to create a newChannelPipeline
-
connect
public ChannelFuture connect(java.net.SocketAddress remoteAddress, java.net.SocketAddress localAddress)
Attempts a new connection with the specifiedremoteAddress
and the specifiedlocalAddress
. If the specified local address isnull
, 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'spipelineFactory
failed to create a newChannelPipeline
-
bind
public ChannelFuture bind(java.net.SocketAddress localAddress)
Attempts to bind a channel with the specifiedlocalAddress
. later the channel can be connected to a remoteAddress by callingChannel.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
viaChannel.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'spipelineFactory
failed to create a newChannelPipeline
-
-