com.ascert.comms.x25
Interface X25Socket

All Known Implementing Classes:
X25SocketImpl

public interface X25Socket

Defines a common interface for connecting and communicating using X.25. For convenience a socket based approach has been chosen for the naming and usage of methods. This will be familiar to most Java programmers from the java.net.* TCP/IP classes. Driver implementations for specific vendor's cards and software API's must map this interface onto card and driver specific calls to perform the required functions.

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

Field Summary
static int X25_CUD_LENGTH
          Constant value for maximum size of Call User Data.
static int X25_NUA_ADDRLEN
          Constant value for the maximum size of an X.25 NUA.
 
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.
 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.
 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.
 void connectPVC(java.lang.String pvcQualifier)
          Connects a client socket to a PVC (permanent virtual circuit) X.25 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.
 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.
 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.
 

Field Detail

X25_CUD_LENGTH

public static final int X25_CUD_LENGTH
Constant value for maximum size of Call User Data. Note that for non fast-select calls this is reduced to only 16 bytes.

See Also:
Constant Field Values

X25_NUA_ADDRLEN

public static final int X25_NUA_ADDRLEN
Constant value for the maximum size of an X.25 NUA.

See Also:
Constant Field Values
Method Detail

accept

public X25Socket accept()
                 throws java.io.IOException
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.

Returns:
a new X25Socket instance for the incoming call
Throws:
java.io.IOException - if an error occurs whilst waiting for a call
Since:
1.00
See Also:
bind(java.lang.String), 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.

Parameters:
localAddr - local NUA to bind the socket too.
Throws:
java.io.IOException - if an error occurs during the bind
Since:
1.00

close

public void close()
           throws java.io.IOException
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.

Throws:
java.io.IOException - if an error occurs during the close
Since:
1.00

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.

Parameters:
remoteAddr - remote NUA to connect the socket too
Throws:
java.io.IOException - if an error occurs during the connect
Since:
1.00
See Also:
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 connect(String) are synonymous.

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
Since:
1.00

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.

Parameters:
pvcQualifier - qualifier for the PVC (e.g. LCN number)
Throws:
java.io.IOException - if an error occurs connecting to the PVC
Since:
1.00

getCallUserData

public byte[] getCallUserData()
                       throws java.io.IOException
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.

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
Since:
1.00
See Also:
accept()

getClearCodes

public byte[] getClearCodes()
                     throws java.io.IOException
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.

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
Since:
1.00

getClearUserData

public byte[] getClearUserData()
                        throws java.io.IOException
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.

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
Since:
1.00

getLocalAddress

public java.lang.String getLocalAddress()
Gets the local NUA to which the socket is bound (if any).

Returns:
local NUA the socket is bound to
Since:
1.00

getPhysicalAssignment

public java.lang.String getPhysicalAssignment()
                                       throws java.io.IOException
Gets any physical assignment properties for the socket.

Returns:
any physical assignment details which are applicable
Throws:
java.io.IOException - if an error occurs getting the physical assignment details
Since:
1.00

getRawFacilities

public byte[] getRawFacilities()
                        throws java.io.IOException
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.

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

getReceiveBufferSize

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

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

getRemoteAddress

public java.lang.String getRemoteAddress()
Gets the remote NUA to which the socket is connected (if any).

Returns:
local NUA the socket is connected to
Since:
1.00

isBound

public boolean isBound()
Tests whether the X25Socket is bound

Returns:
true if bound, false otherwise
Since:
1.00
See Also:
bind(java.lang.String)

isClosed

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

Returns:
true if closed, false otherwise
Since:
1.00
See Also:
close()

isConnected

public boolean isConnected()
Tests whether the X25Socket is connected, and hence available for data transfer.

Returns:
true if connected, false otherwise
Since:
1.00
See Also:
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.

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
Since:
1.00
See Also:
bind(java.lang.String), accept()

recv

public int recv(X25Message msg)
         throws java.io.IOException
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.

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.lang.IllegalArgumentException - if the supplied buffer size is smaller than the current receive buffer size
java.io.IOException - if an error occurs whilst receiving data
Since:
1.00
See Also:
getReceiveBufferSize(), setReceiveBufferSize(int)

send

public int send(X25Message msg)
         throws java.io.IOException
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.

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
Since:
1.00
See Also:
recv(com.ascert.comms.x25.X25Message)

setCallUserData

public void setCallUserData(byte[] cud)
                     throws java.io.IOException
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).

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
Since:
1.00
See Also:
connect(java.lang.String)

setClearCodes

public void setClearCodes(byte[] clr)
                   throws java.io.IOException
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.

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
Since:
1.00
See Also:
close()

setClearUserData

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

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
Since:
1.00
See Also:
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 bind(java.lang.String), accept(), 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.

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
Since:
1.00

setRawFacilities

public void setRawFacilities(byte[] fac)
                      throws java.io.IOException
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.

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

setReceiveBufferSize

public void setReceiveBufferSize(int size)
                          throws java.io.IOException
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 recv(com.ascert.comms.x25.X25Message) calls to avoid an IllegalArgumentException being thrown.

Parameters:
size - the new size for the input buffer. The value must be greater than 0.
Throws:
java.lang.IllegalArgumentException - if the size is less than 0 or greater than the maximum allowed by the driver implementation.
java.io.IOException - if an error occurs setting the raw facilities
Since:
1.00
See Also:
getReceiveBufferSize(), recv(com.ascert.comms.x25.X25Message)

shutdown

public void shutdown()
              throws java.io.IOException
Graceful shutdown of the socket. Since graceful shutdown is not really a standard X.25 feature, some driver implementations may take this method and 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.

Throws:
java.io.IOException - if an error occurs during the shutdown
Since:
1.00
See Also:
close()