Websphere MQ Everyplace

com.ibm.mqe.adapters
Class MQeCommunicationsAdapter

java.lang.Object
  |
  +--com.ibm.mqe.adapters.MQeCommunicationsAdapter
Direct Known Subclasses:
MQeMidpHttpAdapter, MQeTcpipAdapter, MQeTcpipLengthGUIAdapter, MQeUdpipBasicAdapter

public abstract class MQeCommunicationsAdapter
extends java.lang.Object

This is the base class that provides the generic adapter features. It provides abstract classes or implements all methods that communications adapters need to implement. Any new communications adapter must inherit from MQeCommunicationsAdapter.

The documentation supplied for the communications adapters assumes the reader knows and understands the respective protocol being disussed. For instance when discussing an IP protocol we shall not explain how to use the ping command.


Field Summary
static java.lang.String COMMS_ADAPTER_ADDRESS
          String used as a key for the address of the queue manager running a listener in order for the client to connect.
static java.lang.String COMMS_ADAPTER_CLASS
          String used as a key to retrieve the adapter class.
static java.lang.String COMMS_ADAPTER_GROUP_SIZE
          String used as a key for the number of datagram packets to be sent by the a UDP adapter before an acknowledgement is expected.
static java.lang.String COMMS_ADAPTER_HTTP_VERSION
          String used as a key to provide the version of HTTP the MQeTcpipHttpAdapter should use.
static java.lang.String COMMS_ADAPTER_LISTEN
          String used as a key for the listening option for a communciations adapter.
static java.lang.String COMMS_ADAPTER_NONBLOCKING_TIMEOUT
          String used to determine the internal timeout so the adapter may check to see if the current thread has been requested or demanded to be stopped.
static java.lang.String COMMS_ADAPTER_NOPERSIST
          String used as a key for the nopersist option, currently only used for a MQeTcpipLengthAdapter.
static java.lang.String COMMS_ADAPTER_PERSIST
          String used as a key for the persist option for a communications adapter.
static java.lang.String COMMS_ADAPTER_PKTSIZE
          String used as a key for the packet size for the communications adapter.
static java.lang.String COMMS_ADAPTER_PORT
          String used as a key to the port number for an IP adapter.
static java.lang.String COMMS_ADAPTER_RETRIES
          String used as a key for the maximum number of times the communications adapter will retry in the event of a network failure.
static java.lang.String COMMS_ADAPTER_SERVLET
          String used as a key for the servelet name for the HTTP Adapters.
static java.lang.String COMMS_ADAPTER_TIMEOUT
          String used as a key for the communications adapter timeout value.
static java.lang.String COMMS_ADAPTER_VARIANCE
          String used as a key for the network variance value used by the MQeUdpipBasicAdapter as part of its calculations for timeout and retry to allow for variance within the network.
protected  boolean listeningAdapter
          boolean used to indicate whether the adapter should be acting as a listener.
protected  boolean persistentAdapter
          boolean used to indicate whether the adapter should keep the network connection open.
protected  boolean responderAdapter
          boolean used to indicate whether the adapter should be acting as a responder, that is the adapter has been created by a listening adapter in response to an incoming request.
 
Constructor Summary
MQeCommunicationsAdapter()
           
 
Method Summary
abstract  void activate(MQePropertyProvider info)
          Used to activate an adapter and should only ever be called once in the life-time of the object.
abstract  void close()
          Closes an adapter.
static MQeCommunicationsAdapter createNewAdapter(MQePropertyProvider info)
          Creates a new communications adapter.
 boolean isStopDemanded()
          If the return value is true the current thread should stop immediately.
 boolean isStopRequested()
          If the return value is true the current thread should stop as soon as possible.
abstract  void open()
          Opens an adapter for use.
abstract  byte[] read()
          Reads data from the adapter.
abstract  void temporaryClose()
          Closes a non persistent adapter.
abstract  MQeCommunicationsAdapter waitForContact(MQePropertyProvider info)
          Used by the listening adapter to wait for incoming data.
abstract  void writeData(byte[] data)
          Writes a request to the adapter stream.
abstract  void writeResponse(byte[] data)
          Writes response information to the adapter stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COMMS_ADAPTER_CLASS

public static final java.lang.String COMMS_ADAPTER_CLASS
String used as a key to retrieve the adapter class. This value should be provided by the connection definition, if it is not the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.class is checked. If no value is found an exception will be thrown. For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.class=com.ibm.mqe.adapters.MQeTcpipHistoryAdapter

See Also:
Constant Field Values

COMMS_ADAPTER_ADDRESS

public static final java.lang.String COMMS_ADAPTER_ADDRESS
String used as a key for the address of the queue manager running a listener in order for the client to connect. The value should be provided in the connection definition, if no address is present then the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.address is checked. If neither of these avenues provide a value an exception will be thrown. This value is currently not used by a listening adapter. For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.address=127.0.0.1

See Also:
Constant Field Values

COMMS_ADAPTER_PORT

public static final java.lang.String COMMS_ADAPTER_PORT
String used as a key to the port number for an IP adapter. This value should be provided in the connection definition. If the connection definition does not provide this value the the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.port will be checked. If neither of these avenues provides the information the default port of 1881 is used. For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.port=5005

See Also:
Constant Field Values

COMMS_ADAPTER_LISTEN

public static final java.lang.String COMMS_ADAPTER_LISTEN
String used as a key for the listening option for a communciations adapter. This value should be set in the MQeProperties when creating a listener. For instance, listeningAdapterProperties.setProperty(MQeCommunicationsAdapter.COMMS_ADAPTER_LISTEN, "true");

See Also:
MQeProperties, Constant Field Values

COMMS_ADAPTER_PERSIST

public static final java.lang.String COMMS_ADAPTER_PERSIST
String used as a key for the persist option for a communications adapter. If this option is used the underlying network access will not be closed and re-opened between access. This option may not be used in conjunction with the COMMS_ADAPTER_NOPERSIST option which may be used with the MQeTcpipLengthAdapter. The connection definition is initially checked for the MQe_Adapter_PERIST option. If the option is present in the connection definition then "true" is assumed. If the option has not been set in the connection definition the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.persist property is checked. The Java property should be set to either "true" or "false".

See Also:
MQeConnectionAdminMsg.Con_AdapterOptions, Constant Field Values

COMMS_ADAPTER_SERVLET

public static final java.lang.String COMMS_ADAPTER_SERVLET
String used as a key for the servelet name for the HTTP Adapters. If this value is not set in the connection definition the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.servelet is checked.

See Also:
MQeConnectionAdminMsg.Con_AdapterAsciiParm, Constant Field Values

COMMS_ADAPTER_RETRIES

public static final java.lang.String COMMS_ADAPTER_RETRIES
String used as a key for the maximum number of times the communications adapter will retry in the event of a network failure. Currently this value may not be set in the connection definition so if a user value is required to be used the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.retries must be set. The value should represent a positive number. If the configurable value is set to less than zero the default value of 3 is used. For instance, -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.retries=10

See Also:
MQeUdpipBasicAdapter, Constant Field Values

COMMS_ADAPTER_TIMEOUT

public static final java.lang.String COMMS_ADAPTER_TIMEOUT
String used as a key for the communications adapter timeout value. Currently this value may not be set in the connection definition so if a user value is required the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.timeout must be set. The value is set in milliseconds and should represent a positive number. This configurable property will have an affect on the response of the adapter and should be used only if the communications network is properly understood. The value must represet a positive number. If the timeout value is less than the com.ibm.mqe.adapters.MQeCommunicationsAdapter.nonBlockingTimeout then the com.ibm.mqe.adapters.MQeCommunicationsAdapter.nonBlockingTimeout value is used. If no value is set the default timeout of 5000 is used. It should be noted that this value has no affect on the adapters with persistence set to true. This value is particularly important for the MQeUdpipBasicAdapter.

See Also:
For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.timeout=30000, Constant Field Values

COMMS_ADAPTER_PKTSIZE

public static final java.lang.String COMMS_ADAPTER_PKTSIZE
String used as a key for the packet size for the communications adapter. Currently this value may not be set in the connection definition so the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.packetSize is used. This property should be a positive number setting the number of bytes for the packet and should reflect the MTU for the network being used minus approximately 40 bytes to allow for protocol header information. The following MTU sizes for mobile networks were correct at time of publication. Mobitex 512 - set for 480 CDPD 960 - set for 930, or 500 if using a mobile network card For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.packetSize=500

See Also:
Constant Field Values

COMMS_ADAPTER_NOPERSIST

public static final java.lang.String COMMS_ADAPTER_NOPERSIST
String used as a key for the nopersist option, currently only used for a MQeTcpipLengthAdapter. If this option is used the underlying network access will not be closed and re-opened between access. This option may not be used in conjunction with the COMMS_ADAPTER_PERSIST option.

See Also:
for instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.persist=true, Constant Field Values

COMMS_ADAPTER_HTTP_VERSION

public static final java.lang.String COMMS_ADAPTER_HTTP_VERSION
String used as a key to provide the version of HTTP the MQeTcpipHttpAdapter should use. This value must be either 1.0 or 1.1. The default value is version 1.0, if version 1.1 is specified the underlying network access will not be closed and re-opened between access. This option is not available elsewhere. for instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.httpVersion=1.1

See Also:
Constant Field Values

COMMS_ADAPTER_GROUP_SIZE

public static final java.lang.String COMMS_ADAPTER_GROUP_SIZE
String used as a key for the number of datagram packets to be sent by the a UDP adapter before an acknowledgement is expected. Currently this value may not be set in the connection definition so the Java property com.ibm.mqe.adapter.MQeCommunicationsAdapter.groupSize is checked. The value should represent a positive number. For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.groupSize=10

See Also:
Constant Field Values

COMMS_ADAPTER_VARIANCE

public static final java.lang.String COMMS_ADAPTER_VARIANCE
String used as a key for the network variance value used by the MQeUdpipBasicAdapter as part of its calculations for timeout and retry to allow for variance within the network. Currently this value may not be set in the connection definition so the Java property com.ibm.mqe.adapters.MQeCommunicationsAdapter.variance is checked. The value represents milliseconds and if the Java property is not set the default value of 1000 is used.

See Also:
For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.variance=5000, Constant Field Values

COMMS_ADAPTER_NONBLOCKING_TIMEOUT

public static final java.lang.String COMMS_ADAPTER_NONBLOCKING_TIMEOUT
String used to determine the internal timeout so the adapter may check to see if the current thread has been requested or demanded to be stopped. This value is used in conjunction with the com.ibm.mqe.adapters.MQeCommuncationsAdapter.timeout value. Each time the adapter checks the thread the timeout value is decremented by the threadStopCheck value until the timeout value is zero. The value should represent a positive number in milliseconds, if no value is specified or the value specified is less than one second the default value of 1000 is used. For instance -Dcom.ibm.mqe.adapters.MQeCommunicationsAdapter.nonBlockingTimeout=5000

See Also:
Constant Field Values

persistentAdapter

protected boolean persistentAdapter
boolean used to indicate whether the adapter should keep the network connection open. If this variable is set to true then on a call to nonpersistentClose method the network connection will not be closed.


listeningAdapter

protected boolean listeningAdapter
boolean used to indicate whether the adapter should be acting as a listener. If this variable is set to true the adapter will listen on a named port for any incoming requests.


responderAdapter

protected boolean responderAdapter
boolean used to indicate whether the adapter should be acting as a responder, that is the adapter has been created by a listening adapter in response to an incoming request. The rest of the conversation with be conducted by the responder adapter

Constructor Detail

MQeCommunicationsAdapter

public MQeCommunicationsAdapter()
Method Detail

activate

public abstract void activate(MQePropertyProvider info)
                       throws java.lang.Exception

Used to activate an adapter and should only ever be called once in the life-time of the object.

Note : This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Returns:
void
Throws:
java.lang.Exception - a Java lang exception if an error is encountered

close

public abstract void close()
                    throws java.lang.Exception

Closes an adapter. Implementations of this method should ensure that all network and system objects are correctly closed.

Note: This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Returns:
void
Throws:
IOException - - An error occurred whilst closing the communications objects.
java.lang.Exception

open

public abstract void open()
                   throws java.lang.Exception

Opens an adapter for use. Implementations of this method need to take into account this method may be called more than once in the life-time of the adapter.

Note : This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Returns:
void
Throws:
IOException - - I/O error occurred.
java.lang.Exception

read

public abstract byte[] read()
                     throws java.lang.Exception

Reads data from the adapter. The caller will expect a byte array of data to be returned. Any adapter specific information that has been flowed across with network with the data must be removed prior to returning the byte array.

Note : This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Returns:
A byte array containing the data bytes read from the network
Throws:
java.lang.Exception - Error ocurred whilst reading from the network

temporaryClose

public abstract void temporaryClose()
                             throws java.lang.Exception

Closes a non persistent adapter. Implementors should only close the network and system objects if the variable persistentAdapter is false.

Note: This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

At various times in the communications conversation it is desireable to close an adapter's communications resources, but only if it has not been explicitly stated they should remain open.

java.lang.Exception

waitForContact

public abstract MQeCommunicationsAdapter waitForContact(MQePropertyProvider info)
                                                 throws java.lang.Exception

Used by the listening adapter to wait for incoming data.

On the responder side of a communciations conversation this method is responsible for waiting on a named socket for incoming requests. The method should return an instance of the given adapter to conduct the rest of the conversation whilst leaving the listening adapter free to wait for more requests. Implemenations of this method should use MQeCommunicationsAdapter.createNewAdapter to create the new adapter

Returns:
MQeCommunicationsAdapter a communications adapter
Throws:
java.lang.Exception

createNewAdapter

public static final MQeCommunicationsAdapter createNewAdapter(MQePropertyProvider info)
                                                       throws java.lang.Exception

Creates a new communications adapter. This method checks the MQePropertyProvider for the values for COMMS_ADAPTER_CLASS,COMMS_ADAPTER_LISTEN and COMMS_ADAPTER_PERSIST. COMMS_ADAPTER_CLASS is used to retrieve the class of the adapter to load, if COMMS_ADAPTER_LISTEN is returned as "true" then the listeningAdapter variable is set to true, if the COMMS_ADAPTER_PERSIST is returned as "true" then the persistentAdapter variable is set to true.

Note: This entry point is meant to be used by the WebSphere MQ Everyplace object library and classes extending MQeCommunicationsAdapter only.

The MQePropertyProvider is used to obtain all the information required to load the required communications adapter and to correctly activate that adapter

Returns:
MQeCommunicationsAdapter
Throws:
java.lang.Exception - - not just MQeExceptions

writeData

public abstract void writeData(byte[] data)
                        throws java.lang.Exception

Writes a request to the adapter stream.

This method is used to write data to the network.

Note : This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Parameters:
data - Byte array containing the data to be written.
Returns:
void
Throws:
java.lang.Exception - Error ocurred whilst writing to the network

writeResponse

public abstract void writeResponse(byte[] data)
                            throws java.lang.Exception

Writes response information to the adapter stream. Some protocols require specifc header information to be written with the data dependent upon the nature of the data. This method may be used if such a protocol is being used, otherwise, it is suggested that implementors call the writeData(byte[]) method from this method.

This method is used to write data to the network.

Note : This entry point is meant to be used by the WebSphere MQ Everyplace object library not by application programs.

Parameters:
data - Byte array containing the data to be written.
Returns:
void
Throws:
java.lang.Exception - Error ocurred whilst writing to the network.

isStopRequested

public boolean isStopRequested()

If the return value is true the current thread should stop as soon as possible.

Returns:
boolean

isStopDemanded

public boolean isStopDemanded()

If the return value is true the current thread should stop immediately.

Returns:
boolean

Websphere MQ Everyplace