The connection interfaces provide a variety of features which may be used by an EJB in a communication with an EIS application. These may be used as alternatives or in combination:
Dialog communication (based on the
EISConnection,EISOltpConnectionandEISUpicConnectioninterfaces)Asynchronous communication (based on the
EISConnectioninterface and on additional methods of the interfaceEISOltpConnection)
The following sections provide information concerning these topics. Examples of the most common communication scenarios are given in the JavaDoc of BeanConnect.
Dialog communication
The recommended way for an EJB to communicate with an EISapplication is by using the methods of the EISConnectionOltpMessage interface. Objects of type OltpMessage are exchanged with the EISapplication over this interface. The OltpMessage object serves as a container for the message content, which is assembled from one or more OltpMessageRecord objects and/or one or more OltpMessagePart objects. While an OltpMessageRecord is of arbitrary length, the length of an OltpMessagePart may not exceed 32767 bytes.
At the time of a sndOltpMessage() call, the data to be sent is merely handed over to BeanConnect but not yet transferred to the EIS application. The request to the EIS application is only actually sent when the first rcvOltpMessage() method is issued for this connection.
The easiest way to call a dialog service in an EIS application is with the call() method. This method allows RPC-like communication with an EISapplication.
The following sections outline the communication between an EJB and an UTM/CICS program by means of OltpMessage objects.
The options listed below are available for exchanging data between an EJB and an UTM/CICS program using OltpMessage objects:
You will find further examples of the most common communication scenarios as well as code examples in the JavaDoc of BeanConnect.
Data exchange based on OltpMessagePart objects with UTM partners
With MGET and MPUT, an UTM program can receive or send one or more message parts each with a maximum length of 32 Kbytes. Here the individual MessagePart objects correspond directly to the MGET and MPUT calls in the UTM program.
Data is thus exchanged according to the following scheme:
|
Figure 61: Data exchange based on OltpMessagePart objects (UTM partners)
Data exchange based on OltpMessagePart objects with CICS partners
With RECEIVE and SEND, a CICS program can receive or send one or more message parts each with a maximum length of 32 Kbytes. Here the individual MessagePart objects correspond directly to the RECEIVE and SEND calls in the CICS program.
Data is thus exchanged according to the following scheme:
|
Figure 62: Data exchange based on OltpMessagePart objects (CICS partners)
Data exchange based on OltpMessageRecord objects
As an alternative to multiple MessagePart objects sent within an OltpMessage object, you can use OltpMessageRecord objects sent within an OltpMessage object. In this case, you can send and receive messages which are longer than 32 Kbytes without needing to break it down into packets of 32 Kbytes as a Java programmer.
|
Figure 63: Data exchange based on OltpMessageRecord objects (OSI-TP protocol with UTM partners)
|
Figure 64: Data exchange based on OltpMessageRecord objects (CICS partners)
When communicating with an UTM application via the UPIC protocol, you can use OltpMessageRecord objects and OltpMessagePart objects if you are working with different format names.
| ||||||||||||||||||||||||||||||
Figure 65: Data exchange based on OltpMessageRecord objects (UPIC protocol)
Asynchronous communication
A service is called asynchronous when it does not send a reply message.
The sending of an asynchronous message has to be explicitly triggered by the EJB with the methods snd() + flush(), sndLast() or sndLastString() of the EISConnection interface, which finalize the message and initiate the send cycle.
An asynchronous message may be sent to the EIS partner either immediately or after a delay. With a delayed sending, the EJB must specify the delay time prior to calling the snd() method. You specify the delay time by means of the setDelayTime() method. A delayed message is stored by the BeanConnect proxy until the time delay has elapsed. The message is then forwarded to the EIS application.
An asynchronous message generated in a transaction is sent only if and when the transaction is committed. If the transaction is rolled back, the asynchronous request will not be sent. An asynchronous request with time delay 0 generated outside of a transaction is sent immediately.
If you want to ensure that an asynchronous service is currently being addressed, you can check this using the getPartnerType() method or you can use the setDelayTime(0) method, which throws an exception if a dialog service is addressed unexpectedly. However, the use of this method results in certain performance impairments.
Examples of asynchronous communication with an EIS partner can be found in the JavaDoc of BeanConnect.
Transactional communication
During deployment of a connection factory, the configuration property transactional of the connection factory has to be set (see "transactional" in Defining configuration properties for OSI-TP / LU6.2 ). A connection factory may either support both transactional and non-transactional communication or it may be limited to non-transactional communication only:
If the connection factory supports transactional communication, the runtime environment decides at the time a transaction is started whether the communication within a conversation of such a connection will be transactional or not. A conversation which is started while a transaction is open is always included in the transaction.
A conversation which was already open at the start of the transaction but on which no communication has yet occurred is also included in the transaction. In these cases a transactional protocol will be used for communication; otherwise a non-transactional protocol will be used.
If the connection factory does not support transactional communication, the following applies: For connections generated with this connection factory, a non-transactional protocol is always used, no matter whether the communication takes place within or outside an application server transaction. This allows the deployer of the resource adapter to explicitly exclude an EIS service from a transaction that may be active in the application server.
You can query the current status of a transaction using the isInDistributedTransaction() method of the EISOltpConnection interface.
When a transactional protocol is used for communication, the application server transaction and the transaction in the EIS partner are part of a single, distributed transaction which are either committed or rolled back as a single unit. With transactional communication, a conversation must not span more than one transaction. However, a conversation may comprise more than one dialog step. This means that several snd()/rcv() pairs may be exchanged with the EIS partner within a single transaction.
If an EJB uses more than one transactional connection within a transactional EJB method, it is strongly recommended that these connections are associated in a single EISConnectionGroup (see the following section Connection groups). Doing so helps to avoid a resource bottleneck.
Connection groups
The concept of associated connections enables an EJB to simultaneously send several messages via more than one connection. This allows the processing of several dialog services of one or more EIS partner application at the same time, thereby avoiding the time delay caused by the sequential processing of a number of RPC-like calls.
You can associate a connection with another connection by means of an EISConnectionGroup. You create the EISConnectionGroup using an EISConnectionGroupFactory. You get an EISConnectionGroupFactory with the method getEISConnectionGroupFactory()from a ConnectionFactory. For example:
ConnectionFactory cf1 = (ConnectionFactory)ic.lookup(...); ConnectionFactory cf2 = (ConnectionFactory)ic.lookup(...); EISConnectionGroupFactory cgf = cf1.getEISConnectionGroupFactory(); EISConnectionGroup cg = cgf.getConnectionGroup(); con1 = (EISOltpConnection)cf1.getConnection(cg); con2 = (EISOltpConnection)cf2.getConnection(cg);
You will find a code sample for Example 15 on Code samples for outbound communication .
The simultaneous dispatch of the messages to all connections of the connection group is initiated by calling the execute() method on the EISConnectionGroup-object. Connections for transactional communication may be associated with connections for non-transactional communication. For details see the JavaDoc of BeanConnect.
Code conversion
Whenever String or ByteContainer objects are used, BeanConnect can perform a code conversion. The methods for setting up the proper environment for a code conversion are contained in the interface net.fsc.beanta.encoding.EncodingDef. This interface is extended by the EISConnection interfaces of BeanConnect. If code conversion has not already been activated at deployment time using the encodingActive configuration property (see "encodingActive" in Defining configuration properties for OSI-TP / LU6.2 ), you can switch on code conversion by calling the method setEncodingActive(). The code table to be used for a code conversion is assigned by defining the encoding configuration property (see "encoding" in Defining configuration properties for OSI-TP / LU6.2 ) at deployment time or by using the method setEncoding() of the EISConnection interface. For details about code conversion of messages and on how to supply your own encoding tables see Encoding and national language support ) and the JavaDoc of package net.fsc.beanta.encoding.