Common Client Interface (CCI)

You can create an application to use the IMS™ TM resource adapter to interact with IMS by using the Common Client Interface (CCI).

You can use the application code that is generated by the J2C wizard in a Rational® or WebSphere® integrated development environment (IDE) to access IMS transactions through the IMS TM resource adapter. No coding is necessary when you use this approach. Alternatively, you can write the application source code without using an IDE.

To write the code yourself, you must use the CCI programming interface. The CCI API provides access from Java™ EE clients, such as enterprise beans, JavaServer Pages (JSP) pages, and servlets, to backend enterprise information systems (EIS) such as IMS.

Applications that follow the CCI programming interface model have a common structure, independent of the EIS that is being used. The Java EE Connector Architecture (JCA) specification defines two objects that are necessary for the application:
  • Connection objects that represent connections to an EIS
  • ConnectionFactory objects that create those Connection objects
These objects are what an application server uses to manage security, transaction context, and connection pools for a resource adapter. An application that uses the IMS TM resource adapter CCI programming interface starts by obtaining an IMSConnectionFactory object. The IMSConnectionFactory object can be obtained in two ways:
  • Managed: If you are using an application server, the IMSConnectionFactory object is normally created from the resource adapter through an administration interface such as the WebSphere Application Server administrative console. This type of environment is called a managed environment because an application server is used to manage the qualities of service of the connections in its environment. For example, you would create an IMSConnectionFactory object and configure its custom properties by using the WebSphere Application Server administrative console. Custom properties such as the hostname and port number of the target IMS system are configured on the IMSConnectionFactory object. When the IMSConnectionFactory object is created, it can be made available for use by any enterprise applications through JNDI.
  • Non-managed: When you are not using an application server to manage the connection (such as running the application as a stand-alone Java application), this type of environment is called a non-managed environment. In this type of configuration:
    • You must manually create an IMSManagedConnectionFactory object and set its custom properties. You can then create an IMSConnectionFactory object from the IMSManagedConnectionFactory object.
    • The IMS TM resource adapter uses the DefaultConnectionManager class in the JCA 1.5 Connection Management API for connections. This class does not provide any connection pooling, and all the connection pool properties would be ignored. The IMS TM resource adapter would open and close a socket connection with IMS Connect for every transaction request. Opening and closing socket connections introduces resource overhead and is likely to result in performance degradation as compared to a managed scenario. You can build your own connection pooling by implementing a PoolManager class to be used with the DefaultConnectionManager class. For more information, see the JCA 1.5 Connection Management API section.

      Because CM0 transactions are recoverable, IMS Connect creates a separate TPIPE for each client that uses CM0. Without the connection pool management function provided by an application server, too many TPIPEs would be created and overload the system.

IMS connections

An IMSConnection object can then be created from that IMSConnectionFactory object. The properties of the IMSConnection object can either be specified in an IMSConnectionSpec object passed as a parameter to the getConnection method, or the default values defined in the IMSConnectionFactory is used. After an IMSConnection is obtained, an IMSInteraction instance can be created from the IMSConnection instance. An IMSInteraction instance represents the interaction that is going to be executed on that connection. As with the connection, interactions can have custom properties taken from the IMSInteractionSpec class.

Input and output

To perform the interaction, the application makes a call to the execute() method of the IMSInteraction object, passing it input and output objects to hold the data. An input byte array must be created containing values for each field in the input message to IMS. Likewise, an output byte array must also be created to hold the response message returned by IMS. The value of each field in the output message is extracted from the output byte array.

You can write the input and output byte arrays yourself, or you can use the J2C options in a Rational or WebSphere development environment to create Java data bindings for the input and output messages of your CCI application.

Requirements for applications that retrieve data from an IMS system:
  • Use the IMSConnectionFactory object to create an IMSConnection object.
  • Use the IMSConnection object to create an IMSInteraction object.
  • Use the IMSInteraction object to execute transactions on the backend IMS system.
  • Close the IMSInteraction and IMSConnection objects.