ESB Lesson07 Page 1
Oracle ESBLesson07: OEMS: JMS (AQ) to DB PL/SQL
Oracle Integration Product Management
ESB Lesson07 Page 2
JMS 1.1 interface
databasememory file
J2EE application Core Java ESB, BPEL
JMS 1.1-compliant messaging provider3 persistence options
OEMS (Oracle Enterprise Messaging Services)
ESB Lesson07 Page 3
Requirements
This lesson requires Oracle Database 10g (EE, XE, …)
(Oracle Olite is not enough)
ESB Lesson07 Page 4
Goals
1. Demonstrate how to configure the JMS adapter (inbound) against AQ
2. Demonstrate how to configure the Database adapter to invoke a PL/SQL stored procedure
3. Discuss promotion of projects from dev to prod (and related resource providers considerations)
ESB Lesson07 Page 5
Scenario Overview
• An ESB service is listening on a JMS topic (OEMS database persistence) for new employee notifications.
• Upon receiving such messages it will invoke a stored procedure to insert the new employees in the company database.
ESB Lesson07 Page 6
Configuration Steps
Steps- Prepare DB accounts- Create store procedure- Create destinations in AQ- Create a new ESB project- Create inbound JMS Adapter- Create outbound DB Adapter- Configure routing service- Configure server resource
providers- Register service- Execute
ESB Lesson07 Page 7
Step 1 – Unzip Tutorial Files• If you haven’t already, unzip ESBSamples.zip to
C:\ESBSamples or any other location.• Make sure ESBSamples\AQJMStoDB is present• Ensure this results in the following tree structure:
ESBSamples\+-- AQJMStoDB\| +-- Readme.txt| +-- schemas\| | +-- ADDEMPLOYEES.xsd| +-- sql\| | +-- accounts_create.sql| | +-- accounts_drop.sql| | +-- procedure_create.sql| | +-- procedure_drop.sql| | +-- topic_create.sql| | +-- topic_drop.sql| +-- tools\| +-- count_messages.sql| +-- receive.class| +-- receive.java| +-- send.class| +-- send.java| +-- setenv.bat| +-- show_durables.sql
ESB Lesson07 Page 8
Step 2 – Prepare Database Accounts
• Open a DOS prompt and cd to this tutorial directorycd \ESBSamples\AQJMStoDB\sql
• set ORACLE_HOME to your database installationex: set ORACLE_HOME=D:\D:\ORACLE\oraclexe\app\oracle\product\10.2.0\server
• execute account creation scriptsqlplus sys as sysdba @accounts_create.sql
(enter sys password when prompted)
ESB Lesson07 Page 9
Step 3 – Create Stored Procedure
• Cd to the sql directorycd \ESBSamples\AQJMStoDB\sql
• execute the provided stored procedure creation script:sqlplus dbapp/dbapp @procedure_create.sql
ESB Lesson07 Page 10
Step 4 – Create Destinations in AQ
(Note: A JMS Topic is a multi-consumer queue table with isTopic set to true in AQ)
• Cd \ESBSamples\AQJMStoDB\sql
• using the provided SQL script, create in the database the necessary infrastructure for a JMS topic named JMSDEMO_TOPIC:sqlplus jmsuser/jmsuser @topic_create.sql
ESB Lesson07 Page 11
Step 5 – Create a New ESB project
• Open JDev• Right-click on your demo
application (left pane) and select “New Project”
• From the project gallery, select a project of type “ESB Project”
• Name that project “AQJMStoDB”
ESB Lesson07 Page 12
Step 5a – Create the inbound JMS Adapter service
• Click on Component Palette (right of the screen)
• Drag and drop a JMS Adapter on the project.
ESB Lesson07 Page 13
Step 5b – Create the inbound JMS Adapter service
1. Enter "ListenForNewEmployees" as the Name for your service.
2. Create a new System/Group=“DefaultSystem.AQJMStoDB“ :
1. click on the torch light2. click on the + sign3. Select ServiceGroup and
enter “AQJMStoDB” as the name
12.1
2.2
2.3
ESB Lesson07 Page 14
Step 5c – Create the inbound JMS Adapter service
1. Back to main JMS Adapter Service creation screen, click on “Configure Adapter” icon in “Adapter Service WSDL”
2. Leave Service Name as "ListenForNewEmployees", then Next3. Select Oracle Enterprise Messaging Service (OEMS) as a JMS Provider.4. Pick "Database" from the persistence drop-down menu, and Next.
1
432
ESB Lesson07 Page 15
Step 5d – Create the inbound JMS Adapter service
1. Next to "Connection", click on "New" to create a new connection..2. Enter "OEMS" as Connection Name, Connection Type: "Oracle (JDBC)“3. Enter your authentication credentials.
Username: "jmsuser", Password: "jmsuser". Check "deploy password". Hit "Next".(…)
1
2
3
ESB Lesson07 Page 16
Step 5e – Create the inbound JMS Adapter service
1. On the Connection Details screen, ensure that the Driver is set to "thin",Host Name is set to "localhost", JDBC Port is set to "1521" and SID is “XE".Click Next.
2. Test Connection and then click Finish.
1
2
ESB Lesson07 Page 17
Step 5f – Create the inbound JMS Adapter serviceBack to the JMS Adapter wizard:1. Select Consume Message as Operation Type and click Next.2. Enter "OEMS" for Resource Provider3. next to Destination Name, click on Browse...4. Under Destinations, All Types, JMSUSER you should see
JMSDEMO_TOPIC (topic). Select it. OK.5. Enter a "Durable Subscriber ID": NewProvisioningESB
1
2
4
3
5
ESB Lesson07 Page 18
Step 5g – Create the inbound JMS Adapter service
1. Click on Next.2. Under Message Schema, next to Schema
Location, click on Browse...3. Click on Import Schema File icon (top right)4. Hit the light torch icon and navigate to the
directory where you placed this tutorial. Select the ADDEMPLOYEES.xsd schema. OK. Make sure the "Add to Project" checkbox is checked. OK.
5. Expand Imported Schemas / ADDEMPLOYEES.xsd and select InputParameters. OK.
6. Next. 7. Finish.8. Note that ESB also created a routing service
downstream of your JMS Adapter
3
4
5
6
ESB Lesson07 Page 19
Step 5h – Create the outbound RDBMS adapter
1. Click on Component Palette (right of the screen)2. Drag and drop a Database Adapter on the NewEmployee.esb project3. Click "Next", "Database Adapter", "Next", Service Name="CreateEmployee",
Ensure System/Group is set to " DefaultSystem.AQJMStoDB ".4. In the "Adapter Service WSDL", click on "Configure Adapter Service WSDL" icon. This starts the
adapter configuration wizard.
3
4
ESB Lesson07 Page 20
Step 5i – Create the outbound RDBMS adapter
1. Leave "CreateEmployee" as Service Name, then hit "Next".
2. Next to "Connection", click on "New" to create a new connection with the following parameters:1. Connection Name: "EmployeeDB" 2. Connection Type: "Oracle (JDBC)"3. Username: "dbapp“4. Password: "dbapp“5. Check "deploy password".6. Driver: "thin“7. Host Name: "localhost“8. JDBC Port: "1521" 9. SID: “XE“
3. Ensure your connection test is successful and then click "Finish".
(for detailed steps, see connection configured during JMS Adapter configuration)
2
ESB Lesson07 Page 21
Step 5j – Create the outbound RDBMS adapter
1. You should be back to the Adapter Configuration Wizard. Click "Next".
2. Select an operation type: check "Call a Stored Procedure or Function"
3. On the Schema screen, select “DBAPP” then click on "Browse..." and pick ADDEMPLOYEES under "Stored Procedures", OK.
4. Next and Finish.5. You should be back to the "Create Database
Adapter Service" screen, with the Adapter Service WSDL info filled in. Click OK.
2
3
35
ESB Lesson07 Page 22
Step 5k – Configure the ListenForNewEmployees routing service
1. Dbl-click on ListenForNewEmployees routing service2. Select the Routing Rules tab3. click on the + icon to add a rule4. Expand and select ESB/Services
in project/DefaultSystem/AQJMStoDB/CreateEmployee/CreateEmployee service. OK.
5. dbl-click the transformation icon.6. Select Create New Mapper File
and accept default name.7. Select EMPS on the left-hand side
of the mapper and drag it over to EMPS on the right-hand side. Accept defaults of the Auto Map Preferences.
8. Save and close the tab for the mapper.9. Save and close the tab for the routing service.
3
4
7
ESB Lesson07 Page 23
Step 6 – Design is complete
• The design phase is complete. It is time to promote the project for testing.
ESB Lesson07 Page 24
Promoting your projects from dev to prod
Before registering your project on the server, you need to ensure that the resources you were referring to in JDev are also available to the server. Ex: datasources.
Also: you might want the server to actually use different resources that the ones you were using during design.
Administrators should create matching datasources on the ESB server, using the same logical names but pointing to actual production resources.
AQJMStoDB project
JDev
DevelopmentRDBMS
ResourceProvider =
“EmployeeDB”
AQJMStoDB project
ESB
ProductionRDBMS
ResourceProvider =
“EmployeeDB”X
ESB Lesson07 Page 25
Non-managed vs Managed Connections• Non-managed mode
• Connection info specified in the WSDL
• Default out-of-the-box (wizard captures design time connection info assuming this as runtime connection)
• Managed mode (Toplink)• Connection info specified in oc4j-ra.xml via JNDI entry
• Above JNDI entry referred to in the WSDL
• Managed mode (OC4J) [Recommended]• Connection info specified in data-sources.xml
• Above data-source referred by JNDI entry in oc4j-ra.xml
• Above JNDI entry referred to in the WSDL
ESB Lesson07 Page 26
Note on Non-Managed Mode
Unless you are using some of the preconfigured resource providers (such as the one for OC4J-JMS), you WILL have to update the app server config files.
Ex: JMS Adapter against the database provider.
In managed mode, you will need to edit:1. oc4j-ra.xml2. (data-sources.xml)3. application.xml
In non-managed mode, you will need to edit:1. application.xml
ESB Lesson07 Page 27
Configuring Server
1. Shutdown SOA Suite2. Configure application.xml and oc4j-ra.xml for JMS
Adapter3. Configure application.xml and oc4j-ra.xml for
Database Adapter4. Restart SOA Suite5. Register ESB project
6. Test
ESB Lesson07 Page 28
Step 7a – Configuring a JMS Adapter in managed modeValues you will need from your project
JNDI name (B)
Use in oc4j-ra.xml
Resource Provider Name (A)
Use in application.xml and oc4j-ra.xml
ESB Lesson07 Page 29
Step 7b – JMS Adapter: configuring database resource provider (application.xml)
• Go to your ESB server install.Navigate to %ESB_HOME%\ j2ee\home\configEx: cd D:\ORACLE\OracleESB_beta\j2ee\home\config
• Open application.xml and add the following entry:
<resource-provider class="oracle.jms.OjmsContext" name="OEMS"><description>Resource provider for the OEMS database</description><property name="url"
value="jdbc:oracle:thin:jmsuser/jmsuser@localhost:1521:XE" /></resource-provider>
Match RP name in your project (A)
ESB Lesson07 Page 30
Step 7c – JMS Adapter: configuring JMS connection factories (oc4j-ra.xml)
• Go to your ESB server install, down to the JMS adapter deployment. Ex:D:\ORACLE\OracleESB_beta\j2ee\home\application-
deployments\default\JmsAdapter
• Open oc4j-ra.xml and add the following entry:
<connector-factory location="eis/Jms/OEMS" connector-name="Jms Adapter"><config-property name="connectionFactoryLocation"
value="java:comp/resource/OEMS/TopicConnectionFactories/myTCF"/><config-property name="factoryProperties" value=""/><config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/><config-property name="isTopic" value="true“/><config-property name="isTransacted" value="true"/><config-property name="username" value="jmsuser"/><config-property name="password" value="jmsuser"/><connection-pooling use="none"></connection-pooling><security-config use="none"></security-config>
</connector-factory>
JNDI Name (B)as specified in
project
Resource Provider Name (A)as specified in project and
application.xml
Can be anything
ESB Lesson07 Page 31
Step 7d – Configuring a Database Adapter in managed modeValues you will need from your project
JNDI name (A)
Use in oc4j-ra.xml
ESB Lesson07 Page 32
Step 7e – Database Adapter (oc4j-ra.xml)
<connector-factory location="eis/DB/EmployeeDB" connector-name="Database Adapter"><config-property name="xADataSourceName" value="jdbc/EmployeeDB-XA"/><config-property name="dataSourceName" value="jdbc/EmployeeDB"/><config-property name="platformClassName"
value="oracle.toplink.platform.database.Oracle9Platform"/><config-property name="usesNativeSequencing" value="true"/><config-property name="sequencePreallocationSize" value="50"/><config-property name="defaultNChar" value="false"/><config-property name="usesBatchWriting" value="true"/><connection-pooling use="none"></connection-pooling><security-config use="none"></security-config>
</connector-factory>
• Go to your ESB server install, down to the Database Adapter deployment. Ex:D:\ORACLE\OracleESB_beta\j2ee\home\application-
deployments\default\DBAdapter
• Open oc4j-ra.xml and add the following entry:JNDI Name (A)as specified in
project
ESB Lesson07 Page 33
Step 7f – Database Adapter (data-sources.xml)
• Go to your ESB server install.Navigate to %ESB_HOME%\ j2ee\home\configEx: cd D:\ORACLE\OracleESB_beta\j2ee\home\config
• Open data-sources.xml and add the following entries:
<managed-data-source name="EmployeeDB-XA" connection-pool-name="EmployeePool" jndi-name="jdbc/EmployeeDB-XA"/>
<managed-data-source name="EmployeeDB" connection-pool-name="EmployeePool" jndi-name="jdbc/EmployeeDB"/>
<connection-pool name="EmployeePool"><connection-factory factory-
class="oracle.jdbc.pool.OracleDataSource" user="dbapp" password="dbapp" url="jdbc:oracle:thin:@//localhost:1521/XE">
</connection-factory> </connection-pool>
Datasourcenames as
specified in oc4j-ra.xml
ESB Lesson07 Page 34
Step 7g – Restart server
opmnctl stopall
opmnctl startall
Debugging
Look at the following log files:
%ESB_HOME%\j2ee\home\log\home_default_group_1\oc4j\log.xml
%ESB_HOME%\opmn\logs\default_group~home~default_group~1.log
If required, set logger levels in ASControl for:
to FINE
ESB Lesson07 Page 35
Step 8 – Register!
That should be it for the design-time – time to test our new employee provisioning service!
• Save All• Right click on the AQJMStoDB project, select "Register with ESB",
"LocalIntegrationServer“• You should get a confirmation dialog
ESB Lesson07 Page 36
Step 9 – Check the ESB control
Open your ESB console (http://localhost:8888/esb/esb/EsbConsole.html).You should see a service similar to this:
ESB Lesson07 Page 37
Step 10 – Send a JMS message to trigger the new service
• Open a DOS prompt and go to the tutorial directory, under toolsex: cd C:\ESBSamples\AQJMStoDB\tools
• Edit setenv.bat to reflect your environment (classpath)• Edit oems.properties to reflect your server settings (location, port, sid, etc..)• Then send a message as below:
C:\ESBSamples\AQJMStoDB\tools>setenvC:\ESBSamples\AQJMStoDB\tools>java Send JMSDEMO_TOPIC-------------------------------------------------------------OEMS.155 - simple JMS send / JMS 1.02 / Database AQ / no JNDI-------------------------------------------------------------Connection factory = oracle.jms.AQjmsTopicConnectionFactory@ab95e6
destination: JMSUSER.JMSDEMO_TOPICmessage :
<?xml version = '1.0' encoding = 'UTF-8'?><db:InputParameters xmlns:db="http://xmlns.oracle.com/pcbpel/adapter/db/DBAPP/ADDEMPLOYEES/">
<EMPS><EMPS_ITEM>
<FNAME>John</FNAME><MIDDLE>W</MIDDLE><LNAME>Doe</LNAME><ADDR>
<STREET>100 Oracle Parkway</STREET><CITY>Redwood Shores</CITY><STATE>CA</STATE><ZIP>94065</ZIP>
</ADDR></EMPS_ITEM>
</EMPS></db:InputParameters>
message was sent with ID=ID:F85494669F764BFAB51CC75367D07B35
ESB Lesson07 Page 38
Step 11 – Checking execution in the ESB Control
Open your ESB console (http://localhost:8888/esb/esb/EsbConsole.html).Click on “Instances” in top right cornerClick on the green arrow next to “Search”You should see one instance as below:
ESB Lesson07 Page 39
Step 11 – Checking execution from sqlplus
Check that new employee was added to the employee_table:
1. Open a DOS prompt2. Issue the following commands:
D:\>sqlplus dbapp/dbapp@XE
SQL*Plus: Release 10.2.0.1.0 - Production on Wed Sep 6 17:09:53 2006
Copyright (c) 1982, 2005, Oracle. All rights reserved.
Connected to:
Oracle Database 10g Express Edition Release 10.2.0.1.0 - Production
SQL> select * from employee_table;
NAME
---------------------------------------------
LOCATION
--------------------------------------------------
John W Doe
100 Oracle Parkway, Redwood Shores, CA 94065
ESB Lesson07 Page 40
Appendix A – create_procedure.sql
create type address as object (
street varchar2(20),
city varchar2(15),
state char(2),
zip integer
);
/
show errors;
create type person as object (
fname varchar2(15),
middle char,
lname varchar2(15),
addr address
);
/
show errors;
create type employees as table of person;
/
show errors;
create table employee_table (name varchar2(45), location
varchar2(50));
create procedure addemployees(emps in employees) as
e_name varchar2(75);
e_location varchar2(75);
p person;
begin
for i in emps.first .. emps.last
loop
p := emps(i);
e_name := p.fname || ' ' || p.middle || ' ' || p.lname;
e_location := p.addr.street || ', ' || p.addr.city || ', '
|| p.addr.state || ' ' || p.addr.zip;
insert into employee_table values (e_name, e_location);
end loop;
commit;
end;
/
ESB Lesson07 Page 41
Appendix B – topic_create.sql
exec dbms_aqadm.create_queue_table(queue_table=>'JMSDEMO_QUEUE_TABLE',
queue_payload_type=>'sys.aq$_jms_text_message',multiple_consumers=>true);
exec dbms_aqadm.create_queue(queue_name=>'JMSDEMO_TOPIC',
queue_table=>'JMSDEMO_QUEUE_TABLE');
exec dbms_aqadm.start_queue(queue_name=>'JMSDEMO_TOPIC');
commit;