com.stc.connector.webspheremqadapter.message
Interface IMqOtd

public interface IMqOtd

The WebSphere MQ Object Type Definition, the access model to WebSphere MQ queue managers, queues, and messages. This interface describes the eWay OTD structure exposed to Java Collaborations that use the WebSphere MQ eWay in non-receive (non-trigger) mode.

Version:

$Revision: 1.6 $

Method Summary

void	accessQueue(java.lang.String queueName) Call this to access a queue on the current queue manager, to access messages.
void	accessQueue(java.lang.String queueName, java.lang.String qmgrName) Call this to access a queue on a remote queue manager.
void	backout() Tells the current queue manager that all gets and puts since the last syncpoint are to be backed out.
void	commit() Tells the current queue manager that your Collaboration has reached a syncpoint and that all gets and puts that have occurred since the last syncpoint are to be made permanent.
void	connectToQueueManager(java.lang.String sQueueMgrName, java.lang.String sHost, int nPort, java.lang.String sChannel, java.lang.String sUserID, java.lang.String sPwd) At OTD creation time, the queue manager specified in the configuration will be automatically connected to (and be set as the current queue manager).
javax.resource.spi.LocalTransaction	createLocalTransactionSupport()
void	get() Get a message from the current queue.
int	getCharacterSet() Returns the CCSID (coded character set ID) of the current queue manager's codeset.
int	getCurrentDepth() Get the number of messages available in the current queue.
IGMO	getGMO() Access to the GMO branch of this OTD.
int	getMaximumDepth() Gets the maximum number of messages that can exist on the current queue.
int	getMaximumMessageLength() Gets the maximum length of application data that can exist in any one message on the current queue.
int	getMaximumPriority() Returns the maximum message priority supported by the current queue manager.
IMessage	getMessage() Accesses the Message branch of the OTD.
IPMO	getPMO() Access to the PMO branch of this OTD.
IQueue	getQueue() Accesses the Queue branch of the OTD.
QueueAccessOptions	getqueueAccessOptions() Retrieve the access-options data structure that specifies the options that control the opening of the queue.
QueueAccessOptions	getQueueAccessOptions() Retrieve the access-options data structure that specifies the options that control the opening of the queue.
void	getWithOptions() Get a message from the current queue.
boolean	isQueueMgrConnected() Determines whether the the current queue manager is still connected to WebSphere MQ.
boolean	isTransactionInProgress()
void	newMessage() Allows the user to destroy then recreate the Message object.
void	put() Put a message into the current queue.
void	putWithOptions() Put a message into the current queue.
void	selectQueue(java.lang.String queueName) Select one of the previously accessed queues and make it the current queue.
void	selectQueueManager(java.lang.String queueMgrName) Selects one of the queue managers you have previously connected to.

Method Detail

getQueue

IQueue getQueue()

Accesses the Queue branch of the OTD.

Parameters:

None.

Returns:

IQueue - Returns Queue sub-OTD.

Throws:

None.

getMessage

IMessage getMessage()

Accesses the Message branch of the OTD.

Parameters:

None.

Returns:

IMessage - Returns Message sub-OTD.

Throws:

None.

newMessage

void newMessage()
                throws com.stc.connector.appconn.common.ApplicationConnectionException

Allows the user to destroy then recreate the Message object. This is necessary if you want to do a get after you've done a get or have modified the message.

Parameters:

None.

Throws:

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

connectToQueueManager

void connectToQueueManager(java.lang.String sQueueMgrName,
                           java.lang.String sHost,
                           int nPort,
                           java.lang.String sChannel,
                           java.lang.String sUserID,
                           java.lang.String sPwd)
                           throws MQAgentConnectionException,
                                  com.stc.connector.appconn.common.ApplicationConnectionException

At OTD creation time, the queue manager specified in the configuration will be automatically connected to (and be set as the current queue manager). This may be the one and only queue manager needed in the collaboration. If there is a need to connect to another queue manager, use this method.

Using this method connects to a queue manager and selects it as the current queue manager. There is a concept of a "current queue manager". The current queue manager is that queue manager that is the recipient of all the queue related calls. It is set in one of two ways. Either by this method, or the selectQueueManager method.

Important: this should only be called in Non-Transactional mode. If you are in XA compliant mode, there must be exactly one queue manager connection and that will be the one specified in the configuration. An attempt to connect to another queue manager in XA mode will cause an exception to be thrown.

Parameters:

sQueueMgrName - name of queue manager

sHost - name of host on which the queue manager resides

nPort - port of the host on which queue manager is bound

sChannel - channel to use

sUserID - user ID; may be blank or null.

sPwd - password; may be blank or null.

Throws:

MQAgentConnectionException - if there is a problem connecting to the queue manager.

com.stc.connector.appconn.common.ApplicationConnectionException - if the current connection context is no longer usable because it has been invalidated.

See Also:

selectQueueManager(String)

selectQueueManager

void selectQueueManager(java.lang.String queueMgrName)
                        throws NoSuchQueueManagerException,
                               com.stc.connector.appconn.common.ApplicationConnectionException

Selects one of the queue managers you have previously connected to. Sets that queue manager as the current queue manager. See also the connectToQueueManager method. Should only be called in non transactional mode. Only needs to be called if you have connected to more than one queue manager.

Parameters:

queueMgrName - Name of the queue manager to select.

Throws:

NoSuchQueueManagerException - Thrown if the named queue manager does not exist.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the object is no longer usable because it has been invalidated.

See Also:

connectToQueueManager(String, String, int, String, String, String)

isQueueMgrConnected

boolean isQueueMgrConnected()
                            throws com.stc.connector.appconn.common.ApplicationConnectionException

Determines whether the the current queue manager is still connected to WebSphere MQ.

Parameters:

None.

Returns:

Boolean - Returns true if still connected; otherwise false.

Throws:

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

getCharacterSet

int getCharacterSet()
                    throws MQException,
                           com.stc.connector.appconn.common.ApplicationConnectionException

Returns the CCSID (coded character set ID) of the current queue manager's codeset.

Parameters:

None.

Returns:

int - Returns an integer specifying the CCSID.

Throws:

MQException - Thrown if the current queue manager is disconnected.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

getMaximumPriority

int getMaximumPriority()
                       throws MQException,
                              com.stc.connector.appconn.common.ApplicationConnectionException

Returns the maximum message priority supported by the current queue manager. Range is from lowest (zero) to the value returned.

Parameters:

None.

Returns:

int - Returns an integer specifying the maximum priority.

Throws:

MQException - Thrown if the current queue manager is disconnected.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

commit

void commit()
            throws MQException,
                   com.stc.connector.appconn.common.ApplicationConnectionException

Tells the current queue manager that your Collaboration has reached a syncpoint and that all gets and puts that have occurred since the last syncpoint are to be made permanent. Note that this should NOT be called in XA compliant mode. (In XA mode, eGate is acting as the transaction coordinator). If this is called in XA mode it will throw an exception.

Parameters:

None.

Throws:

MQException - Thrown if the commit fails for any reason other than being in XA mode.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

java.lang.IllegalStateException - Thrown if the commit fails because of XA mode.

backout

void backout()
             throws MQException,
                    com.stc.connector.appconn.common.ApplicationConnectionException

Tells the current queue manager that all gets and puts since the last syncpoint are to be backed out. As in commit, this should NOT be called in XA mode since in XA mode eGate is acting as the transaction coordinator. An attempt to call it in XA mode will cause an exception to be thrown.

Parameters:

None.

Throws:

MQException - Thrown if the backout fails for any reason other than being in XA mode.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

java.lang.IllegalStateException - Thrown if the backout fails because of XA mode.

getGMO

IGMO getGMO()

Access to the GMO branch of this OTD. Retained for backward compatibility. New collaborations should use IQueue.getGMO() instead.

Parameters:

None.

Returns:

IGMO - Returns the GMO sub-OTD

Throws:

None.

getPMO

IPMO getPMO()

Access to the PMO branch of this OTD. Retained for backward compatibility. New collaborations should use IQueue.getPMO() instead.

Parameters:

None.

Returns:

IPMO - Returns the PMO sub-OTD

Throws:

None.

getqueueAccessOptions

QueueAccessOptions getqueueAccessOptions()

Retrieve the access-options data structure that specifies the options that control the opening of the queue. Retained for backward compatibility. New collaborations should use IQueue.getqueueAccessOptions() instead.

Parameters:

None.

Returns:

QueueAccessOptions - Returns the QueueAccessOptions object describing the queue access options in effect.

Throws:

None.

getQueueAccessOptions

QueueAccessOptions getQueueAccessOptions()

Retrieve the access-options data structure that specifies the options that control the opening of the queue. Retained for backward compatibility. New collaborations should use IQueue.getqueueAccessOptions() instead.

Parameters:

None.

Returns:

QueueAccessOptions - Returns the QueueAccessOptions object describing the queue access options in effect.

Throws:

None.

accessQueue

void accessQueue(java.lang.String queueName)
                 throws MQAgentConnectionException,
                        com.stc.connector.appconn.common.ApplicationConnectionException

Call this to access a queue on the current queue manager, to access messages. The accessed queue becomes the current queue; this is similar to the concept of a current queue manager.

This method is retained for backward compatibility. New collaborations should use IQueue.accessQueue(java.lang.String) instead.

Parameters:

queueName - Name of the queue to access on the current queue manager.

Throws:

MQAgentConnectionException - Thrown if there is a problem accessing the queue.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

See Also:

selectQueue(String), MQOtd#selectQueueManager(String)

accessQueue

void accessQueue(java.lang.String queueName,
                 java.lang.String qmgrName)
                 throws MQAgentConnectionException,
                        com.stc.connector.appconn.common.ApplicationConnectionException

Call this to access a queue on a remote queue manager. The accessed queue becomes the current queue; this is similar to the concept of a current queue manager.

Note:The queue manager named in this call is not added to the internal list of selectQueueManager(String) selectable} queue managers.

This method is retained for backward compatibility. New collaborations should use IQueue.accessQueue(String, String) instead.

Parameters:

queueName - Name of the queue to access on the current queue manager.

qmgrName - Name of the remote queue manager which owns the named queue.

Throws:

MQAgentConnectionException - Thrown if there is a problem accessing the queue.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

See Also:

selectQueue(String), MQOtd#selectQueueManager(String)

selectQueue

void selectQueue(java.lang.String queueName)
                 throws NoSuchQueueException,
                        MQAgentConnectionException,
                        com.stc.connector.appconn.common.ApplicationConnectionException

Select one of the previously accessed queues and make it the current queue. All queue-related operations operate on the current queue. related operations operate on that current queue.

This method is retained for backward compatibility. New collaborations should use IQueue.selectQueue(java.lang.String) instead.

Parameters:

queueName - Name of the queue to select on the current queue manager.

Throws:

NoSuchQueueException - Thrown if the specified queue is not found.

MQAgentConnectionException - Thrown if there is a connection error.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

See Also:

accessQueue(String)

get

void get()
         throws MQException,
                com.stc.connector.appconn.common.ApplicationConnectionException

Get a message from the current queue. The default GetMessageOptions are used, whatever they may be (as is dictated by WebSphere mQ). The retrieved message is stored in the Message part of the WebSphere MQ OTD.

This method is retained for backward compatibility. New collaborations should use IQueue.get() instead.

Parameters:

None.

Throws:

MQException - Thrown if the get fails.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

getWithOptions

void getWithOptions()
                    throws MQException,
                           com.stc.connector.appconn.common.ApplicationConnectionException

Get a message from the current queue. The GetMessageOptions set in this OTD's GMO part are used. The retrieved message is stored in the Message part of the WebSphere MQ OTD.

This method is retained for backward compatibility. New collaborations should use IQueue.getWithOptions() instead.

Parameters:

None.

Throws:

MQException - Thrown if the get fails.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

put

void put()
         throws MQException,
                com.stc.connector.appconn.common.ApplicationConnectionException

Put a message into the current queue. The default PutMessageOptions are used, whatever they may be. The message to be put is retrieved from the Message part of the WebSphere MQ OTD, so it must be populated before calling this method.

This method is retained for backward compatibility. New collaborations should use IQueue.put() instead.

Parameters:

None.

Throws:

MQException - Thrown if the put fails

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

putWithOptions

void putWithOptions()
                    throws MQException,
                           com.stc.connector.appconn.common.ApplicationConnectionException

Put a message into the current queue. The PutMessageOptions set in this OTD's PMO part are used. The message to be put is retrieved from the Message part of the WebSphere MQ OTD, so it must be populated before calling this method.

This method is retained for backward compatibility. New Collaborations should use IQueue.putWithOptions() instead.

Parameters:

None.

Throws:

MQException - Thrown if the put fails

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

getCurrentDepth

int getCurrentDepth()
                    throws MQException,
                           com.stc.connector.appconn.common.ApplicationConnectionException

Get the number of messages available in the current queue.

This method is retained for backward compatibility. New collaborations should use IQueue.getCurrentDepth() instead.

Parameters:

None.

Returns:

int - Returns the number of messages.

Throws:

MQException - Thrown if the query fails.

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

getMaximumDepth

int getMaximumDepth()
                    throws MQException,
                           com.stc.connector.appconn.common.ApplicationConnectionException

Gets the maximum number of messages that can exist on the current queue.

This method is retained for backward compatibility. New collaborations should use IQueue.getMaximumDepth() instead.

Parameters:

None.

Returns:

int - Returns the number of messages.

Throws:

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

MQException - Thrown if the query fails.

getMaximumMessageLength

int getMaximumMessageLength()
                            throws MQException,
                                   com.stc.connector.appconn.common.ApplicationConnectionException

Gets the maximum length of application data that can exist in any one message on the current queue.

This method is retained for backward compatibility. New collaborations should use IQueue.getMaximumMessageLength() instead.

Parameters:

None.

Returns:

int - Returns the maximum application data size in a message.

Throws:

com.stc.connector.appconn.common.ApplicationConnectionException - Thrown if the current queue manager is no longer usable because it has been invalidated.

MQException - Thrown if the query fails.

isTransactionInProgress

boolean isTransactionInProgress()

createLocalTransactionSupport

javax.resource.spi.LocalTransaction createLocalTransactionSupport()