Connect To AIA Via JMS White Paper - Oracle · Connect to AIA from your Enterprise via JMS Page 5...

Connect to AIA from your Enterprise via JMS An Oracle White Paper

[December] [2008]

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



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.


HIGH-LEVEL ENTERPRISE TO AIA CONNECTIVITY VIA JMS ARCHITECTURE


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.


JMS CONNECTIVITY ARCHITECTURE FOR ORACLE AQ-JMS PROVIDER


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.


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


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


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


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>



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>


GUIDELINES FOR SETTING UP THE ENTERPRISE APPLICATION

(Example: JMS client setup instructions for Siebel 8.0)

Siebel Application Configuration


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:

http://download.oracle.com/otn/java/oc4j/101330/oc4j_extended_101330.zip


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:


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


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


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:



Business Service Name EAI XML Converter

Business Service Method IntObjHierToXMLDoc

Input Arguments:


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:


Business Service Name EAI JMS Transport

Business Service Method Send

Input Arguments:


<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


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.

Connect To AIA Via JMS White Paper - Oracle · Connect to AIA from your Enterprise via JMS Page 5...

Documents

Transcript of Connect To AIA Via JMS White Paper - Oracle · Connect to AIA from your Enterprise via JMS Page 5...