Class Hierarchy All Classes All Fields and Methods

Class com.ibm.connector2.ims.ico.IMSConversationalHelper

java.lang.Object
   |
   +----com.ibm.connector2.ims.ico.IMSConversationalHelper
Deprecated. IMSConversationalHelper is deprecated. In the future it will only be available as a sample class. It is recommended that you obtain it from the "IMS Examples Exchange" on the IMS web site: http://www.ibm.com/ims. Additional versions, using other types of input and output messages, will be made available over time.

The IMSConversationalHelper is a helper class designed to allow Java applications and Enterprise Java Beans to communicate with conversational IMS applications.

IMS Connect requires all iterations of a conversation to use the same connection (for example, TCP/IP socket). The helper class sets up and maintains a consistent connection with IMS Connect that is used for the duration of the conversation. It does so by obtaining a connection from the ConnectionFactory and holding it open until the conversation has ended. The IMSConversationalHelper class is used in conjunction with the IMSCCIRecord helper class. The IMSCCIRecord helper class can be used to create record classes to represent the input and output of each iteration of a conversational IMS application.

The key method in the IMSConversationalHelper class is the execute method. The execute method takes two arguments, an input record and an output record. The input record is sent to the IMS application, and the results are returned through the output record.

Business methods can then be created to represent each iteration of the IMS application.

For instance, a simple method to represent a single iteration might look like:

 	public CPBOutputRecord runFirstIteration( CPBInputRecord input ) {
		try {
			CPBOutputRecord output = new CPBOutputRecord();
			super.execute( input, output );
			return output;
		} catch ( Exception e ) {
			throw new EJBException(e);
		}
	}
 

Management

The helper class can be used in both managed and non-managed environments.

Managed environments

If the helper class is used to develop an Enterprise Java Bean, it runs in a managed environment. In a managed environment, there are several requirements:

Non-managed environments

If the helper class is used to develop a Java application, the application will use the helper class in a non-managed manner. This means you must create and provide a ConnectionFactory to the helper class through its setConnectionFactory method.

At a minimum, for TCP/IP you must provide:

For Local-Option, you must provide: To provide the ConnectionFactory, first create an IMSManagedConnectionFactory. Then set the options that you want to use for your connections (hostname, port number, datastore, SSL, etc). Use the createConnectionFactory method to create a new ConnectionFactory for IMSConversationalHelper. Reference the following code for an example (the code would be used inside a class that extends IMSConversationalHelper):
 IMSManagedConnectionFactory imsCF = new IMSManagedConnectionFactory();
 
 imsCF.setHostName("MYHOST.ABC.XYZ.COM");
 imsCF.setPortNumber("9999"); 
 imsCF.setDataStoreName("MYDSTOR");
 
 super.setConnectionFactory( (ConnectionFactory) imsCF.createConnectionFactory() );
 

public class IMSConversationalHelper
extends Object

Constructor Index
Constructor Description
IMSConversationalHelper()  
Method Index
Method Description
void endConversation() Used to force a conversation with IMS to be ended.
void execute(IMSCCIRecord, IMSCCIRecord) The execute() method is used in extending classes to commmunicate with IMS.
String getJNDILookupName() Returns the JNDI name that will be used to look up the IMS Connector for Java ConnectionFactory.
String getLtermName() Returns the String representation of the ltermName property.
String getMapName() Returns the value of the mapName property, typically the name of an MFS Message Output Descriptor (MFS MOD).
boolean isConvEnded() Returns boolean true if the conversation with IMS has ended, false otherwise.
void setConnectionFactory(ConnectionFactory) Provides the helper class with a ConnectionFactory to use instead of doing a JNDI lookup for an application server-managed ConnectionFactory, for use in a non-managed environment.
void setConnectionSpec(IMSConnectionSpec) Provides the helper class with an IMSConnectionSpec instance which can be used to provide information such as the security information to be used with component-managed authentication.
void setExecutionTimeout(int) Sets the executionTimeout property (int) value.
void setJNDILookupName(String) Allows the user to reset the JNDI name that will be used to look up the IMS Connector for Java ConnectionFactory.
void setLtermName(String) Sets the value of the ltermName property.
void setMapName(String) Sets the value of the mapName property, typically the name of an MFS Message Output Descriptor (MFS MOD).
void setSocketTimeout(int) Sets the socketTimeout property (int) value.

Constructors

IMSConversationalHelper

public IMSConversationalHelper() 

Methods

endConversation

public void endConversation() throws ResourceException

Used to force a conversation with IMS to be ended.

The endConversation() method provides a way of forcibly ending a conversation with IMS. By passing the SYNC_END_CONVERSATION interaction verb, it tells IMS Connect to terminate the conversation. It then cleans up the connection to IMS Connect, sets the convEnded variable to true, and readies the bean for a new conversation.

execute

public final void execute(IMSCCIRecord input,
                          IMSCCIRecord output) throws ResourceException, NamingException

The execute() method is used in extending classes to commmunicate with IMS. Given an input and output record, it will run the query and populate the output record with the results. The variable convEnded will be set to the value of IMSInteractionSpec.convEnded and can be accessed with the method isConvEnded().

getJNDILookupName

public String getJNDILookupName() 

Returns the JNDI name that will be used to look up the IMS Connector for Java ConnectionFactory.

If a custom JNDI name has not been specified using , the method will return the default name, "java:comp/env/ibm/ims/IMSTarget".

getLtermName

public final String getLtermName() 

Returns the String representation of the ltermName property.

getMapName

public final String getMapName() 

Returns the value of the mapName property, typically the name of an MFS Message Output Descriptor (MFS MOD). On output, the name of the MOD provided in the I/O PCB by the IMS application program is provided to the Java application by the getMapName method.

Note: The mapName property should not be used by Java applications that use an enterprise service whose input and output messages are generated by WebSphere Studio's MFS support.

isConvEnded

public boolean isConvEnded() 

Returns boolean true if the conversation with IMS has ended, false otherwise.

setConnectionFactory

public void setConnectionFactory(ConnectionFactory connFactory) 

Provides the helper class with a ConnectionFactory to use instead of doing a JNDI lookup for an application server-managed ConnectionFactory, for use in a non-managed environment.

Use the setConnectionFactory method to specify a ConnectionFactory to use in a non-managed setting. Initialize a new IMSManagedConnectionFactory, set whatever parameters are necessary for your IMS Connect instance, and then call the createConnectionFactory method to generate a new ConnectionFactory for use in the setConnectionFactory method.

If no ConnectionFactory is set, or if the method is called with null instead of a ConnectionFactory, the helper class will do a managed lookup of the JNDI name "ibm/ims/IMSTarget" to retrieve a ConnectionFactory.

setConnectionSpec

public void setConnectionSpec(IMSConnectionSpec connSpec) 

Provides the helper class with an IMSConnectionSpec instance which can be used to provide information such as the security information to be used with component-managed authentication.

The userName, password and groupName values in the IMSConnectionSpec will override the values specified in the Custom Properties of the J2C ConnectionFactory. If an IMSConnectionSpec is not provided or a null is provided to this method, the helper class will use the default values specified in the ManagedConnectionFactory instead.

setExecutionTimeout

public void setExecutionTimeout(int newExecTimeout) 

Sets the executionTimeout property (int) value.

setJNDILookupName

public void setJNDILookupName(String jndiName) 

Allows the user to reset the JNDI name that will be used to look up the IMS Connector for Java ConnectionFactory.

If no name is specified, or if setJNDILookupName is called with a null input, the default JNDI name, "java:comp/env/ibm/ims/IMSTarget" will be used for the JNDI lookup.

setLtermName

public void setLtermName(String newLtermName) 

Sets the value of the ltermName property. This value is used to override the value in the LTERM field of the IMS application program's I/O PCB, with the intent that the IMS application will make logic decisions based on the override value. See the IMS Connect User's Guide and Reference for a description of how the LTERM override is used.

setMapName

public void setMapName(String newMapName) 

Sets the value of the mapName property, typically the name of an MFS Message Output Descriptor (MFS MOD). The MOD name will be provided to the IMS application program in the I/O PCB.

Note: The mapName property should not be used by Java applications that use an enterprise service whose input and output messages are generated by WebSphere Studio's MFS support.

setSocketTimeout

public void setSocketTimeout(int aSocketTimeout) 

Sets the socketTimeout property (int) value.

Class Hierarchy All Classes All Fields and Methods