Connect to AIA from your Enterprise via JMS An Oracle White Paper
[December] [2008]
Connect to AIA from your Enterprise via JMS Page 2
Connect to AIA from your Enterprise via JMS
Introduction ......................................................................................................... 3
High-Level Enterprise to AIA Connectivity Via JMS Architecture ..... 4
JMS Connectivity Architecture for Oracle AQ-JMS provider ............... 6
Resource Adapter Configuration on OC4J Container .............................. 7
Connect to AIA from your Enterprise via JMS Page 3
Connect to AIA from your Enterprise via JMS
INTRODUCTION
Application Integration Architecture (AIA) recommends the store-and-forward pattern to ensure the
guaranteed delivery of the business events between two or more participating applications which are
exchanging their business transactions in the fire-and-forget message exchange pattern. AIA adopts
the standard store-and-forward mechanism using the Java Message Service (JMS).
Participating applications can send business events to the AIA layer in different ways such as
technology adapters, SOAP over HTTP, or via JMS. If the participating application is not capable of
pushing the business events to the JMS layer directly, then AIA can fill the gap with the first class
AIA artifact, “JMS producer service”.
This paper provides information on how an enterprise application / participating system can connect to
AIA via JMS to push the business events to the AIA integration layer. It provides a high-level
description of the architecture for any JMS provider and then discusses more detailed architecture
using the Oracle AQ-JMS provider.
This paper provides the setup instructions required on the OC4J container to allow the enterprise
applications / participating systems to connect to AQ-JMS provider.
In addition, this paper provides a detailed example of setup instructions required for the enterprise
application/ participating system, specifically JMS client setup instructions. We use Siebel 8.0 as the
example; however you can follow these instructions for other enterprise systems by replacing system
specific library files wherever it is applicable in the setup instructions.
Connect to AIA from your Enterprise via JMS Page 4
HIGH-LEVEL ENTERPRISE TO AIA CONNECTIVITY VIA JMS ARCHITECTURE
Connect to AIA from your Enterprise via JMS Page 5
Enterprise applications such as Siebel, Agile, PeopleSoft, and EnterpriseOne can connect to the AIA layer via
any standard JMS providers like OC4J, AQ-JMS, or WLS JMS using standard JMS client programs in
association with the JMS provider specific libraries.
The connection mechanism depends upon the source application or container and the target JMS provider or
its container. Since each JMS provider has its own set of libraries and follows a different methodology to
expose its interface, you should explore and identify the required JMS client setup dependencies for
connecting to the desired JMS provider.
The JMS provider acts as a bridge between the enterprise applications and the AIA layer with standard JMS
features such as:
Support for the transactions
Standard JMS headers and message type
Message priorities
Message correlation
Client acknowledgement
Message grouping
Message sequencing
Message durability
Reliable messaging
JMS providers may support more features than these common features. Please refer to the individual JMS
provider documentation for more details.
You should evaluate the available features and select the appropriate provider for your AIA connectivity
depending on the container used for AIA PIP’s deployment, quality of service (QOS), and the reliability of the
JMS provider.
Connect to AIA from your Enterprise via JMS Page 6
JMS CONNECTIVITY ARCHITECTURE FOR ORACLE AQ-JMS PROVIDER
Connect to AIA from your Enterprise via JMS Page 7
This architecture diagram illustrates AIA connectivity with Siebel or Agile trying to push the messages directly to the AQ-JMS queues via JMS protocol. Enterprise applications should use the OJMS resource adapter deployed on the OC4J container to push the enterprise business messages to AQ-JMS queues. Enterprise applications should set up the required OC4J client libraries and ensure that they are available to the application‟s runtime. The OC4J client libraries use the opmn protocol for the remote invocation on top of ORMI protocol. The connectivity is transactional between the enterprise client and the OJMS resource adapter. The OJMS resource adapter acts as a bridge between the enterprise application and the actual AQ-JMS Queue.
The following setup instructions explain the detailed steps required to create the JMS queues on the OC4J container server and AQ database and the client setup required on the Siebel enterprise application.
RESOURCE ADAPTER CONFIGURATION ON OC4J CONTAINER
1. Create JMS Queue
i) Create user and assign privileges.
Run the following sql commands: DROP USER jmsuser CASCADE ; GRANT connect,resource,AQ_ADMINISTRATOR_ROLE TO jmsuser IDENTIFIED BY jmsuser ; GRANT execute ON sys.dbms_aqadm TO jmsuser; GRANT execute ON sys.dbms_aq TO jmsuser; GRANT execute ON sys.dbms_aqin TO jmsuser; GRANT execute ON sys.dbms_aqjms TO jmsuser; connect jmsuser/jmsuser;
ii) Create the table that handles the OEMS JMS destination (queue).
Queues use a queue table. The following SQL example creates a single table, AIA_TESTJMSQTAB for a queue. The multiple_consumers parameter specifies whether there are multiple consumers. Set multiple_consumers to false for a queue. Begin DBMS_AQADM.CREATE_QUEUE_TABLE(Queue_table =>'AIA_TESTJMSQTAB',Queue_payload_type =>'SYS.AQ$_JMS_MESSAGE', sort_list => 'PRIORITY,ENQ_TIME', multiple_consumers=>false, compatible =>'8.1.5'); End;
iii) Create the JMS destination.
Connect to AIA from your Enterprise via JMS Page 8
This SQL example creates a queue called AIA_TESTJMSQUEUE within the queue table AIA_TESTJMSQTAB. Begin DBMS_AQADM.CREATE_QUEUE(Queue_name =>'AIA_TESTJMSQUEUE', Queue_table =>'AIA_TESTJMSQTAB'); End;
iv) Start Queue.
Begin sys.dbms_aqadm.start_queue(queue_name => 'AIA_TESTJMSQUEUE', enqueue => TRUE, dequeue => TRUE);
End;
2. Create Connection Pool
Logon to oc4j EM console and select the oc4j instance (example:oc4j_soa)
Go to JDBC Resources: <oc4j_soa>/Administration tab/JDBC Resources
Connect to AIA from your Enterprise via JMS Page 9
Field Enter:
Name of the Connection Pool TestJmsConn
URL jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(LOAD_BALANCE=on)(ADDRESS=(PROTOCOL=tcp)(HOST=ap6036fems.us.oracle.com)(PORT=1565)))(CONNECT_DATA=(SERVICE_NAME=brcinstd)))
Username jmsuser
Password jmsuser
3. Create Data Source
Field Enter:
Name TestJmsDS
Connect to AIA from your Enterprise via JMS Page 10
JNDI Location jdbc/TestJmsDS
Connection Pool Select the Connection Pool that you created in the previous step (example: TestJmsConn)
4. Create OJMS resource provider (OEMS with database)
Go to Database Persistence: <oc4j_soa>/Administration tab/Database Persistence Click the “Deploy” button
Field Enter:
Resource Adapter Module Name TestJmsRA
Resource Provider Name TestJmsRP
Datasource JNDI location Select the Jndi name of the data source that you created in the previous step.
RESTART the Server from the “telnet console”.
5. Create Connection Factory for the resource adapter
Go to Database Persistence: <oc4j_soa>/Administration tab/Database Persistence Select the OJMS resource adapter that you have created (TestJmsRA).
Go to the Connection Factories Tab Create
Connect to AIA from your Enterprise via JMS Page 11
Select javax.jms.QueueConnectionFactory from the drop-down list. Enter the JNDI location: TestJmsRA/MyQCF Keep the default configuration properties as it is.
6. Create Administration Object for the resource adapter Select the Administration objects tab and click “Create”.
Select the “oracle.j2ee.ra.jms.generic.AdminObjectQueueImpl” from the drop down menu. Provide JNDI location for the admin object: TestJmsRA/Admin Keep the default configuration properties values as it is.
7. Check the application.xml.
Verify the resource adapter configuration of the application.xml at the location: <OracleAS_HOME>/j2ee/<SOA_Instance>/config <resource-provider name="TestJmsRP" class="oracle.jms.OjmsContext"> <description /> <property name="datasource" value="jdbc/jmsTestDS" /> </resource-provider>
Connect to AIA from your Enterprise via JMS Page 12
RESTART the Server from the “telnet console”.
8. Enable the user role to allow EJB/RMI access and grant permissions.
Follow the instructions in the oc4j Security Guide to enable this role and grant permissions to the user or role. For testing purposes, you can enable the “anonymous” user and check the connectivity. But, after the connectivity testing, make sure that you disable/de-activate the anonymous user for the server. AIA doesn‟t recommend allowing anonymous users with no password to access SOA resources. To enable the anonymous user for testing, open the “<OracleAS_HOME>/j2ee/<SOA_Instance>/config/system-jazn-data.xml” file and activate the anonymous user. Add the anonymous user as the member of “users” role.
<members><member> <type>user</type>
<name>anonymous</name> </member></members>
Add the users role/group to the application.xml access control group. <namespace-access>
<read-access>
<namespace-resource root="">
<security-role-mapping>
<group name="oc4j-administrators" />
<group name="ascontrol_admin" />
<group name="users" />
</security-role-mapping>
</namespace-resource>
</read-access>
<write-access>
<namespace-resource root="">
<security-role-mapping name="<jndi-user-
role>">
<group name="oc4j-administrators" />
<group name="ascontrol_admin" />
<group name="users" />
</security-role-mapping>
</namespace-resource>
</write-access>
</namespace-access>
RESTART the Server from the “telnet console”.
GUIDELINES FOR SETTING UP THE ENTERPRISE APPLICATION
(Example: JMS client setup instructions for Siebel 8.0)
Siebel Application Configuration
Connect to AIA from your Enterprise via JMS Page 13
1. Extract oc4j-extended.zip from http://download.oracle.com/otn/java/oc4j/101330/oc4j_extended_101330.zip to a folder in a machine where the siebel server is installed say D:\JMS folder.
2. Copy Siebel.jar and SiebelJI_enu to D:\JMS folder. These jar files can be found in Siebel installed directory.
3. Copy jndi.jar file to D:\JMS\j2ee\home\lib folder. You should find it in: product/10.1.3.1/OracleAS_1/datadirect/sun/lib/jndi.jar
4. Java version: use “jdk1.5 update 6”. 5. Copy "com/evermind/util/JCAProperties.class" from the oc4j-internal.jar file to the D:\JMS folder.
This jar file can be found in the SOA installation directory. 6. Create a file with name „jndi.properties‟ with following details in the path D:\JMS
java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory java.naming.provider.url=opmn:ormi://<IP Address of the FMW server>:<Posrt No>:oc4j_soa java.naming.security.principal=anonymous For example:
java.naming.factory.initial=com.evermind.server.rmi.RMIInitialContextFactory java.naming.provider.url=opmn:ormi:// 152.68.240.154:6009:oc4j_soa java.naming.security.principal=anonymous
Make sure that there is no extra spaces in the jndi.properties file. 7. Create a Named Subsystem in Siebel application through the server management. Connect to the
server manager from command prompt from bin directory of the Siebel installed folder with the command.
Srvrmgr /g <gatewayserver> /e <enterpriseserver> /s <siebelserver> /u <userid> /p <password> Eg. srvrmgr /g sdc78198svqe:4330 /e siebel /s sdc78198svqe /u sadmin /p sadmin
8. Run the following command to create the named subsystem and add the jar file into the class path. Create named subsystem JAVA for subsystem JVMSubSys with
DLL=C:\Sun\SDK\jdk\jre\bin\server\jvm.dll, CLASSPATH =
D:\JMS;D:\JMS\Siebel.jar;D:\JMS\SiebelJI_enu.jar;D:\JMS\j2ee\ho
me\lib\adminclient.jar;D:\JMS\j2ee\home\lib\jndi.jar;D:\JMS\j2e
e\home\lib\jta.jar;D:\JMS\j2ee\home\oc4jclient.jar;D:\JMS\j2ee\
home\lib\bcel.jar;D:\JMS\j2ee\home\lib\jms.jar;D:\JMS\j2ee\home
\lib\javax77.jar;D:\JMS\jdbc\lib\ojdbc14dms.jar;D:\JMS\lib\dms.
jar;D:\JMS\opmn\lib\optic.jar;D:\JMS\j2ee\home\lib\ejb.jar;.,
VMOPTIONS= D:\JMS\log\jms.log
Note: - To locate the JAR files, you need to do a search/find in the extracted folders of oc4j_extended_101330.zip or SOA installation or Siebel installation directories.
For Solaris Environment the CLASSPATH should be separated by : (colon) while for windows it should be ; (semicolon). So the above command for Solaris environment has to be:
Connect to AIA from your Enterprise via JMS Page 14
Create named subsystem JAVA for subsystem JVMSubSys with DLL=
/usr/jdk1.5.0_06/jre/lib/sparc/client/libjvm.so, CLASSPATH =
/export/home/qa2/JMS:/export/home/qa2/JMS/Siebel.jar:/export/ho
me/qa2/JMS/SiebelJI_enu.jar:/export/home/qa2/JMS/j2ee/home/lib/
adminclient.jar:/export/home/qa2/JMS/j2ee/home/lib/jndi.jar:/ex
port/home/qa2/JMS/j2ee/home/lib/jta.jar:/export/home/qa2/JMS/j2
ee/home/oc4jclient.jar:/export/home/qa2/JMS/j2ee/home/lib/bcel.
jar:/export/home/qa2/JMS/j2ee/home/lib/jms.jar:/export/home/qa2
/JMS/j2ee/home/lib/javax77.jar:/export/home/qa2/JMS/jdbc/lib/oj
dbc14dms.jar:/export/home/qa2/JMS/lib/dms.jar:/export/home/qa2/
JMS/opmn/lib/optic.jar:/export/home/qa2/JMS/j2ee/home/lib/ejb.j
ar:., VMOPTIONS= /export/home/qa2/JMS/log/jms.log
Make sure the path is correct for all the files and the CLASSPATH should end with a . (dot). Here qa2 should be replaced with the appropriate folder name.
9. Login into Siebel Application, navigate to Site Map -> Administration Server Configuration -> Profile Configuration
a. Query For the Profile with Alias Name „JAVA‟ in the profile List and make sure the parameters are correct.
b. For Windows environment edit the value of VMOPTIONS to -Djms.log=D:\JMS\log\jms.log.
c. For Solaris environment edit the value of VMOPTIONS to -Xusealtsigs -Xrs -Djms.log=/export/home/qa2/JMS/log/jms.log
Make sure that JMS/log folder exits and has the write permission. 10. Restart the Siebel Server.
Change Required in Web Service 1. Navigate to Site Map -> Administration – Web Services -> Outbound Web Services 2. Query for SWI* 3. Change the transport to JMS and address as:
jms://<queue name>@<connection factory> queue name and connection factory will be provided by AIA team.
4. After changing the address click on clear cache button.
Test Your Configuration
1. Login to Siebel Application, navigate to Site Map -> Administration Server Configuration -> Profile Configuration
Query For the Profile with Alias Name „JAVA‟ in the profile List and make sure the parameters are correct. Edit the value of VMOPTIONS to -Djms.log=D:\JMS\log\jms.log.
2. Restart the Siebel Server 3. Login to the Siebel Application, navigate to Site Map -> Administration-Business Service ->
Simulator Click on New and provide the following Parameters:
Connect to AIA from your Enterprise via JMS Page 15
Service Name = EAI JMS Transport Method Name = Check CLASSPATH
It should be successful.
If the test fails for Solaris, then go to Administration – Server Configuration Enterprise Profile Configuration Query for JAVA In the below applet for CLASSPATH parameter paste the correct path:
/export/home/qa2/JMS:/export/home/qa2/JMS/Siebel.jar:/export/home/qa
2/JMS/SiebelJI_enu.jar:/export/home/qa2/JMS/j2ee/home/lib/adminclien
t.jar:/export/home/qa2/JMS/j2ee/home/lib/jndi.jar:/export/home/qa2/J
MS/j2ee/home/lib/jta.jar:/export/home/qa2/JMS/j2ee/home/oc4jclient.j
ar:/export/home/qa2/JMS/j2ee/home/lib/bcel.jar:/export/home/qa2/JMS/
j2ee/home/lib/jms.jar:/export/home/qa2/JMS/j2ee/home/lib/javax77.jar
:/export/home/qa2/JMS/jdbc/lib/ojdbc14dms.jar:/export/home/qa2/JMS/l
ib/dms.jar:/export/home/qa2/JMS/opmn/lib/optic.jar:/export/home/qa2/
JMS/j2ee/home/lib/ejb.jar:.
Restart the Siebel Server. Check the classpath again by simulator.
4. Now change the Method Name to CheckJNDIContext. With the following input arguments:ome\lib
folder.
Field Enter:
SendUsername anonymous
ConnectionFactory java:comp/resource/TestJmsRP/QueueConnectionFactories/QCF
SendQueue java:comp/resource/TestJmsRP/Queues/AIA_TESTJMSQUEUE
Connect to AIA from your Enterprise via JMS Page 16
5. Change the Method Name to Send, and keep the input arguments the same as in above step.
Once the simulator test is successful, configure the application workflow with the above configurations. Make sure that the „outbound web service‟ that is being called has been configured to have the transport type „JMS‟ and the address to point to correct queue details. Example:- jms://java:comp/resource/TestJmsRP/Queues/AIA_TESTJMSQUEUE@java:comp/resource/TestJmsRP/QueueConnectionFactories/QCF
Connect to AIA from your Enterprise via JMS Page 17
Workflow Steps In this method we call the proxy business service in the workflow and post the message over JMS with Queue details so that message will be enqueued in the Queue. Workflow details are as follows:
Workflow Process for Submit Order
Description of individual steps: 1. Start Generic Step 2. Get Order
Field Enter:
Type Business Service
Business Service Name EAI Siebel Adapter
Business Service Method Query
Input Arguments:
Input Argument Type Property Name
PrimaryRowId Process Property Object Id
OutputIntObjectName Process Property Integration Object Name
Output Arguments:
Output Argument Type Property Name
SiebelMessage Query Output Message Query Output Message
In this step of the workflow Query Method of business service “EAI Siebel Adaptor” is called that takes “ObjectId” as the input argument. Return an output argument of Siebel Message of type Integration Object that will be input to the next step of the workflow process. 3. Convert to XML
Field Enter:
Type Business Service
Connect to AIA from your Enterprise via JMS Page 18
Business Service Name EAI XML Converter
Business Service Method IntObjHierToXMLDoc
Input Arguments:
Input Argument Type Property Name
SiebelMessage Process Property Opportunity Message
Output Arguments:
Output Argument Type Property Name
XMLMessage Output Argument XML Message
In this step of the workflow IntObjHierToXMLDoc Method of business service “EAI XML Converter” is called that will convert the Siebel Message to XML format. This output argument will be passed as the input argument to the next step. 4. Send
Field Enter:
Type Business Service
Business Service Name EAI JMS Transport
Business Service Method Send
Input Arguments:
Input Argument Type Property Name
<Value> Process Property
XML Message
ConnectionFactory Literal
ConnectionUsername Literal
SendQueue Literal
SIEBEL_JMS: JMSPriority Process Property
SIEBEL_JMS: JMSPriority
Send Method of the business service “EAI JMS Transport” is called. It will take the XML Message, Connection Factory Name, Username, Queue Name and JMSPriority as the input arguments and enqueue it in the Oracle AQ. This web service call is of asynchronous type so there is no output for this web service call.
5. End Generic Step
Connect to AIA from your Enterprise via JMS
December 2008
Author: Srikanth Somayajula
Contributing Authors:
Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.
Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
www.oracle.com
Copyright © 2009, Oracle. All rights reserved.
This document is provided for information purposes only
and the contents hereof are subject to change without notice.
This document is not warranted to be error-free, nor subject to
any other warranties or conditions, whether expressed orally
or implied in law, including implied warranties and conditions of
merchantability or fitness for a particular purpose. We specifically
disclaim any liability with respect to this document and no
contractual obligations are formed either directly or indirectly
by this document. This document may not be reproduced or
transmitted in any form or by any means, electronic or mechanical,
for any purpose, without our prior written permission.
Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective owners.