ServiceFlow
Page 6 of 48
Page 5 of 48
Oracle Service Bus (OSB) 10.3.1 JCA Transport with DB Adapter
Tutorial Oracle Corporation - ProprietaryUse pursuant to
MACROBUTTON HtmlResAnchor Company Document Usage Instructions
Abstract: This document describes the steps for using the JCA DB
Adapter with OSB
31.Introduction
42.Software Requirements
53.Pre-requisites
64.High level Steps
75.Use Case 1 DB Business Service
75.1Step 1 Generate WSDL for DB operations in JDeveloper
195.2Step 2 - Create OSB Business Service with Non-Managed
Connection Mode
235.3Step 3 - Test OSB Business Service with Non-Managed
connection mode
245.4WLS Console Configuration
255.4.1Configure Data Source
285.4.2Configure DB Adapter Connection Factory
325.5Step 4 Test OSB Business Service with Managed connection
mode
356.Use Case 2 DB Proxy Service
356.1Generate WSDL for DB Poll operation in JDeveloper
416.2Create OSB Proxy Service to poll the database
456.2.1Implement proxy services message flow
476.3Deploy and test OSB Proxy Service
1. IntroductionThis document provides step by step instructions
for creating Oracle Service Bus (OSB) configuration to update and
retrieve application data residing in a database.
In the first use case OSB Business Service, with JCA (DB)
transport protocol, performs database operations such as select,
insert, update, delete, invoking a stored procedure, or executing
any custom SQL against the database. Hence, OSB acts as a proxy
between the client that needs to perform database operations and
the database. Client invokes the proxy service, which uses Route,
Service Callout, or Publish to invoke the JCA business service.
SHAPE \* MERGEFORMAT
In the second use case OSB Proxy Service, with JCA (DB)
transport protocol, polls a database table for new or changed
records. Hence, OSB acts as a proxy between the database and the
backend service that intends to receive changes from the database.
Proxy service polls for database table changes. Proxy service then
uses Route, Service Callout, or Publish to propagate the changes to
the backend service.
SHAPE \* MERGEFORMAT
2. Software Requirements Oracle Database Express Edition 10g
(Oracle XE)
OSB 10gR3 MP1 (10.3.1)
JDeveloper 10.1.3.x3. Pre-requisites
1. All required software installed
2. Create a backup of
JDEV_HOME\integration\lib\DBAdapter.jar
3. Copy
OSB_HOME\eclipse\plugins\com.bea.alsb.transports.jca_\DBAdapter.jar
to JDEV_HOME\integration\lib
4. Create a Customer table with following columns in Oracle XE
database. This document assumes the table is created in the system
schema and the database username/passwd is system/welcome1. Use the
appropriate database schema and credentials as your case might
be.
5. Document assumes some level of familiarity witha. Installing
Oracle XE database, OSB, JDeveloper
b. Creating tables using Oracle XE database.
c. Using OSB proxy and business services, deployment, and
testingd. Using JDeveloper to create projects, and Database Adapter
instances4. High level StepsUse case 1 DB Business Service
performing database operations on behalf of the client.
Specifically, the DB Business Service we implement will insert
Customer records into the Customer table.1. Generate WSDL
representing database operations, and the Toplink file representing
object relational mapping
2. Create Business Service in OSB to invoke database operations
using
a. Service Type = WSDL Web Service (using the WSDL from step
1)
b. Transport Protocol = jcac. Connection Mode = Non-Managed3.
Test the business service with Connection Mode as Non-Managed
(Connection Mode is configured in the JCA Transport specific
properties).
4. Test the business service with Connection Mode as Managed5.
Create Proxy service to expose to client. This step is only for
use-case completeness, as such, it is not described in this
document.
Use case 2 DB Proxy Service polling database changes and
propagating changes to the backend service. Specifically, the DB
Proxy Service we implement will poll the Customer table for
new/changed Customer records and logs received records to the
server console.1. Generate WSDL representing the database (poll)
operation, and the Toplink file representing object relational
mapping
2. Create Proxy Service in OSB to poll the database table
using
a. Service Type = WSDL Web Service (using the WSDL from step
1)
b. Transport Protocol = jca
c. Connection Mode = Managedd. Implement proxy services message
flow3. Deploy the proxy service and test5. Use Case 1 DB Business
Service5.1 Step 1 Generate WSDL for DB operations in JDeveloper
You can skip this section if you are already familiar with
creating the database adapter using JDeveloper.
WSDL for database operations and the top link mapping file are
generated as a result of database adapter creation using the
database adapter wizard in JDeveloper.
1. Create a new application in JDevelopera.
File->New->Application
b. Name: DBContent
2. Create Project
a. Name: DBProject
3. Create Database Adapter
a. Select Project ->Right Click ->New ->Business Tier
->Web Services ->Database Adapter->click OK (DB adapter
wizard comes up)
4. Step 1 of 2 - Service Name: DatabaseOutbound
5. Step 2 of 2 Service Connection
a. Click New to create a new connection (or pick a connection if
one already exists) Create Database Connection wizard comes up
i. Step 1 of 4 (Type)
1. Connection Name: DbConnection22. Connection Type: Oracle
JDBC
ii. Step 2 of 4 (Authentication) provide Database
username/passwd
1. Username: system2. Password: welcome1
iii. Step 3 of 4 (Connection) provide Database connection
information
1. Driver: thin
2. Hostname: localhost
3. JDBC Port: 1521
4. SID: XE
iv. Step 4 of 4 (Testing) - Click Test connection
b. Select the connection created in a
c. JNDI Name: eis/DB/DBConnection2 (NOTE: Remember this JNDI
Name as you will require it when configuring managed connection
factory in WLS Console for Managed connection mode)
6. Step 3 of 3: Operation Type
a. Select Perform an Operation on a Table: leave default (all
operations Insert or Update, Insert Only, Update Only, Delete,
Select)
7. Select Table
a. Click Import Tables - Select the appropriate table you want
to work with
i. Provide appropriate Schema and Name filter and click on Query
to query the tables. For e.g. use Customer% as the Name filter and
select the appropriate schema.
ii. Select Customer table that was created earlier using Oracle
XE) to Selected.
iii. Click Next
8. Step 5 of 7: Relationships
a. Click Next
9. Step 6 of 7: Object Filtering
a. Leave defaults for Object Filtering and Click Next
10. Step 7 of 7: Define Selection Criteria
a. Check Return Single Result Set
b. Click Finish
Following files are created:
DatabaseOutbound.wsdl
DBAdapterOutboundHeader.wsdl
DatabaseOutbound_table.xsd
DatabaseOutbound_toplink_mappings.xml
NOTE: Remember the file system location for these files. You
have to browse the WSDL (DatabaseOutbound.wsdl) and the top link
mapping file (DatabaseOutbound_toplink_mappings.xml) when creating
JCA business service in OSB.5.2 Step 2 - Create OSB Business
Service with Non-Managed Connection Mode
1. Create OSB configuration project followed by OSB Project
2. Create new business service
a. Select Project->Right click->New->Business
Service
3. Configure business service
a. Service Type: WSDL Web Serviceb. Click Browse->Click
Consume
c. Select Service Resource as File Systemd. Specify WSDL
location by clicking Browse for WSDL Location and point to the wsdl
file above (DatabaseOutbound.wsdl)
NOTE: If you did not replace DBAdapter.jar in JDeveloper with
the DBAdapter.jar from OSB, the imported WSDL has an error. You can
fix this by deleting the DatabaseOutboundSelect operation and its
corresponding entry under . See step 3 of Pre-requisites.
If you run into the above error, fix the error as detailed
earlier.
e. Next, on the business service select the WSDL port from the
WSDL that is already imported into the workspace.
f. You will notice the Transport Protocol defaults to jca and
Endpoint URI points to the JNDI name specified in JDeveloper during
Database Adapter configuration (See figure below).
NOTE: The JNDI name is used by the business service to look up
the connection factory if the Connection mode is Managed.
Figure 1: Transport configuration
4. Configure JCA Transport specific configuration on Business
Service
a. Leave all properties as default except
i. Connection Mode: Non-ManagedNOTE: Setting Connection Mode to
Non-Managed helps quickly testing the business service. In this
mode, connection information can be specified in two ways: One, in
the WSDL. This is the case when the property Always use
configuration from JCA WSDL is checked. Two, in the JCA Transport
specific properties, - Connection Factory Properties &
Connection Factory Authentication Properties. In this example, we
use the connection information present in the WSDL.
NOTE: In production, it is recommended to use Connection Mode as
Managed. ii. Specify Toplink file
1. You will notice an error message shown below for the Toplink
file
2. Toplink File property -> Click Browse and select the top
link mappings xml file (DatabaseOutbound_toplink_mappings.xml).
5. Finish You will see the error message go away and the
Non-Managed Connection Mode.
Figure 2: JCA Transport Configuration5.3 Step 3 - Test OSB
Business Service with Non-Managed connection mode
1. Start Weblogic server for OSB
2. Create Server connection in Workshop
3. Right click on the business service->Run As->Run on
server
4. Select Operation as Insert and specify the test data (id must
be unique)
Figure 3: Test console - Request
Figure 4: Test console - Response5. Look at the database to see
the row inserted
Figure 5: Row inserted in the databaseBefore we move to the next
step to test the business service in Managed mode we must create
the Data Source and the Connection Factory using WLS Console. 5.4
WLS Console Configuration
In the previous section, you used the Connection Mode as
Non-Managed to quickly test the business service. In the
Non-Managed mode, connection information in the WSDL is used.
In production, it is recommended to use the Managed Connection
Mode. In the Managed mode, connection information from the
connection factory defined in WLS is used. Endpoint URI of the
business service is the JNDI Name of the connection factory defined
in WLS.
This section provides step by step information on configuring
the Data Source and the Connection Factory using WLS Console.
5.4.1 Configure Data Source
1. In WLS Console Home Page, click on JDBC -> Data
Sources
Figure 5: WLS Console Home Page
2. Click New to create a new Data Source
Figure 6: JDBC Data Source Creation3. Configure JDBC properties
for the data source
a. Name: MyDB
b. JNDI Name: MyDB
c. Database Type: Oracle
d. Database Driver: Oracles Driver (Thin XA) versions: 9.0.1,
9.2.0, 10, 11
e. Click Next
NOTE: Remember the JNDI name for the data source. This is
required when you create Connection Factory for the DB adapter.
4. Transaction Options, click Next
5. Define connection properties->Click Next
6. Click test configuration
7. You MUST see connection test succeeded. Click Next
8. Select Admin server to target to (single server mode)
9. You will see the following message. You are done with
configuring the Data Source.
5.4.2 Configure DB Adapter Connection Factory
1. Click on Deployments on the left side of the WLS Console Home
Page.
2. Click Customize this table on the right and set number of
rows displayed to 100. Click Apply.
3. Scroll down to DBAdapter. Click on DBAdapter
4. Create New Connection Factory
a. Click on Configuration tab, followed by Outbound Connection
Pools tab
b. Select javax.resource.cci.ConnectionFactory and Click New
5. Select javax.resource.cci.ConnectionFactory and click
Next
6. Specify the JNDI Name for outbound connection instance. Next,
click Finish
NOTE: The JNDI Name here MUST match the JNDI Name specified in
JDeveloper. The JNDI Name specified in JDeveloper also becomes the
Endpoint URI of the business service (eis/DB/DBConnection2). See
Step 5c in Configuring Database Adapter in JDeveloper and Step 3 in
Creating business service in OSB.
7. You see the following messages.
NOTE: Two important steps: one, update the deployment plan with
the changes and two; update the deployment with the deployment plan
(See Step 9 for updating deployment with the deployment plan).
If you havent yet created a deployment plan for the DB Resource
Adapter you will be asked to create one. In this case, you MUST
create the deployment plan and then save the changes to the
deployment plan. If you already created a deployment plan, it is
updated with the changes.
8. Update connection factorys Data Source property
a. Select the connection you just created by clicking it
(eis/DB/DBConnection2). You will see the following page
b. Click in the Property Value cell for xaDataSourceName, type
the JNDI Name of the Data Source (MyDB) in the text field that
appears, and then press ENTER.NOTE: Hitting ENTER after typing the
data source name is critical. Otherwise, the value will NOT be
saved. Tab will NOT work either.NOTE: The JNDI Name of the Data
Source is the JNDI Name specified in Step 3 of the section on
Creating a Data Source.
c. Select xaDataSourceName (by clicking on the Check box on the
left) and click Save. You will again see the messages to update the
deployment with the content saved in the deployment plan.
NOTE: In some cases, saving changes to the deployment plan might
generate errors. Just ignore the errors!
9. Updating deployment with the deployment plan
a. Click on Deployments (on the left side) under Domain
Structure
b. Select the DBAdapter by clicking on the check box on the
first column for the DBAdapter row
c. Click Update.
d. You will see the following page. Leave the default (Redeploy
application using following deployment plans). Click Next and then
Click FINISH
NOTE: If you encounter an error by choosing the second option.
Please select the first option (Update this application in place)
and then click Next.e. You will see the following message. You are
now done with configuring and updating the DBAdapter connection
factory along with the Data Source
10. Logout of WLS Console5.5 Step 4 Test OSB Business Service
with Managed connection mode
1. Complete steps in Section 5.4 to configure Data Source and DB
Adapter Connection Factory.2. In Eclipse, go to the Business
Service definition and set the Connection Mode JCA Transport
specific property to Managed
3. Right click on the business service->Run As->Run on
server
4. Select Operation as Insert and specify the test data (id must
be unique)
Figure 6: Test console - Request
Figure 7: Test console - Response
5. Look at the database to see the row inserted
Figure 8: Row inserted in the database6. Use Case 2 DB Proxy
Service6.1 Generate WSDL for DB Poll operation in JDeveloper
You can skip this section if you are already familiar with
creating the database adapter for Poll operation using
JDeveloper.
WSDL for database Poll operation and the top link mapping file
are generated as a result of database adapter creation using the
database adapter wizard in JDeveloper.
1. If JDeveloper application and project exist (from section
5.1) jump to Step 3. Otherwise, create a new application in
JDevelopera. File->New->Application
b. Name: DBContent2. Create Project
a. Name: DBProject3. Create Database Adapter
a. Select Project ->Right Click ->New ->Business Tier
->Web Services ->Database Adapter->click OK (DB adapter
wizard comes up)
4. Step 1 of 2 - Service Name: DatabaseInbound
5. Step 2 of 2 Service Connection. If service connection already
exists (see Section 5.1) simply select the service connection
(DbConnection2) and skip this step.a. Click New to create a new
connection (or pick a connection if one already exists) Create
Database Connection wizard comes up
i. Step 1 of 4 (Type)
1. Connection Name: DbConnection22. Connection Type: Oracle
JDBC
ii. Step 2 of 4 (Authentication) provide Database
username/passwd
1. Username: system2. Password: welcome1iii. Step 3 of 4
(Connection) provide Database connection information
1. Driver: thin
2. Hostname: localhost
3. JDBC Port: 1521
4. SID: XE
iv. Step 4 of 4 (Testing) - Click Test connection
b. Select the connection created in a
c. JNDI Name: eis/DB/DBConnection2 (NOTE: Remember this JNDI
Name as you will require it when configuring managed connection
factory in WLS Console for Managed connection mode)
6. Step 3 of 3: Operation Type
a. Select Poll for New or Changed Records in a table
7. Select Tablea. Click Import Tables - Select the appropriate
table you want to work with
i. Provide appropriate Schema and Name filter and click on Query
to query the tables. For e.g. use Customer% as the Name filter and
select the appropriate schema.
ii. Select Customer table that was created earlier using Oracle
XE) to Selected.
iii. Click Next
8. Step 5 of 9: Relationships
a. Click Next
9. Step 6 of 9: Object Filtering
a. Leave defaults for Object Filtering and Click Next
10. Step 7 of 9: After Reada. Leave default: Delete the Row(s)
that were Readb. Click Next
11. Step 8 of 9: Polling Options
a. Leave Polling Frequency at the default - 5 seconds. b. Set
Database Rows per XML Document to 5
12. Step 9 of 9: Define Selection Criteriaa. Check Single Result
Set. Update select query if required. I left it to be the
default.b. Click Finish
Following files are created (see under
DBContent/DBProject/Resources):
DatabaseInbound.wsdl
DatabaseInbound_table.xsd
DatabaseInbound_toplink_mappings.xml
NOTE: Remember the file system location for these files. You
have to browse the WSDL (DatabaseInbound.wsdl) and the top link
mapping file (DatabaseInbound_toplink_mappings.xml) when creating
JCA proxy service in OSB.6.2 Create OSB Proxy Service to poll the
database1. Skip this step if OSB Configuration project and OSB
Project already exist (see Section 5.2). Create OSB configuration
project followed by OSB Project if not present
2. Create new proxy service
a. Select Project->Right click->New->Proxy Service
3. Configure proxy service
b. Service Type: WSDL Web Servicec. Click Browse->Click
Consume
d. Select Service Resource as File SystemSpecify WSDL location
by clicking Browse for WSDL Location and point to the wsdl file
above (DatabaseInbound.wsdl)
e. Next, on the business service select the WSDL port from the
WSDL that is already imported into the workspace.
f. You will notice the Transport Protocol defaults to jca and
Endpoint URI points to the JNDI name specified in JDeveloper during
Database Adapter configuration (See figure below).
NOTE: The JNDI name is used by the business service to look up
the connection factory if the Connection mode is Managed.
4. Configure JCA Transport specific configuration on Business
Service a. Leave all properties as default Connection Mode is
Managed
b. Specify Toplink file
i. You will notice an error message shown below for the Toplink
file
ii. Toplink File property -> Click Browse and select the top
link mappings xml file (DatabaseInbound_toplink_mappings.xml).
5. Finish You will see the error message go away and the Managed
Connection Mode.
6.2.1 Implement proxy services message flow
Lets create a very simple message flow to log the request
received by the proxy service. In this case, the records picked by
the DatabaseInbound proxy service will be logged to the server
console.1. Create a Pipeline pair
2. On the Request pipeline, add a Stage and a Log action to the
Stage. 3. In the log action log $body (this will be data that is
retrieved from the database).a. Set the severity to Debug in the
Log action
NOTE: Make sure logging is turned on at Debug level from the WLS
Console. Follow instructions in the next section (6.2.1.1).6.2.1.1
Setting Log level to Debug from WLS Console
From WLS Console
1. Click on Environment->Servers
2. Click on Admin Server
3. Select Logging tab
4. Click Advanced
5. Set Minimum severity to Log, Log File Severity Level and
Standard Out - Severity Level to Debug.
6. Click Save and log out of WLS Console6.3 Deploy and test OSB
Proxy Service1. From the Servers tab republish the application
2. Once published the status for the server is updated to
Synchronized
3. You must see the following log on the server console. The two
records created in the Customer table by executing the business
service (DatabaseOutbound) in earlier sections will be picked up by
the proxy service and logged.
< [PipelinePairNode1, PipelinePairNode1_request, stage1,
REQUEST]
Pradeep15470 Great America Pkwy, Santa Clara, CA
Kiran
2 5470 Great America Pkwy, Santa Clara, CA>4. You can execute
the business service (DatabaseOutbound) created earlier multiple
times. This will create multiple records in the Customer table. The
proxy service (DatabaseInbound) will pick up these records at 5
second intervals and log them to the server console. Each XML
document received by the proxy service will contain maximum of 5
records as we set the number of rows per XML Document to 5 during
DatabaseInbound adapter configuration in JDeveloper.NOTE: The db
adapter uses one thread (The activation spec property,
NumberOfThreads, is set to 1 by default) to poll the database. This
thread is never released to the pool and hence appears as being
stuck to the work manager which can result in stack trace in the
system out and server log like the following:
####