java.lang.Object | +----com.ibm.connector2.ims.ico.IMSConversationalHelperDeprecated. 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); } }
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:
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:
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 | Description |
IMSConversationalHelper() |
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. |
public IMSConversationalHelper()
public void endConversation() throws ResourceExceptionUsed 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.
- Throws
javax.resource.ResourceException
- When an error occurs in communicating with IMS Connect
public final void execute(IMSCCIRecord input, IMSCCIRecord output) throws ResourceException, NamingExceptionThe 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().
- Parameters
- input - the input record sent to IMS Connect
- output - the output record populated with the return from IMS Connect
- Throws
javax.resource.ResourceException
- When an error occurs in communication with IMS Connect
- Throws
NamingException
- When the JNDI lookup of the resource reference "ibm/ims/IMSTarget" fails. Most likely this is because. the reference is not present or it is not being invoked in an EJB container
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".
- Returns
- String the current JNDI lookup name
public final String getLtermName()Returns the String representation of the ltermName property.
- Returns
- String - The String representation of the ltermName property
- See Also
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.
- Returns
- String - The value of the mapName property; typically the name of an MFS MOD. Use of mapName is optional.
- See Also
public boolean isConvEnded()Returns boolean true if the conversation with IMS has ended, false otherwise.
- Returns
- boolean true if conversation has ended, false otherwise.
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.
- Parameters
- connFactory - The ConnectionFactory to use for this
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.
- Parameters
- connSpec - The IMSConnectionSpec that will be used to overide the default values specified in the ManagedConnectionFactory.
- See Also
public void setExecutionTimeout(int newExecTimeout)Sets the executionTimeout property (int) value.
- Parameters
- newExecTimeout - The new value for the property.
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.
- Parameters
- jndiName - the new JNDI lookup name
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.
- Parameters
- newLtermName - The new value for the ltermName property. Use of ltermName is optional.
- See Also
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.
- Parameters
- newMapName - The new value for the mapName property. Use of mapName is optional.
- See Also
public void setSocketTimeout(int aSocketTimeout)Sets the socketTimeout property (int) value.
- Parameters
- aSocketTimeout - The new value for the property.