com.ascert.comms.driver.farsite
Class X25SocketImpl

java.lang.Object
  |
  +--com.ascert.comms.driver.farsite.X25SocketImpl
All Implemented Interfaces:
X25Socket

public class X25SocketImpl
extends java.lang.Object
implements X25Socket

Contains the X25Socket implementation for the FarSync range of X.25 cards.

Since:
1.00
Version:
1.00, 21 May 2003
Author:
Rob Walker

Field Summary
static java.lang.String FARSITE_DIAG_PROPERTY
          System property controlling whether diagnostics are produced to System.out.
 
Fields inherited from interface com.ascert.comms.x25.X25Socket
X25_CUD_LENGTH, X25_NUA_ADDRLEN
 
Constructor Summary
protected X25SocketImpl()
          General constructor to create and initialise a new X.25 socket.
 
Method Summary
 X25Socket accept()
          Accept a new incoming X.25 SVC (switched virtual circuit) connection on a server socket.
 void bind(java.lang.String localAddr)
          Binds a socket to a specific local NUA. This method is typically used to bind server sockets to local NUA's on which they will receive incoming calls. It can also be used to force client sockets to make calls from a specific local NUA..
 void close()
          Closes a socket, disconnecting any call.
 void connect(java.lang.String remoteAddr)
          Connects a client socket to a specified remote NUA using an X.25 SVC. The client socket can be bound to a local NUA. If the socket is already be connected or has been closed an Exception will be thrown..
 void connect(java.lang.String remoteAddr, int timeout)
          Connects a client socket with an optional timeout value, which may be 0 if no timeout is required. Note that there is no guarantee that all driver implementations will support timeouts, in which case this call and X25Socket.connect(String) are synonymous..
 void connectPVC(java.lang.String pvcQualifier)
          Connects a client socket to a PVC (permanent virtual circuit) X.25 connection. Note that although the "connect" metaphor is used here, in fact PVC's are permanent. So the only connection which is actually being made is between the Java application and the local X.25 card's i/o channel for the specific PVC.

Note that whilst the format of NUA's for SVC calls follow a standard which is likely to be common to most X.25 driver implementations, the means of specifying a particular PVC to be used may vary across implementations. Typically the format will be some qualifier to the specific LCN (logical channel number) to be used for the connection..

 byte[] getCallUserData()
          Gets any User Data which was supplied with an incoming call.
 byte[] getClearCodes()
          Gets any cause and diagnostic codes supplied when the current call was disconnected.
 byte[] getClearUserData()
          Gets any User Data which was supplied when the current call was cleared.
 java.lang.String getLocalAddress()
          Gets the local NUA to which the socket is bound (if any).
 java.lang.String getPhysicalAssignment()
          Gets any physical assignment properties for the socket.
 byte[] getRawFacilities()
          Gets any X.25 Facilities supplied with an incoming call.
 int getReceiveBufferSize()
          Gets the buffer size used by the underlying driver implementation for input on this connection.
 java.lang.String getRemoteAddress()
          Gets the remote NUA to which the socket is connected (if any).
 boolean isBound()
          Tests whether the X25Socket is bound
 boolean isClosed()
          Tests whether the X25Socket is closed, and hence unavailable for any further operations.
 boolean isConnected()
          Tests whether the X25Socket is connected, and hence available for data transfer.
 void listen(int backlog)
          Puts a server socket into Listen Mode, ready to accept incoming connections. Note that prior to listening for connections server sockets must have been bound to a local NUA..
 int recv(X25Message msg)
          Receive an incoming message on an X.25 socket.
 int send(X25Message msg)
          Send a message on an X.25 socket.
 void setCallUserData(byte[] cud)
          Sets the User Data to be included in the next outgoing call.
 void setClearCodes(byte[] clr)
          Sets the cause and diagnostic codes to be supplied when the current call is disconnected.
 void setClearUserData(byte[] cud)
          Sets the User Data to be included when the current call is cleared.
 void setPhysicalAssignment(java.lang.String param)
          Sets the physical assignment properties for the socket.

It is common for servers to have multi-port X.25 cards, each port driving a physically separate X.25 lines. Additionally, some servers may also have multiple X.25 cards installed. Depending on network topology, there may be a need to ensure that certain operations such as X25Socket.bind(java.lang.String), X25Socket.accept(), X25Socket.connect(java.lang.String) are directed to only a single line e.g. where an NUA is only valid for a single physical link. This method allows a socket to be tied to a specific physical line. Note, however, that at present the format used for the physical assignment specifier is driver implementation specific..

 void setRawFacilities(byte[] fac)
          Sets the X.25 Facilities to be used with the next outgoing call.
 void setReceiveBufferSize(int size)
          Sets the buffer size used by the underlying driver implementation for input on this connection.
 void shutdown()
          Graceful shutdown of the socket.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FARSITE_DIAG_PROPERTY

public static final java.lang.String FARSITE_DIAG_PROPERTY
System property controlling whether diagnostics are produced to System.out. Set to true to enable driver diagnostics.

See Also:
Constant Field Values
Constructor Detail

X25SocketImpl

protected X25SocketImpl()
                 throws java.io.IOException
General constructor to create and initialise a new X.25 socket. Note that generally this will only be called from within the farsite driver package by the X25FactoryImpl.

Throws:
java.io.IOException - Description of the Exception
Method Detail

accept

public X25Socket accept()
                 throws java.io.IOException
Description copied from interface: X25Socket
Accept a new incoming X.25 SVC (switched virtual circuit) connection on a server socket. Prior to accepting calls, server sockets must be bound to an NUA and be listening for incoming connections. A new socket instance will be returned for the incoming call, which cannot be null. Error cases will be signalled by an appropriate exception being thrown. This method may be called many times for a single server socket e.g. to accept multiple incoming calls for the same NUA.

Specified by:
accept in interface X25Socket
Returns:
a new X25Socket instance for the incoming call
Throws:
java.io.IOException - if an error occurs whilst waiting for a call
See Also:
X25Socket.bind(java.lang.String), X25Socket.listen(int)

bind

public void bind(java.lang.String localAddr)
          throws java.io.IOException
Binds a socket to a specific local NUA. This method is typically used to bind server sockets to local NUA's on which they will receive incoming calls. It can also be used to force client sockets to make calls from a specific local NUA..

FarSite driver specifics:
For the FarSync card, all NUA values are strings of up to 16 numeric characters.

Specified by:
bind in interface X25Socket
Parameters:
localAddr - local NUA to bind the socket too.
Throws:
java.io.IOException - if an error occurs during the bind

close

public void close()
           throws java.io.IOException
Description copied from interface: X25Socket
Closes a socket, disconnecting any call. Upon completion no further operations may be performed on the socket and no further data can be sent or received.

Specified by:
close in interface X25Socket
Throws:
java.io.IOException - if an error occurs during the close

connect

public void connect(java.lang.String remoteAddr)
             throws java.io.IOException
Connects a client socket to a specified remote NUA using an X.25 SVC. The client socket can be bound to a local NUA. If the socket is already be connected or has been closed an Exception will be thrown..

FarSite driver specifics:
For the FarSync card, all NUA values are strings of up to 16 numeric characters.

Specified by:
connect in interface X25Socket
Parameters:
remoteAddr - remote NUA to connect the socket too
Throws:
java.io.IOException - if an error occurs during the connect
See Also:
X25Socket.connect(String, int)

connect

public void connect(java.lang.String remoteAddr,
                    int timeout)
             throws java.io.IOException
Connects a client socket with an optional timeout value, which may be 0 if no timeout is required. Note that there is no guarantee that all driver implementations will support timeouts, in which case this call and X25Socket.connect(String) are synonymous..

FarSite driver specifics:
For the FarSync card, all NUA values are strings of up to 16 numeric characters.

Specified by:
connect in interface X25Socket
Parameters:
remoteAddr - remote NUA to connect the socket too
timeout - timeout value in milliseconds, or 0 if no timeout is required
Throws:
java.io.IOException - if an error occurs during the connect

connectPVC

public void connectPVC(java.lang.String pvcQualifier)
                throws java.io.IOException
Connects a client socket to a PVC (permanent virtual circuit) X.25 connection. Note that although the "connect" metaphor is used here, in fact PVC's are permanent. So the only connection which is actually being made is between the Java application and the local X.25 card's i/o channel for the specific PVC.

Note that whilst the format of NUA's for SVC calls follow a standard which is likely to be common to most X.25 driver implementations, the means of specifying a particular PVC to be used may vary across implementations. Typically the format will be some qualifier to the specific LCN (logical channel number) to be used for the connection..

FarSite driver specifics:
At present PVCs are only supported when using the Windows version of the FarSync sockets interface. An IOException with a failure to connect will be seen under Linux.

For the FarSync card, the PVC qualifier should be a numeric string containing the LCN to be used for a PVC, prefixed by a '+' character e.g. "+1" would indicate the PVC should use LCN 1. A phsyical assigment must also have been set for the socket or an exception will be thrown.

Specified by:
connectPVC in interface X25Socket
Parameters:
pvcQualifier - qualifier for the PVC (e.g. LCN number)
Throws:
java.io.IOException - if an error occurs connecting to the PVC
See Also:
setPhysicalAssignment(java.lang.String)

getCallUserData

public byte[] getCallUserData()
                       throws java.io.IOException
Description copied from interface: X25Socket
Gets any User Data which was supplied with an incoming call. This method will generally only return valid data immediately after a socket has been connected.

Specified by:
getCallUserData in interface X25Socket
Returns:
any user data supplied with an incoming call, or a 0 length array if none was supplied
Throws:
java.io.IOException - if an error occurs getting the call user data
See Also:
X25Socket.accept()

getClearCodes

public byte[] getClearCodes()
                     throws java.io.IOException
Description copied from interface: X25Socket
Gets any cause and diagnostic codes supplied when the current call was disconnected. Typically this method is only applicable once a call has been disconnected.

Specified by:
getClearCodes in interface X25Socket
Returns:
2 byte array, byte[0] being the cause and byte[1] being the diagnostic data
Throws:
java.io.IOException - if an error occurs getting the clear codes

getClearUserData

public byte[] getClearUserData()
                        throws java.io.IOException
Description copied from interface: X25Socket
Gets any User Data which was supplied when the current call was cleared. This method will generally only return valid data immediately after a socket has been disconnected.

Specified by:
getClearUserData in interface X25Socket
Returns:
any user data supplied when the call was disconnected, or a 0 length array if none was supplied
Throws:
java.io.IOException - if an error occurs getting the clear user data

getLocalAddress

public java.lang.String getLocalAddress()
Description copied from interface: X25Socket
Gets the local NUA to which the socket is bound (if any).

Specified by:
getLocalAddress in interface X25Socket
Returns:
local NUA the socket is bound to

getPhysicalAssignment

public java.lang.String getPhysicalAssignment()
                                       throws java.io.IOException
Description copied from interface: X25Socket
Gets any physical assignment properties for the socket.

Specified by:
getPhysicalAssignment in interface X25Socket
Returns:
any physical assignment details which are applicable
Throws:
java.io.IOException - if an error occurs getting the physical assignment details
See Also:
setPhysicalAssignment(java.lang.String)

getRawFacilities

public byte[] getRawFacilities()
                        throws java.io.IOException
Description copied from interface: X25Socket
Gets any X.25 Facilities supplied with an incoming call. Typically only of use immediately after a new connection has been received. The returned facilities will be in the raw format used in the X.25 incoming call packet.

Specified by:
getRawFacilities in interface X25Socket
Returns:
any X.25 Facilities received in the incoming call
Throws:
java.io.IOException - if an error occurs getting the raw facilities
See Also:
X25Socket.accept()

getReceiveBufferSize

public int getReceiveBufferSize()
                         throws java.io.IOException
Description copied from interface: X25Socket
Gets the buffer size used by the underlying driver implementation for input on this connection.

Specified by:
getReceiveBufferSize in interface X25Socket
Returns:
size of input buffer used for receiving data on this X25Socket
Throws:
java.io.IOException - if an error occurs getting the size
See Also:
X25Socket.setReceiveBufferSize(int)

getRemoteAddress

public java.lang.String getRemoteAddress()
Description copied from interface: X25Socket
Gets the remote NUA to which the socket is connected (if any).

Specified by:
getRemoteAddress in interface X25Socket
Returns:
local NUA the socket is connected to

isBound

public boolean isBound()
Description copied from interface: X25Socket
Tests whether the X25Socket is bound

Specified by:
isBound in interface X25Socket
Returns:
true if bound, false otherwise
See Also:
X25Socket.bind(java.lang.String)

isClosed

public boolean isClosed()
Description copied from interface: X25Socket
Tests whether the X25Socket is closed, and hence unavailable for any further operations.

Specified by:
isClosed in interface X25Socket
Returns:
true if closed, false otherwise
See Also:
X25Socket.close()

isConnected

public boolean isConnected()
Description copied from interface: X25Socket
Tests whether the X25Socket is connected, and hence available for data transfer.

Specified by:
isConnected in interface X25Socket
Returns:
true if connected, false otherwise
See Also:
X25Socket.connect(java.lang.String)

listen

public void listen(int backlog)
            throws java.io.IOException
Puts a server socket into Listen Mode, ready to accept incoming connections. Note that prior to listening for connections server sockets must have been bound to a local NUA..

FarSite driver specifics:
The FarSync card supports a maximum backlog value of 3.

Specified by:
listen in interface X25Socket
Parameters:
backlog - number of incoming connections that can be queued pending an accept operation (may not be supported by all driver implementations)
Throws:
java.io.IOException - if an error occurs during the listen
See Also:
X25Socket.bind(java.lang.String), X25Socket.accept()

recv

public int recv(X25Message msg)
         throws java.io.IOException
Description copied from interface: X25Socket
Receive an incoming message on an X.25 socket. An exception will be thrown if the socket is not connected, or if any other error occurs whilst waiting for data.

It should be note that X25 connections are packet based, hence the operation of this call is subtly different to stream based protocols such as TCP/IP. Firstly, if the buffer within the X25Message is large enough to receive a complete message, then it can be relied upon that whole messages will be received which are neither segmented nor chained with data from other messages. If the incoming message is too large to fit in the supplied X25Message, then as much data as will fit in the buffer will be returned, and the M-Bit will be set to indicate there is more data to be received to complete the incoming message. Further recv calls should be posted until a final X25Message is received with the M-bit unset.

Additionally, the presence of a Q-bit message can also be determined from the returned X25Message object.

Specified by:
recv in interface X25Socket
Parameters:
msg - message object in which to receive incoming data
Returns:
count of the number of bytes received, or 0 if the socket becomes disconnected whilst awaiting data
Throws:
java.io.IOException - if an error occurs whilst receiving data
See Also:
X25Socket.getReceiveBufferSize(), X25Socket.setReceiveBufferSize(int)

send

public int send(X25Message msg)
         throws java.io.IOException
Description copied from interface: X25Socket
Send a message on an X.25 socket. An exception will be thrown if the socket is not connected, or if any other error occurs whilst sending the data.

The X25Message object can specify whether the data is sent with one or both of the Q-bit and the M-bit set. Message sent with the M-bit set may be buffered by the driver implementation or the network until either full packets of data are available to send, or until a final non M-bit X25Message has been sent.

Specified by:
send in interface X25Socket
Parameters:
msg - message object containing the data to be sent
Returns:
count of the number of bytes actually sent
Throws:
java.io.IOException - if an error occurs whilst sending the data
See Also:
X25Socket.recv(com.ascert.comms.x25.X25Message)

setCallUserData

public void setCallUserData(byte[] cud)
                     throws java.io.IOException
Description copied from interface: X25Socket
Sets the User Data to be included in the next outgoing call. This method is generally only valid immediately before making a new connection. Up to 128 bytes of user data (fast select calls) in an X.25 call, or 16 bytes of user data (normal calls).

Specified by:
setCallUserData in interface X25Socket
Parameters:
cud - the user data to be sent with the next call
Throws:
java.io.IOException - if an error occurs setting the call user data
See Also:
X25Socket.connect(java.lang.String)

setClearCodes

public void setClearCodes(byte[] clr)
                   throws java.io.IOException
Description copied from interface: X25Socket
Sets the cause and diagnostic codes to be supplied when the current call is disconnected. Typically this method is only applicable prior to disconnecting a call. Note that setting cause & diagnostic codes may affect the error condition seen by the remote party on disconnection, and if the remote party is also using this Java library it may also affect which (if any) IOException is thrown.

Specified by:
setClearCodes in interface X25Socket
Parameters:
clr - 2 byte array, byte[0] being the cause and byte[1] being the diagnostic data
Throws:
java.io.IOException - if an error occurs setting the clear codes
See Also:
X25Socket.close()

setClearUserData

public void setClearUserData(byte[] cud)
                      throws java.io.IOException
Description copied from interface: X25Socket
Sets the User Data to be included when the current call is cleared. This method is generally only valid immediately before disconnecting a call.

Specified by:
setClearUserData in interface X25Socket
Parameters:
cud - the user data to be sent when the call is cleared
Throws:
java.io.IOException - if an error occurs setting the clear user data
See Also:
X25Socket.close()

setPhysicalAssignment

public void setPhysicalAssignment(java.lang.String param)
                           throws java.io.IOException
Sets the physical assignment properties for the socket.

It is common for servers to have multi-port X.25 cards, each port driving a physically separate X.25 lines. Additionally, some servers may also have multiple X.25 cards installed. Depending on network topology, there may be a need to ensure that certain operations such as X25Socket.bind(java.lang.String), X25Socket.accept(), X25Socket.connect(java.lang.String) are directed to only a single line e.g. where an NUA is only valid for a single physical link. This method allows a socket to be tied to a specific physical line. Note, however, that at present the format used for the physical assignment specifier is driver implementation specific..

FarSite driver specifics:
For the FarSync card, the physical assignment is a string in the format 'adaptor:line' e.g. an assignment value of "0:1" would tie the socket to adapter 0, line 1.

Specified by:
setPhysicalAssignment in interface X25Socket
Parameters:
param - driver implementation specific details of the physical line to which all operations for this socket should be directed
Throws:
java.io.IOException - if an error occurs setting the physical assignment

setRawFacilities

public void setRawFacilities(byte[] fac)
                      throws java.io.IOException
Description copied from interface: X25Socket
Sets the X.25 Facilities to be used with the next outgoing call. Typically only of use immediately before making a new connection. The facilities supplied must be in the raw format used for the X.25 outgoing call packet.

Specified by:
setRawFacilities in interface X25Socket
Parameters:
fac - raw facilities to be included in outgoing call
Throws:
java.io.IOException - if an error occurs setting the raw facilities
See Also:
X25Socket.connect(java.lang.String)

setReceiveBufferSize

public void setReceiveBufferSize(int size)
                          throws java.io.IOException
Description copied from interface: X25Socket
Sets the buffer size used by the underlying driver implementation for input on this connection.

The receive buffer size can affect the ability of the X.25 driver implementation to assemble incoming packets with the M-bit set into whole messages. Setting this value too small will result in lot's of message fragments being received by the application, and more message re-assembly needing to be handled in the application code.

Whatever value is used for the receive buffer size, applications must always ensure they supply a buffer of at least this size in X25Socket.recv(com.ascert.comms.x25.X25Message) calls to avoid an IllegalArgumentException being thrown.

Specified by:
setReceiveBufferSize in interface X25Socket
Parameters:
size - the new size for the input buffer. The value must be greater than 0.
Throws:
java.io.IOException - if an error occurs setting the raw facilities
See Also:
X25Socket.getReceiveBufferSize(), X25Socket.recv(com.ascert.comms.x25.X25Message)

shutdown

public void shutdown()
              throws java.io.IOException
Description copied from interface: X25Socket
Graceful shutdown of the socket. Since graceful shutdown is not really a standard X.25 feature, some driver implementations may take this method and X25Socket.close() as being synonymous. Where possible though, shutdown should ensure that sockets are closed in a manner which cleans up outstanding i/o requests in low level drivers.

Specified by:
shutdown in interface X25Socket
Throws:
java.io.IOException - if an error occurs during the shutdown
See Also:
X25Socket.close()