|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.ObjectClientConn
A somewhat simple, asynchronous interface to a TCP-based outgoing or "client"
connection. Provides a concept of connection state as well as a stream handler that processes the socket's data
streams, once connected, in its own thread.
One shortcoming of this class is that it does not by default support a
proxy of any kind. That is, there are no connection states relating to
connecting to a proxy. However, one can use a custom javax.net.SocketFactory
that connects to the proxy
and then returns that Socket
, or even something more complicated
(like returning a custom subclass of Socket
in the socket
factory for some sort of proxy with extrastream metadata).
As stated above, this class provides a notion of the current state of a
connection. The following is a list of all possible state transitions and
each transition's meaning. Note that when the state changes, all listeners are notified of the old state, the new state, and
a "reason" object whose type varies
(though it is most commonly a java.lang.Exception
or
a java.lang.Error
). The type and meaning of this reason object
for each state transition is given below.
STATE_NOT_CONNECTED
-> STATE_INITING
->
STATE_FAILED
java.lang.Throwable
that caused the failure
STATE_NOT_CONNECTED
-> STATE_INITING
->
STATE_RESOLVING
-> STATE_FAILED
java.net.UnknownHostException
STATE_NOT_CONNECTED
-> STATE_INITING
->
[STATE_RESOLVING
(optional)] ->
STATE_CONNECTING
-> STATE_FAILED
java.net.IOException
STATE_NOT_CONNECTED
-> STATE_INITING
->
[STATE_RESOLVING
(optional)] ->
STATE_CONNECTING
-> STATE_CONNECTED
->
STATE_NOT_CONNECTED
disconnect()
was calledREASON_ON_PURPOSE
java.lang.IOException
that
caused the connection to closeREASON_CONN_CLOSED
disconnect
during a connection, the state will revert to
STATE_NOT_CONNECTED
no matter what state it's currently in.
connect
will fail if both of these are set and if
neither of these is set. So what does this mean? Yes, it means only one of
these values can be non-null
when connect
is
called.
InetAddress
. I did this because often one wants to resolve a
hostname in the same thread as one is connecting on, as resolving and
connecting normally happen in succession when making a connection.
ClientConn
and that the stream handler's handleStream
method is not.
ClientConn
s are created with no stream handler,
no connection listeners, and a default socket factory (null
).
A typical usage of ClientConn
, then, might be as follows:
ClientConn conn = new ClientConn("joust.kano.net", 80); conn.addConnListener(myConnectionListener); conn.setStreamHandler(myStreamHandler); conn.setSocketFactory(new SomeSortOfProxySocketFactoryYouMade()); conn.connect(); System.out.println("Connecting...");Note that the italicized portion of the above code sets a custom socket factory. This step is by no means required, but is useful for creating connections through a proxy. See
setSocketFactory
for details. Also note that the code prints a "Connecting..."
message after calling connect
. If you don't understand
that this class is completely asynchronous by now, I don't think you
ever will.
Nested Class Summary | |
static class |
ClientConn.State
Represents a single connection state. |
Field Summary | |
static ClientConn.State |
REASON_CONN_CLOSED
A reason indicating that the reason for a state change to NOT_CONNECTED was that the socket was closed for some
reason. |
static ClientConn.State |
REASON_ON_PURPOSE
A reason indicating that the reason for a state change to NOT_CONNECTED was that disconnect was called. |
static ClientConn.State |
STATE_CONNECTED
A state indicating that a TCP connection has succeeded and is currently open. |
static ClientConn.State |
STATE_CONNECTING
A state indicating that a TCP connection attempt is being made to the given server on the given port. |
static ClientConn.State |
STATE_FAILED
A state indicating that some stage of the connection failed. |
static ClientConn.State |
STATE_INITING
A state indicating that this FLAP client is preparing to connect. |
static ClientConn.State |
STATE_NOT_CONNECTED
A state indicating that this FLAP client is not connected to a server. |
static ClientConn.State |
STATE_RESOLVING
A state indicating that the given hostname is being resolved to an IP address before connecting. |
Constructor Summary | |
ClientConn()
Creates a ClientConn with no hostname/IP or port. |
|
ClientConn(java.net.InetAddress ip,
int port)
Creates a ClientConn for the given IP address and port
number. |
|
ClientConn(java.lang.String host,
int port)
Creates a ClientConn for the given hostname and port number.
|
Method Summary | |
void |
addConnListener(ClientConnListener l)
Adds a connection listener to this connection. |
void |
connect()
Attempts to connect using the values of host or IP address and TCP port which were, presumably, set before this method was called. |
void |
disconnect()
If not already disconnected, this disconnects the TCP socket associated with this connection and sets the connection state to STATE_NOT_CONNECTED . |
java.lang.String |
getHost()
Returns the hostname associated with this connection. |
java.net.InetAddress |
getIpAddress()
Returns the IP address associated with this connection. |
int |
getPort()
Returns the TCP port associated with this connection. |
java.net.Socket |
getSocket()
Returns the socket on which this connection resides, or null
if this connection has no underlying socket yet. |
javax.net.SocketFactory |
getSocketFactory()
Sets this FLAP connection's socket factory. |
ClientConn.State |
getState()
Returns the current connection state. |
ClientConnStreamHandler |
getStreamHandler()
Returns this connection's "stream handler." |
protected void |
processError(java.lang.Throwable t)
Closes this connection and sets the state to STATE_NOT_CONNECTED , with the given exception or error as
the state change's reason object.
|
void |
removeConnListener(ClientConnListener l)
Removes a connection listener from this connection. |
void |
setHost(java.lang.String host)
Sets the hostname associated with this connection. |
void |
setIpAddress(java.net.InetAddress ip)
Sets the IP address associated with this connection. |
void |
setPort(int port)
Sets the TCP port associated with this connection. |
void |
setSocketFactory(javax.net.SocketFactory socketFactory)
Sets the socket factory this FLAP connection should use to create an outgoing socket. |
void |
setStreamHandler(ClientConnStreamHandler streamHandler)
Sets the "stream handler" for this connection to the given handler. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final ClientConn.State STATE_NOT_CONNECTED
public static final ClientConn.State STATE_INITING
public static final ClientConn.State STATE_RESOLVING
public static final ClientConn.State STATE_CONNECTING
public static final ClientConn.State STATE_CONNECTED
public static final ClientConn.State STATE_FAILED
ClientFlapConn
documentation for details on state transitions
and meanings.
public static final ClientConn.State REASON_ON_PURPOSE
NOT_CONNECTED
was that disconnect
was called.
public static final ClientConn.State REASON_CONN_CLOSED
NOT_CONNECTED
was that the socket was closed for some
reason. This normally means some sort of network failure.
Constructor Detail |
public ClientConn()
ClientConn
with no hostname/IP or port. (You can
use setHost(java.lang.String)
, setIpAddress(java.net.InetAddress)
, and setPort(int)
to set
them later.)
public ClientConn(java.lang.String host, int port)
ClientConn
for the given hostname and port number.
The given hostname and port will be be used to connect to when
connect
is called.
host
- the hostname to connect to when connect
is
calledport
- the port to connect to when connect
is calledpublic ClientConn(java.net.InetAddress ip, int port)
ClientConn
for the given IP address and port
number. The given IP address and port will be be used to connect to when
connect
is called.
ip
- the hostname to connect to when connect
is
calledport
- the port to connect to when connect
is calledMethod Detail |
public final void addConnListener(ClientConnListener l)
l
- the listener to addpublic final void removeConnListener(ClientConnListener l)
l
- the listener to removepublic final java.net.Socket getSocket()
null
if this connection has no underlying socket yet.
public final java.lang.String getHost()
public final void setHost(java.lang.String host)
host
- the hostname to associate with this connectionpublic final java.net.InetAddress getIpAddress()
public final void setIpAddress(java.net.InetAddress ip)
ip
- the IP address associated with this connectionpublic final int getPort()
public final void setPort(int port)
port
- the TCP port associated with this connectionpublic final ClientConn.State getState()
STATE_NOT_CONNECTED
, STATE_INITING
, STATE_RESOLVING
,
STATE_CONNECTING
, STATE_CONNECTED
, or STATE_FAILED
; see each value's individual documentation for details.
public final void connect() throws java.lang.IllegalStateException
Socket
will be passed to this
ClientConn
's stream handler
.
STATE_NOT_CONNECTED
and STATE_FAILED
;
otherwise one must call disconnect()
before calling this method.
java.lang.IllegalStateException
- if a connection attempt is already being
made; if both IP and hostname are both set; if neither IP or
hostname is set; if port is not setprotected final void processError(java.lang.Throwable t)
STATE_NOT_CONNECTED
, with the given exception or error as
the state change's reason object.
Note that calling this method will have no effect if the connection state
is already STATE_NOT_CONNECTED
or STATE_FAILED
.
t
- an exception or error that caused the connection to closepublic final void disconnect()
STATE_NOT_CONNECTED
. Note that if the connection state is
already STATE_NOT_CONNECTED
or STATE_FAILED
no state change will take place.
public final void setSocketFactory(javax.net.SocketFactory socketFactory)
socketFactory
is null
, as
is the default value, new Socket(..)
is used in place of a
using a socket factory.
socketFactory
- a socket factory to use in creating the outgoing
OSCAR connection, or null
to not use a factorypublic final javax.net.SocketFactory getSocketFactory()
null
(the default value) then new Socket(..)
is
used in place of using a socket factory to create a socket.
public final void setStreamHandler(ClientConnStreamHandler streamHandler)
Socket
created by this
ClientConn
as soon as it has been successfully created.
streamHandler
can be null
if you
really want it to be; a value of null
simply means the
connection will be made and immediately dropped.
STATE_CONNECTED
.
ClientConn
s are
initialized with no stream handler (a value of null
).
streamHandler
- a "stream handler" for this connectionClientConnStreamHandler
public final ClientConnStreamHandler getStreamHandler()
null
.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |