Package org.jboss.netty.bootstrap
Class ClientBootstrap
java.lang.Object
org.jboss.netty.bootstrap.Bootstrap
org.jboss.netty.bootstrap.ClientBootstrap
- All Implemented Interfaces:
ExternalResourceReleasable
A helper class which creates a new client-side Applying different settings for different
Channel
and makes a
connection attempt.
Configuring a channel
Options
are used to configure a channel:
For the detailed list of available options, please refer toClientBootstrap
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 a ChannelPipelineFactory
by
calling Bootstrap.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:
Please note 'shallow-copy' here means that the addedClientBootstrap
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
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
ConstructorsConstructorDescriptionCreates a new instance with noChannelFactory
set.ClientBootstrap
(ChannelFactory channelFactory) Creates a new instance with the specified initialChannelFactory
. -
Method Summary
Modifier and TypeMethodDescriptionbind
(SocketAddress localAddress) Attempts to bind a channel with the specifiedlocalAddress
.connect()
Attempts a new connection with the current"remoteAddress"
and"localAddress"
option.connect
(SocketAddress remoteAddress) Attempts a new connection with the specifiedremoteAddress
and the current"localAddress"
option.connect
(SocketAddress remoteAddress, 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 Details
-
ClientBootstrap
public ClientBootstrap()Creates a new instance with noChannelFactory
set.Bootstrap.setFactory(ChannelFactory)
must be called before any I/O operation is requested. -
ClientBootstrap
Creates a new instance with the specified initialChannelFactory
.
-
-
Method Details
-
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 setClassCastException
- if"remoteAddress"
or"localAddress"
option's value is neither aSocketAddress
nornull
ChannelPipelineException
- if this bootstrap'spipelineFactory
failed to create a newChannelPipeline
-
connect
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:
ClassCastException
- if"localAddress"
option's value is neither aSocketAddress
nornull
ChannelPipelineException
- if this bootstrap'spipelineFactory
failed to create a newChannelPipeline
-
connect
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
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
-