com.ibm.MQIsdp
Class ClientMQIsdp

java.lang.Object
  |
  +--com.ibm.MQIsdp.ClientMQIsdp
All Implemented Interfaces:
com.ibm.MQIsdp.MQIpdpClientCallback, MQIsdpAdvancedCallback, MQIsdpSimpleCallback

public class ClientMQIsdp
extends java.lang.Object
implements com.ibm.MQIsdp.MQIpdpClientCallback

The ClientMQIsdp Java class provides an API for the WebSphere MQ Integrator MQIsdp protocol.


Constructor Summary
ClientMQIsdp(java.lang.String server, int port)
          The ClientMQIsdp constructor.
 
Method Summary
 int connect(java.lang.String clientid, boolean cleanstart, short keepalive)
          Connect to the WebSphere MQ Integrator broker.
 int connect(java.lang.String clientid, boolean cleanstart, short keepalive, java.lang.String willtopic, int willQoS, java.lang.String willmsg, boolean willretain)
          Connect to the WebSphere MQ Integrator broker.
 void connectionLost()
          Default callback method invoked when the MQIsdp client TCP/IP connection is unexpectedly terminated.
 void disconnect()
          Disconnect from the WebSphere MQ Integrator broker.
 int getBlockingTimeout()
          Method to query the number seconds the MQIsdp client waits for waits for a blocking API methods to complete.
 int getPortNumber()
          Method to query the IP port number to which the MQIsdp client is connected.
 int getRetry()
          Method to return the interval at which message delivery will be retried in the event of acknowledgements not being received.
 java.lang.String getServerAddress()
          Method to query the IP address or hostname to which the MQIsdp client is connected.
 boolean isConnected()
          Method to the indicate the connection state of the MQIsdp client.
 void notifyAck(int ref, int msgid)
          This method is required as part of the MQIsdp protocol implementation, but should not be called by users of this class.
 boolean outstanding(int aMsgId)
           
 void ping()
          Send a MQIsdp ping message to indicate that the MQIsdp client is alive.
 int publish(java.lang.String thisTopic, byte[] thisMessage, int thisQoS, boolean retained)
          Publish a message on a particular topic to the WebSphere MQ Integrator broker.
 void publishArrived(java.lang.String topic, byte[] message, int QoS, boolean retained)
          Default callback method invoked when a publication arrives for this MQIsdp client.
 void published(int aMsgId)
          Default callback method invoked when a message is successfully published from the MQIsdp client.
 void registerAdvancedHandler(com.ibm.MQIsdp.MQIsdpAdvancedCallback aHandler)
          Register an advanced callback handler as described by the MQIsdpAdvancedCallback interface
 void registerSimpleHandler(com.ibm.MQIsdp.MQIsdpSimpleCallback aHandler)
          Register an simple callback handler as described by the MQIsdpSimpleCallback interface
 void setBlockingTimeout(int timeout)
          Set the time limit which the MQIsdp client should wait for a blocking API method to complete.
 void setRetry(int retryNum)
          Set the retry interval at which the MQIsdp client should retry any messages that have not been acknowledged by the broker.
 void startTrace()
          Start tracing the MQIsdp Java client.
 void stopTrace()
          Stop tracing the MQIsdp Java client.
 byte[] subscribe(java.lang.String[] theseTopics, int[] theReqQoS)
          Subscribe to one or more topics.
 void terminate()
          This method terminates all running threads in the ClientMQIsdp instance.
 int unsubscribe(java.lang.String[] theseTopics)
          Unsubscribe from one or more topics.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ClientMQIsdp

public ClientMQIsdp(java.lang.String server,
                    int port)
             throws java.lang.Exception
The ClientMQIsdp constructor.

Parameters:
server - The IP address or hostname of the WebSphere MQ Integrator broker.
port - The IP port number of the SCADAInput node on the WebSphere MQ Integrator broker.
Method Detail

startTrace

public void startTrace()
                throws java.lang.Exception
Start tracing the MQIsdp Java client. The trace will be produced in a binary format in the current directory. The trace file is called mqe0.trc. Execute java -jar MQIsdpTraceFormat.jar mqe0.trc > a.out to format the trace into a readable format. Tracing is currently only available for the J2SE implementation.

java.lang.Exception

stopTrace

public void stopTrace()
Stop tracing the MQIsdp Java client. This will close the trace file in the current directory.


registerAdvancedHandler

public void registerAdvancedHandler(com.ibm.MQIsdp.MQIsdpAdvancedCallback aHandler)
Register an advanced callback handler as described by the MQIsdpAdvancedCallback interface

Parameters:
aHandler - Object that will handle the advanced (and simple) callback events.

registerSimpleHandler

public void registerSimpleHandler(com.ibm.MQIsdp.MQIsdpSimpleCallback aHandler)
Register an simple callback handler as described by the MQIsdpSimpleCallback interface

Parameters:
aHandler - Object that will handle the simple callback events.

connect

public int connect(java.lang.String clientid,
                   boolean cleanstart,
                   short keepalive)
            throws java.lang.Exception
Connect to the WebSphere MQ Integrator broker.

Parameters:
clientid - A character identfier which must be unique across all MQIsdp connections to the WebSphere MQ Integrator broker.
cleanstart - A boolean indicating if the broker should cleanup if the TCP/IP connection unexpectedly terminates. This will leave the broker in a state as though the client had never connected.
USE WITH CARE.
In the event of a TCP/IP error the broker will delete all subscriptions this client registered and delete all publications awaiting delivery to this client.
keepalive - An interval in seconds that the broker should use to determine if the MQIsdp client is still alive. If data is not received within this interval the broker will assume the client has terminated and disconnect it, cleaning up if the clean start flag was specified. If the connection is inactive for keepalive seconds this client library will automatically ping the connection to keep it alive until an explicit disconnect is issued.
Returns:
The return code from the WebSphere MQ Integrator broker in response to the connect or -1 on error.
java.lang.Exception

connect

public int connect(java.lang.String clientid,
                   boolean cleanstart,
                   short keepalive,
                   java.lang.String willtopic,
                   int willQoS,
                   java.lang.String willmsg,
                   boolean willretain)
            throws java.lang.Exception
Connect to the WebSphere MQ Integrator broker.

Parameters:
clientid - As above
cleanstart - As above.
keepalive - As above.
willtopic - In the event of the MQIsdp connection unexpectedly terminating the broker will publish a 'Last Will and Testament' message on this topic.
willQoS - Publish the last will and testament message at this Quality of Service (0,1 or 2).
willmsg - In the event of the MQIsdp connection unexpectedly terminating the broker will publish this data on the above topic.
willretain - A boolean indicating if the 'Last Will and Testament' message should be a retained publication.
Returns:
The return code from the WebSphere MQ Integrator broker in response to the connect or -1 on error.
java.lang.Exception

connectionLost

public void connectionLost()
                    throws java.lang.Exception
Default callback method invoked when the MQIsdp client TCP/IP connection is unexpectedly terminated. This method may be overridden or a simple/advanced callback handler may be registered if the application needs to detect this event.
Default behaviour is to throw an exception which will stop any further API calls succeeding. An application should reconnect to send and receive any further data. If cleanStart has been specified on connect then all inflight data will be lost and the broker will automatically unsubscribe the client from all topics. Without the cleanStart flag the protocol will continue sending any inflight data when the client next connects. Topic subscriptions will remain active in the broker.
If an alternative method is supplied (which is recommended) it should attempt to reconnect using the connect method. If the cleanstart flag was specified then this method should also resubscribe for all topics that the client is interested in receiving. If the connection lost method is unable to reconnect then it should throw an exception. This exception will then be thrown by the API whenever a publish or subscribe method is called to indicate that there is a problem.

Specified by:
connectionLost in interface MQIsdpSimpleCallback
java.lang.Exception

disconnect

public void disconnect()
                throws java.lang.Exception
Disconnect from the WebSphere MQ Integrator broker.

java.lang.Exception

getBlockingTimeout

public int getBlockingTimeout()
Method to query the number seconds the MQIsdp client waits for waits for a blocking API methods to complete. Blocking API methods are subscribe and unsubscribe.

Returns:
The number of seconds the MQIsdp client waits. Default 30 seconds.

getServerAddress

public java.lang.String getServerAddress()
Method to query the IP address or hostname to which the MQIsdp client is connected.

Returns:
The IP address or hostname to which the MQIsdp client will connect / is connected.

getPortNumber

public int getPortNumber()
Method to query the IP port number to which the MQIsdp client is connected.

Returns:
The IP port number to which the MQIsdp client will connect / is connected.

getRetry

public int getRetry()
Method to return the interval at which message delivery will be retried in the event of acknowledgements not being received.

Returns:
The interval in seconds at which message deliveries will be retried.

isConnected

public boolean isConnected()
Method to the indicate the connection state of the MQIsdp client.

Returns:
A boolean indicating if the MQIsdp client is successfully connect to a WebSphere MQ Integrator broker at this time.

notifyAck

public void notifyAck(int ref,
                      int msgid)
This method is required as part of the MQIsdp protocol implementation, but should not be called by users of this class.

Specified by:
notifyAck in interface com.ibm.MQIsdp.MQIpdpClientCallback

outstanding

public boolean outstanding(int aMsgId)
Parameters:
aMsgId - A caller may query the delivery status of a message by supplying the message identifier returned from the publish method.
Returns:
A boolean indicating if the message identified by aMsgId has been successfully delivered to the WebSphere MQ Integrator broker.

ping

public void ping()
          throws java.lang.Exception
Send a MQIsdp ping message to indicate that the MQIsdp client is alive. Sending of ping messages within the keepalive interval is automatically handled by the MQIsdp client library. However an application can also initiate a ping exchange if it so desires.

java.lang.Exception

publish

public int publish(java.lang.String thisTopic,
                   byte[] thisMessage,
                   int thisQoS,
                   boolean retained)
            throws java.lang.Exception
Publish a message on a particular topic to the WebSphere MQ Integrator broker.

Parameters:
thisTopic - A string containing the topic on which the associated data should be published.
thisMessage - A byte array containing the data to be published on the above topic.
thisQoS - The Quality of Service which the message should be delivered at.
  • QoS 0 - Delivered at most once ( 0 or 1 times)
  • QoS 1 - Delivered at least once ( 1 or more times)
  • QoS 2 - Delivered only once
retained - - Should this be a retained publication?
Returns:
The message identifier of the published message.
java.lang.Exception

publishArrived

public void publishArrived(java.lang.String topic,
                           byte[] message,
                           int QoS,
                           boolean retained)
Default callback method invoked when a publication arrives for this MQIsdp client. This method may be overridden or a simple/advanced callback handler may be registered if the application needs to detect this event.

NOTE:
Any implementation of this method should NOT call any of the other API methods as this will cause a deadlock. Blocking for a significant amount of time is also not advised. If API calls or blocking are required in this method, then the method should start up a new thread to do the work.

Specified by:
publishArrived in interface MQIsdpSimpleCallback
Parameters:
topic - The topic associated with the received publication.
message - A byte array containing the publication data received.
QoS - The quality of service at which the message was delivered.
retained - Is this a retained publication?

published

public void published(int aMsgId)
Default callback method invoked when a message is successfully published from the MQIsdp client. This method may be overridden or an advanced callback handler may be registered if the application needs to detect this event.

Specified by:
published in interface MQIsdpAdvancedCallback
Parameters:
aMsgId - The message identifier of the message successfully puyblished from this MQIsdp client.

setBlockingTimeout

public void setBlockingTimeout(int timeout)
Set the time limit which the MQIsdp client should wait for a blocking API method to complete. The blocking API methods are subscribe and unsubscribe.

Parameters:
timeout - The timeout interval in seconds. Default 30 seconds.

setRetry

public void setRetry(int retryNum)
Set the retry interval at which the MQIsdp client should retry any messages that have not been acknowledged by the broker. The message types are subscribe, unsubscribe and publish (QoS 1 or 2).

The minimum retry interval that can be set is 10 seconds. If an attempt is made to set a value less than 10 seconds, then the API will assume a retry interval of 10 seconds.

Parameters:
retryNum - The retry interval in seconds. Default 10 seconds.

terminate

public void terminate()
This method terminates all running threads in the ClientMQIsdp instance. This method should be called after disconnect, when the CLientMQIsdp instance has been finished with. Once terminate has been called any further method calls on the ClientMQIsdp instance will fail.


subscribe

public byte[] subscribe(java.lang.String[] theseTopics,
                        int[] theReqQoS)
                 throws java.lang.Exception
Subscribe to one or more topics.

Parameters:
theseTopics - An array of topics. Each topic is a character string.
Returns:
A byte array containing the Quality of Service that was granted by the broker for each topic. The granted Quality of Service is associated with the sent topic by array index.
Returns null if the subscribe outcome is unknown. Be aware in this case that the subscription may be successfully registered with the broker, but a response was not received, possibly due to network errors.
java.lang.Exception

unsubscribe

public int unsubscribe(java.lang.String[] theseTopics)
                throws java.lang.Exception
Unsubscribe from one or more topics.

Parameters:
theseTopics - An array of topics. Each topic is a character string.
Returns:
-1 on if unsubscribe outcome is unknown. Be aware in this case that the unsubscribe may have been successfully processed by the broker, but a response was not received, possibly due to network errors.
java.lang.Exception