IMSInteraction

java.lang.Object
- com.ibm.connector2.ims.ico.IMSInteraction

public class IMSInteraction
extends java.lang.Object

A component uses an instance of this class to perform an interaction with IMS via IMS Connect. A typical interaction is running an IMS transaction. For example, an application that uses the Common Client Interface (CCI) would use an Interaction instance to run an IMS transaction as follows:

 Connection connection = cf.getConnection();

 // Create an interaction instance to use to submit the IMS transaction.
  IMSInteraction interaction = (IMSInteraction) connection.createInteraction();

  // Set interactionSpec properties.
   IMSInteractionSpec iSpec = new IMSInteractionSpec();
   iSpec.setInteractionVerb(IMSInteractionSpec.SYNC_SEND_RECEIVE);
   ...
   // Create the input record
    ...

    // Send the input message to IMS to run the transaction and
     // return the output message.
      interaction.execute(iSpec, input, output);

A CCI application can also use an Interaction instance to send a request asnychronously to IMS OTMA to retrieve a queued output message. The message was queued when the output of a Commit Mode 0 interaction on a dedicated persistent socket could not be delivered.

      // Get a factory to create dedicated persistent socket connection
       IMSConnectionFactory cf = null;
       IMSManagedConnectionFactory mcf = new IMSManagedConnectionFactory();
       mcf.setHostName("myHostName");
       mcf.setPortNumber(new Integer(9999));
       mcf.setDataStoreName("myIMS");
       mcf.setCM0Dedicated(new Boolean("TRUE"));
       cf = (IMSConnectionFactory) mcf.createConnectionFactory();

       // Create a connection for use by clientID "CLIENT01"
        IMSConnectionSpec aCSpec = new IMSConnectionSpec();
        aCSpec.setClientID("CLIENT01");
        connection = connectionFactory.getConnection(aCSpec);

        // Create an interaction instance to use to retrieve the asynchronous output message.
         IMSInteraction interaction = (IMSInteraction) connection.createInteraction();

         // Set interactionSpec properties.
          IMSInteractionSpec iSpec = new IMSInteractionSpec();
          iSpec.setInteractionVerb(IMSInteractionSpec.SYNC_RECEIVE_ASYNCOUTPUT);
          iSpec.setCommitMode(0);
          ...
          // Send a request to IMS to return the asynchronous output message.
           interaction.execute(iSpec, null, output);

A CCI application can also use an Interaction instance to send a message to IMS OTMA to end a conversation:

           // Note: conn is a handle to the connection used to carry on the
            // conversation.  An application must use the same connection with IMS Connect
             // (TCP/IP socket or Local Option connection) for all the iterations
              // of a conversation.
               IMSInteraction interaction = (IMSInteraction) conn.createInteraction();

               // Set interactionSpec properties.
                IMSInteractionSpec iSpec = new IMSInteractionSpec();
                iSpec.setInteractionVerb(IMSInteractionSpec.SYNC_END_CONVERSATION);
                ...
                // Send a message to end the conversation
                 interaction.execute(iSpec, null);

See Also:: #execute(InteractionSpec, Record, Record), IMSInteractionSpec, IMSConnection.createInteraction()

Constructor Summary

Constructors
Constructor and Description

IMSInteraction(IMSConnection aConnection)
Creates an IMSInteraction instance for use in an interaction with IMS via IMS Connect.

Constructors
Constructor and Description
`IMSInteraction(IMSConnection aConnection)` Creates an IMSInteraction instance for use in an interaction with IMS via IMS Connect.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearWarnings()` Clears all the warnings reported by this IMSInteraction instance.
`void`	`close()` Releases all resources maintained by IMS Connector for Java for the IMSInteraction instance.
`javax.resource.cci.Record`	`execute(javax.resource.cci.InteractionSpec interactionSpec, javax.resource.cci.Record input)` Deprecated. The execute(javax.resource.cci.InteractionSpec iSpec, javax.resource.cci.Record input) method is deprecated. You should use the execute(javax.resource.cci.InteractionSpec iSpec, javax.resource.cci.Record input, javax.resource.cci.Record output) method for all your interactions with IMS. If IMS does not return an output for an interaction, your execute method should return a null output record. Performs an interaction with IMS OTMA via IMS Connect. This variant of the execute method is used by applications that use the Common Client Interface (CCI) to send a request to IMS OTMA to force the end of an IMS conversation. In this case, the interactionVerb property of the IMSInteractionSpec instance is set to SYNC_END_CONVERSATION, and the input Record instance is ignored.
`boolean`	`execute(javax.resource.cci.InteractionSpec interactionSpec, javax.resource.cci.Record input, javax.resource.cci.Record output)` Performs an interaction with IMS via IMS Connect.
`javax.resource.cci.Connection`	`getConnection()` Returns the connection associated with this interaction.
`javax.resource.cci.RecordFactory`	`getRecordFactory()` Returns a RecordFactory object that is used to create generic Record instances.
`javax.resource.cci.ResourceWarning`	`getWarnings()` Gets the first ResourceWarning from the chain of warnings associated with this Interaction instance.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - IMSInteraction
```
public IMSInteraction(IMSConnection aConnection)
```
    Creates an IMSInteraction instance for use in an interaction with IMS via IMS Connect.
    
    Parameters:
    aConnection - The active connection to IMS Connect that is associated with this interaction.
    See Also:
    IMSConnection.createInteraction()
- Method Detail
  - clearWarnings
```
public void clearWarnings()
                   throws javax.resource.ResourceException
```
    Clears all the warnings reported by this IMSInteraction instance. After a call to this method, the method getWarnings returns null until a new warning is reported for this IMSInteraction instance.
    Note: Currently, IMS TM Resource Adapter does not issue any warnings.
    
    Throws:
    
    javax.resource.ResourceException
  - close
```
public void close()
           throws javax.resource.ResourceException
```
    Releases all resources maintained by IMS Connector for Java for the IMSInteraction instance. The close of an IMSInteraction instance does not close the associated IMSConnection instance.
    
    Throws:
    
    javax.resource.ResourceException -
    Note: The derived exception javax.resource.spi.IllegalStateException is thrown by close() when the close method is invoked on an invalid (already closed) interaction.
  - execute
```
public javax.resource.cci.Record execute(javax.resource.cci.InteractionSpec interactionSpec,
                                javax.resource.cci.Record input)
                                  throws javax.resource.ResourceException
```
    Deprecated. The execute(javax.resource.cci.InteractionSpec iSpec, javax.resource.cci.Record input) method is deprecated. You should use the execute(javax.resource.cci.InteractionSpec iSpec, javax.resource.cci.Record input, javax.resource.cci.Record output) method for all your interactions with IMS. If IMS does not return an output for an interaction, your execute method should return a null output record. Performs an interaction with IMS OTMA via IMS Connect. This variant of the execute method is used by applications that use the Common Client Interface (CCI) to send a request to IMS OTMA to force the end of an IMS conversation. In this case, the interactionVerb property of the IMSInteractionSpec instance is set to SYNC_END_CONVERSATION, and the input Record instance is ignored.
    Parameters:
    interactionSpec - An IMSInteractionSpec instance containing the properties of this interaction.
    input - The input record for this interaction; ignored for SYNC_END_CONVERSATION.
    
    Throws:
    javax.resource.ResourceException -
    
    The execute() method was invoked on an invalid interaction. The interaction or its associated connection were closed.
    Note: The derived exception javax.resource.spi.IllegalStateException is thrown in this case.
    The interactionSpec is null or not of type IMSInteractionSpec. The exception javax.resource.ResourceException is thrown in this case.
    See Also:
    IMSInteractionSpec
  - execute
```
public boolean execute(javax.resource.cci.InteractionSpec interactionSpec,
              javax.resource.cci.Record input,
              javax.resource.cci.Record output)
                throws javax.resource.ResourceException
```
    Performs an interaction with IMS via IMS Connect. For example, this variant of the execute method can be used run a simple IMS transaction on a Local Option or shareable persistent socket connection by invoking the execute method with the following:
    - An IMSInteractionSpec instance containing:
      
      the interactionVerb property set to SYNC_SEND_RECEIVE (1)
      the imsRequestType property set to IMS_REQUEST_TYPE_IMS_TRANSACTION (1)
      the commitMode property set to send-then-commit (1)
      
      or
      
      (for shareable persistent socket connections only) the commitMode property set to commit-then-send (0)
    - a Record instance containing the input data of the IMS transaction
    - a Record instance for receipt of the output data of the IMS transaction
    Both non-conversational and conversational IMS transactions can be run using this variant of the execute method.
    This variant of the execute method can also be used on dedicated persistent socket connections to run an IMS transaction using Commit Mode 0, retrieve queued output messages from Commit Mode 0 interactions, or retrieve messages that were inserted to alternate Program Contorl Blocks (PCBs).
    For example, to retrieve undelivered output from a Commit Mode 0 interaction on a socket connection dedicated to "CLIENT01", the execute method is invoked with:
    - An IMSInteractionSpec instance containing:
      
      the interactionVerb property set to SYNC_RECEIVE_ASYNCOUTPUT (4)
      the commitMode property set to commit-then-send (0)
    - a null for the input Record instance
    - a Record instance for receipt of the output message
    Note: For interactions on a dedicated persistent socket connection the Interaction instance is obtained from a connection that is dedicated to a particular clientID. The value for this clientID is provided in the IMSConnectionSpec object passed to the getConnection() method used to obtain the connection.
    
    For Commit Mode 0 interactions that use interactionVerb = SYNC_SEND_RECEIVE on a dedicated persistent socket connection, clientID identifies the queue to which the output message will be queued if it cannot be delivered to the client. For Commit Mode 0 interactions that use interactionVerb = SYNC_RECEIVE_ASYNCOUTPUT, clientID identifies the queue from which the message will be retrieved.
    Parameters:
    interactionSpec - An IMSInteractionSpec instance containing the properties of this interaction.
    input - For SYNC_SEND_RECEIVE and SYNC_SEND, a Record instance that contains the input for the IMS transaction; null for SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT.
    output - For SYNC_SEND_RECEIVE, SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT, a Record instance that receives the output data; null for SYNC_SEND.
    
    Throws:
    javax.resource.ResourceException -
    
    The execute() method was invoked on an invalid interaction. The interaction or its associated connection were closed.
    Note: The derived exception javax.resource.spi.IllegalStateException is thrown in this case.
    The interactionSpec is null or not of type IMSInteractionSpec. The exception javax.resource.ResourceException is thrown in this case.
    The input or output record is null or not an instance of javax.resource.cci.Streamable for SYNC_SEND_RECEIVE interactions. The exception javax.resource.ResourceException is thrown in this case.
    See Also:
    IMSInteractionSpec, IMSConnectionSpec, IMSConnection
  - getConnection
```
public final javax.resource.cci.Connection getConnection()
```
    Returns the connection associated with this interaction.
    
    Returns:
    javax.resource.cci.Connection The associated IMSConnection.
  - getRecordFactory
```
public javax.resource.cci.RecordFactory getRecordFactory()
                                                  throws javax.resource.ResourceException
```
    Returns a RecordFactory object that is used to create generic Record instances.
    Note: IMS TM Resource Adapter does not support this method.
    
    Returns:
    javax.resource.cci.RecordFactory
    
    Throws:
    
    javax.resource.ResourceException -
    Note: The derived exception javax.resource.NotSupportedExecption is thrown by getRecordFactory().
  - getWarnings
```
public javax.resource.cci.ResourceWarning getWarnings()
                                               throws javax.resource.ResourceException
```
    Gets the first ResourceWarning from the chain of warnings associated with this Interaction instance.
    Note: Currently, IMS TM Resource Adapter does not issue any warnings.
    
    Returns:
    javax.resource.cci.ResourceWarning
    
    Throws:
    
    javax.resource.ResourceException

Methods inherited from class java.lang.Object

IMSInteraction

clearWarnings

close

execute

execute

getConnection

getRecordFactory

getWarnings