How to setup TAFC CALLJEE 

in IBM Websphere ?  

1.    Introduction

The DeliveryMDB is a message driven bean that can be called from a jBC program using
the CALLJEE or JEEActivate functions.  These remote calls are achieved by using a
TCP/IP communication from the TAFC process to a Java Enterprise Edition Application
Server – such as JBoss (see the JRemote Inbound JCA User Guide for more information.). 
The only configuration necessary in TAFC is a host and a port.

In order to be callable, a message driven bean must implement the

JRemoteMessageListener interface and activate the JRemote JCA (jremote-ra.rar).  Once
activated the JRemote JCA will listen for incoming requests on the configured IP address
and port (see the ra.xml inside jremote-ra.rar).  The DeliveryMDB is configured to only
receive messages that have been sent with an activation string of "DELIVERY".  This
configuration is using a feature of the JRemote JCA that allows many message driven
beans to be activated, but only called when a message with the correct activation string is
received (see the DeliveryMDB ejb-jar.xml). 

The purpose of the DeliveryMDB is to place messages onto a JMS queue and optionally
wait for a reply on a JMS queue.  The DeliveryMDB ejb-jar.xml contains the configuration
required for these request and reply queues.  Multiple instances of the DeliveryMDBs can
be created in the ejb-jar.xml to receive requests for different activation types.  The jBC
program can determine which MDB instance it needs to call by the ACTIVATION string,
but it can also pass a timeout value, processing type (SYNC or ASYNC), correlation tag to
identify messages on the JMS queue and the JMSType.

2.    Quick guide to setting up TOCF(EE) DeliveryMDB

tocfT24ra-ra.rar:

The T24 RA will listen for incoming requests on a configured IP address and TCP port and
pass them on to the appropriate endpoint. In order for a DeliveryMDB to be activated as an
endpoint, it must inform the application server about its activation specification.
The activation specification is configured in the DeliveryMDB's deployment descriptors
and specifies which resource it wants to activate with (i.e. T24 RA) and what type of
message it wants to receive. This mechanism allows many MDBs to be activated but
deliver messages only to those which have been configured to receive this type of
message.

The DeliveryMDB's ejb-jar.xml deployment descriptor contains the following activation

property:

      
           <activation-config >
                <activation-config -property>
                    <activation-config -property-name>handler</activation-config -property-
name>
                    <activation-config -property-value>DELIVERY</activation- config -property-
value>
                </activation-config -property>
            </activation-config >

"DELIVERY" is the activation string which has to be passed as a parameter to the

CALLJEE/JEEActivate functions in order to call this particular MDB. The value of this
activation property can be changed to have multiple instances of the DeliveryMDB
receiving requests for different activation strings. 

As mentioned before, the purpose of the DeliveryMDB is to place messages on JMS

queues. A jBC program invoking a DeliveryMDB should leave the first 10 attributes of the
message parameter as header properties. The properties are as follows:

JMS type
The message type, used as a JMS message type on the queue. This gives the consumer the
opportunity to decide whether it wants to consume this type of message. The consumer
receiving a message can use the getJMSType() method (see class javax.jms.Message) to
retrieve the message type.

Correlation ID prefi x
This value is used by the reply queue to pick up the correct reply. The DeliveryMDB will
use this prefix to set the JMS Correlation ID with the following syntax.

<Correlation ID prefi x>_<message number>

The example below sets the following correlation IDs:

1 s t   message (attribute 11)          -->    MSG_ID_1

2 n d   message (attribute 12)          -->    MSG_ID_2

This ensures uniqueness on the queue and enables external systems to send response
messages in orders which are different than originally sent by the DeliveryMDB.

Processing type

Two values are supported:

 SYNC will cause the DeliveryMDB to wait for a reply on the response

queue.  See timeout attribute 4.
 ASYNC will cause the DeliveryMDB to place message on request
queue and not wait for a response.

Timeout

A total value in milliseconds specifying how long the DeliveryMDB will wait for all
messages to be processed.

<5> RESERVED
<6> RESERVED
<7> RESERVED
<8> RESERVED
<9> RESERVED
<10> RESERVED
The messages should therefore be assigned to attributes 11 and greater. The following
example places two JMS messages on the request queue and then waits until both
responses have been received.

      
      
    PROGRAM HELLO_WORLD
 
    INCLUDE JBC.h
 
    ACTIVATION = "DELIVERY"
    INFO = ""
    INFO<1> = "HELLO_MESSAGE"
    INFO<2> = ""
    INFO<3> = "SYNC"
    INFO<4> = "3000"
    INFO<5> = ""
    INFO<6> = ""
    INFO<7> = ""
    INFO<8> = ""
    INFO<9> = ""
    INFO<10> = ""
    INFO<11> = "My first message"
    INFO<12> = "My second message"
 
    JEECON = JEEOpen("127.0.0.1", 55006)
    IF SYSTEM(0) EQ 0 THEN
        CRT "OK"
    END ELSE
        CRT "CONNECTION FAILED"
    END
 
    ERROR.CODE = JEEActivate(JEECON,ACTIVATION,INFO)
    IF ERROR.CODE NE 0 THEN
        CRT "[FAILED] Error code: ":ERROR.CODE
    END
 
    JEEClose(JEECON)
END

The order in which messages are placed on the request queue follows a sequential order,
i.e. message on attribute 11 first, then message on attribute 12, etc. The external system is
allowed to send the responses back in a different order since the JMS Correlation ID
ensures uniqueness in a queue. When the processing type is SYNC, the DeliveryMDB will
wait until it has received a response for each respective request or until the timeout value
has been reached.

The activation specification in the application server deployment descriptor specifies that
a DeliveryMDB instance will be executed each time a message arrives at the inbound T24
Resource Adapter and the activation string of the message matches the activation
specification of the DeliveryMDB:

Activation specification JNDI name:

JBoss Weblogic Websphere

tocfT24ra-ra.rar [RAR jca/t24ResourceAdapter jca/t24ResourceAdapter

mapping]
 
The ejb-jar.xml defines the following resource references to locate the

1. JMS connection factory – to create a JMS session and place the request on the
request queue
2. request queue -  to send the request to the external system.
3. response queue – to receive the response from the external system.

Resource references JNDI names:

Resource reference / JBoss Weblogic Websphere

App. Server

jms/ jms/ jms/ jms/

jmsConnectionFactory jmsConnectionFactory t24QueueCxFactory t24QueueCxFactory
 queue/requestQueue queue/requestQueue jms/requestQueue jms/requestQueue

queue/responseQueue queue/responseQueue jms/responseQueue jms/responseQueue

 
If the DeliveryMDB has not been enlisted into a global transaction propagated by
CALLJEE, it will use a transacted JMS session to ensure that either all or none of the
messages are placed on the JMS request queue. The DeliveryMDB should be configured to
one of the following modes:

 Use Bean Managed Transaction demarcation  (BMTD) and a non XA enabled JMS

connection factory
 Use Container Managed Transaction demarcation  (CMTD) and a XA enabled JMS
connection factory

3.    IBM websphere

Version:   7.0.0.0+
 
Configure the following components in Websphere's Administrative
 
Install T24 RA:
Resource Adapters
                          Install tocfT24ra-ra.rar using default values
                       
Resource adapters > T24RA > J2C activation specification
                         Set activation specification which is used by the RA to configure a
specific endpoint instance
                                    - NAME:           T24 Resource Adapter
                                    - JNDI NAME:   jca/t24ResourceAdapter
 
Resource adapters > T24RA > J2C connection factories                                            
                         Define new JCA connection factory
                                    - NAME:           T24 JCA Connection Factory
                                    - JNDI NAME:   jca/t24ConnectionFactory
 
Configure the 'listenhost' with the IP address of the host where JMS queue(WAS) is
deployed and 'listenport' with any port (55006: Default)

Configure JMS Messaging Using WebSphere MQ Messaging Provider

Download Websphere MQ from IBM Website and install the product following the
instructions available on the IBM Website.
This section of the document explains the minimum required steps to configure MQ
alongside the JCA architecture.
After installing the MQ server, user need to login to the system (UNIX/Windows) as the
MQ user defined during installation and create Queue Manager and Queues.

Create Queue Manager

To create queue manager issue the following command.
            crtmqm –q Queue.Manager.Name     
   
Start Queue Manager
Before creating Queues user needs to start the Queue Manager defined in the previous
step. To start the Queue Manager issue the following command 
            strmqm Queue.Manager.Name            -->  to start Queue.Manager.Name 
Also make note of the following commands:
           endmqm Queue.Manager.Name          -->  to stop Queue.Manager.Name 
           dltmqm Queue.Manager.Name            -->  to delete Queue.Manager.Name   
Queues
We need to define two queues for the simple JCA architecture.
 
 In.Queue        –       Where messages will be posted to be processed
 Reply.Queue  –       Where reply messages will come

To create the queues user needs to be in an MQSC session to kick start the MQSC session
run the following command 
             runmqsc –e Queue.Manager.Name 

NB: A message tells you that MQSC session has started. MQSC has no specific prompt

Once the user is in MQSC prompt to create queues issue the following commands
 
            define qlocal ('In.Queue')
            define qlocal ('Reply.Queue')
 
After defining the queues, to exit from the MQSC session type 
            end
NB: If the requirement is to create the queue names using mixed case characters then
Make sure to give the queue names within single quotes. If the queue names are not
provided within quotes by default MQ will create the queue names in Upper Case
characters.

MQ Listener
Before moving on configuring other components related to JCA architecture, the MQ
Listener needs to be started using the following command by specifying the Queue
Manager Name created before and the port where you want the MQ Listener to be listening
                        runmqlsr -m Queue.Manager.Name -t TCP -p PortNumber (1414 by
default)
insert -p PortNumber if you want to use a different value from the default one

Browser Configuration
Configure the following components in Websphere's Administrative Console and then try
to start T24
Browser 

Create WebSphere MQ Server           

            Servers -->  Server Types  -->  WebSphere MQ servers à New
 
            Name:                                      T24 MQ Server
            WebSphere MQ Server name:    Queue.Manager.Name
            WebSphere MQ Host:               Ip Address of the host machine
            WebSphere MQ Port:                  Port Number for MQ Listener
            WebSphere MQ Channel:          SYSTEM.DEF.SVRCONN

Click TestConnection button to test the connection. User should see 'test connection

succeeded' message.

Configure JMS Messaging On WebSphere Application Server for Websphere MQ:

      
Service Integration Bus > Buses
                        --> Create new Service Integration Bus:  BrowserBus
                       
Service Integration Bus > Buses > BrowserBus
                       --> Switch to tab 'Local Topology' and add a new Bus member
                       --> Choose Websphere MQ Server option
                       --> Install using default Values
           
Service Integration Bus > Buses > BrowserBus > Bus members > T24 MQ Server
                        -->  Select (check) the option called 'Override WebSphere MQ server
connection properties'
JMS > Connection factories                  
                        --> Create a new JMS connection factory using e.g. the 'Websphere MQ
messaging Provider'

                                    - NAME:                       T24 JMS Connection Factory

                                    - JNDI NAME:               jms/t24CxFactory

                                    - Queue Manager:         Queue.Manager.Name

                                    - Hostname:                  IP address of MQ Manager machine

                                    - Port:                           Port where 'mq' listener is started

                        Keep everything else as default until unless required.

JMS > Queue connection factories                                              
                        --> Create a new JMS Queue connection factory using e.g. the 'Websphere
MQ messaging Provider'
                                    - NAME:           T24 Queue Connection Factory
                                    - JNDI NAME:   jms/t24QueueCxFactory
                                    - Queue Manager:         Queue.Manager.Name
                                    - Hostname:                  IP address of MQ Manager machine
                                    - Port:                           Port where 'mq' listener is started
                        Keep everything else as default until unless required.
JMS > Queues                                           
                      --> Create a new JMS Queue connection factory using e.g. the 'Websphere
MQ messaging Provider'
                                    - NAME:                T24 OFS Queue
                                    - JNDI NAME:        jms/t24OFSQueueJEE
                                    - Queue name:       In.Queue
                                    - Queue Manager:  Queue.Manager.Name
 
            JMS>Queues>T24 OFS Queue>Websphere MQ Connection Properties
           
                                    -Queue Manager Host:  IP Address of the host machine
                                    -Queue Manager Port:   MQ Listener Port number
                    --> Create a new JMS Queue connection factory using e.g. the 'Websphere
MQ messaging Provider'
                                    - NAME:               T24 OFS Reply Queue
                                    - JNDI NAME:       jms/t24OFSReplyQueueJEE
                                    - Queue name:      Reply.Queue
                                     - Queue Manager: Queue.Manager.Name    Reply.Queue
 
JMS>Queues>T24 OFS Reply Queue>Websphere MQ Connection Properties
           
                                  -Queue Manager Host:  IP Address of the host machine
                                  -Queue Manager Port:   MQ Listener Port number
 

JMS queues and JNDI's:

  
   
JMS > Activation Specification                             
                      --> Create a new Activation specification using e.g. the 'WebSphere MQ
messaging Provider'
                                    - NAME:           T24 OFS Message MDB
                                    - JNDI NAME:   jms/t24OfsMessageMDB
                                    - Destination JNDI NAME: jms/t24OFSQueueJEE
                                    - Queue Manager or Queue sharing group name:
Queue.Manager.Name
                                    - Host Name:      IP Address of the host machine
                                    - Port:               MQ Listener Port Number
                                       - Server Connection Channel: SYSTEM.DEF.SVRCONN
                                     - Click Test Connection Button: Should see the message 'A
connection was successfully made to WebSphere MQ.'
Install TOCF(EE):
 
Enterprise Applications
                       --> Install tocfee.ear using default values. The following warnings can be
ignored at this stage:
ADMA0114W: Resource assignment with JNDI
name eis/com.temenos.tocf.common.jca.OFSMessageListener  is not found …
ADMA0114W: Resource assignment with JNDI name jca/t24PluginsResourceAdapter  is
not found …
ADMA0115W: Resource assignment of name queue/requestQueue and type
javax.jms.Queue, with JNDI name jms/requestQueue is not found...
ADMA0115W: Resource assignment of name queue/responseQueue and type
javax.jms.Queue, with JNDI name jms/responseQueue is not found…
 
Enterprise Applications > TOCF(EE)_EAR > Manage Modules > TOCFPLUGIN >
Resource Adapter > J2C Activation specifications >
com.temenos.tocf.common.jca.OFSMessageListener
                        --> Set activation specification for the TOCF(EE) Plugin component
                                    - NAME:           T24 Plugin Resource Adapter
                                    - JNDI NAME:   jca/t24PluginsResourceAdapter
Enterprise Applications
                                    -->  Start TOCF(EE)_EAR

Resource Reference:
Test screen shots:
 
MQ queues without any messages:

Executing the HELLO_WORLD program which post 2 messages onto a JMS queue. 
2 messages in MQ IN queue as it listens to the JMS queue

Browse the IN queue for the two messages:

       

Last Updated: 09-Aug-2018