OracleSOASuitHandbook AppendixC May2011

Oracle 11g SOA Suite Handbook:Appendix C May 25, 2011
(pn)Part V
(pt)Appendices
(cn)Appendix C
(ct) Configuration of Adapters and SOA Suite Infrastructure
(1) Preparation and Configuration of the SOA Suite infrastructure

The SOA Suite is a complex piece of software that contains various infrastructure
components and that interacts with many services and facilities both in the WebLogic Server
platform and offered by external providers. Through the technology adapters, the SOA Suite
interacts with database, JMS, Advanced Queuing, FTP, File System and other technologies.
Other facilities engaged by the SOA Suite include the User Messaging Service (UMS) for
sending and receiving notifications (email, instant messaging etc.), the Identity Management
services (available through WebLogic‟s OPSS ) and OWSM.
This appendix provides you with detailed instructions for the configuration of some of
these interactions and mechanisms. It helps you to get started with the JMS Adapter and the
Database Adapter, as well as configuring the UMS for sending emails.
Note: these instructions are created for SOA Suite 11gR1 Patch Set 3 and 4 (11.1.1.4 and
11.1.1.5), although they will largely apply to previous patch sets as well.
Installation and configuration of the SOA Suite software

1. Following the normal procedure, make sure to install the Oracle SOA Suite 11g R1 PS 3 on
top of WebLogic Server 11gr (10.3.4) and ensure to also install BPM Suite 11g R1 (PS3) as
an extension of the same WebLogic domain that also hosts SOA Suite.
For this installation to succeed, you first of all need to make an Oracle RDBMS available,
could be 10g XE or 11g R1 or R2 EE. Run the Repository Configuration Utility (rcu) against
this database to create the database schemas and objects required for the run time
environment for SOA Suite and BPM.
C-1
Oracle 11g SOA Suite Handbook: Appendix C May 25, 2011
2. Install the local development environment, consisting of JDeveloper 11g R1 (PS3) with the
SOA Composite Editor and BPM Studio extensions.
Create users in the WebLogic Server LDAP directory

You need to add some users to the identity store that is pre-installed with WebLogic Server. We can
manage the default Security Realm myrealm from the console – a management application that can be accessed at
http://<host>:7001/console – where host is likely to be localhost.
3. Open the WebLogic Server Console in a web browser
4. The Human Workflow services work out of the box with the users defined in this default identity store.
However, you can of course plug in a production quality LDAP server.
For now, let’s create user Maggie as the person to take on all high priority appointment assessments for the
time being. Open the WebLogic console, click on Security Realms in the Domain Structure tree.
C-2
5. Click on myrealm in the Summary window. The click on the Users and Groups tab. The list of current users –
which should at least contain the weblogic user – is presented.
6. Click on the New button in order to add a new user.
C-3
Enter details for Maggie, at least her username and password. Click on OK.
C-4
You could create additional users, such as frank (a colleague of maggie) and the
appointmentmanager.
SoapUI
For testing the SOA Composite applications - reusing test cases over and over again - and
quickly establishing that all required services are indeed available, it is imperative that
SoapUI is installed. This simple, next-next-finish install can be done after downloading the
SoapUI software from: http://www.soapui.org/. No additional configuration is required.
EMail: Server and Client
Installing and Configuring the Java EMail Server

There are several [open source] mail servers available for use with the SOA Suite and of course
commercial offerings including Exchange and SaaS mail providers like Google's GMail can be
used by the SOA Suite. In our environment we will use the Java EMail Server (JES). It is simple,
C-5
easy to install and configure and has a small footprint and runtime overhead. It provides all
functionality we need.
The steps to install and configure the mail server:
1. Download the Java EMail Server from

http://sourceforge.net/projects/javaemailserver/files/JES%201/Version%201.6.1/jes-
1.6.1.zip/download. (check out the home page for the Java EMail Server at
http://www.ericdaugherty.com/java/mailserver/).
2. Extract the contents of the zip file to some directory, for example C:\Program
Files\JavaMailServer.
3. Open mail.conf. Add domain stmatthews.com to the domains entry:
domains=mydomain.com,stmatthews.com
4. Open file user.conf. Add the following user accounts:

user.actionable.account@stmatthews.com=actionable
user.maggie@stmatthews.com=maggiemaggie
user.frank@stmatthews.com=frankfrank
user.appointmentmanager@stmatthews.com=adminadmin
user.patientOne@mydomain.com=patientOne
user.patientTwo@mydomain.com=patientTwo
user.doctorBoris@mydomain.com=doctorBoris
5. Run the command script mail.bat (on Windows) or mail.sh (on Linux). This should start
the mail server. Check the file jes.log in the root directory of the JES. You can also check
the file user.conf: upon successful start up, all clear text passwords in this file will have
been replaced by encrypted counterparts.
C-6
Installing and Configuring the Thunderbird Mail Client

In this training, we will use the Mozilla Thunderbird mail client to connect to this email server for sending
and receiving email. Proceed to install and configure Thunderbird in combination with the local email server.
6. Download Thunderbird from http://www.mozillamessaging.com/nl/thunderbird/ and install

according to the instructions.
7. Subsequently, start Thunderbird to create the necessary server settings and accounts.
Open the Tools menu and click on Account Settings.
8. The Account Settings editor appears. Select the node Outgoing Server. Click the Add button to add a
new SMTP Server.
C-7
9. Enter the details for our mail server: a description (a human readable label) and the server name
(probably localhost). The default port of 25 is okay. Click OK to create the SMTP server. Optionally click
on the Set Default button if you have multiple mail servers configured and this one is not [yet] the default
server.
Next you need to create a number of accounts for the users in and around St Matthews:
10. Click on the Add Account button
C-8
Accept the default account type of Email Account and press Next.
C-9
Enter the display name for the account and the email address. This address must correspond with the value that
you have configured in the user,conf file for the Java Email Server. Press Next.
C-10
Specify localhost as the Incoming Server. Press Next.
Enter the incoming user name. This value must correspond with the value that you have configured in the
user,conf file for the Java Email Server.
C-11
Press Next.
Enter the account name. This value too should correspond with the value that you have configured in the
user,conf file for the Java Email Server.
C-12
Press Next. The summary page appears. Press Finish to complete the account creation.
C-13
11. Repeat this same procedure for the other mail accounts that were configured in the user.conf file for the
Java EMail Server (but not the actionable.account@stmatthews.com).
The Thunderbird client shows all accounts that were just created:
C-14
12. To try out the configuration of both Java Email Server and Thunderbird, you could try to send an email
from Maggie to Frank:
after pressing send and waiting for some time (and perhaps pressing the Get Mail button once or twice) -
the email should arrive:
Configuring Email notification in the SOA Suite

The SOA Suite is configured to use this mail server, to send out notifications and (as we will discuss later
on) receive notifications (emails that are send as the reaction to a task). Take a look at the blog article
C-15
http://technology.amis.nl/blog/6019/configure-soa-suite-11g-for-sending-email-notifications-
with-google-mail for details on configuring notification in the SOA Suite 11g.
One of the ways of the SOA Suite 11g for communicating with the outside world – apart of course from
web service calls and interaction via technology adapters – is through the new User Messaging Service (UMS), a
facility installed in the SOA Domain during installation of the SOA Suite. The UMS enables two-way
communication between users (real people) and deployed applications. The communication can be via various
channels, including Email, Instant Messaging (IM or Chat), SMS and Voice. UMS is used from several components in
Fusion Middleware, for example BPEL, Human Workflow, BAM and WebCenter and can also be used from custom
developed applications.
The User Messaging Service comes with a number of drivers that each handle traffic for a specific channel.
One of the drivers controls the email channel. This driver needs to be configured with the properties of the
Google GMail Server and the email account from which emails are sent.
7. Go to the Oracle Enterprise Manager Fusion Middleware Control Console (typically http://host:7001/em) and
open the User Messaging Service node. From the drop down menu in the right hand pane, select the option
Email Driver Properties:
C-16
The form that is now shown allows you to set various properties on the Email Driver, including the
details about the email server to be used by the driver for email operations.
Set MailAccessProtocol to POP3.
scroll down:
8. The properties that need to be configured for sending emails are indicated in the red
rectangle. They are:
 OutgoingMailServer - localhost
 OutgoingMailServerPort - 25
 OutgoingMailServerSecurity - None
 OutgoingDefaultFromAddress (optional) – the emailaddress that is indicated as the sender
of the email message (appointmentmanager@stmatthews.com)
C-17
 OutgoingUsername – the user account from which the email is sent (can be left empty
when no security is used - otherwise appointmentmanager@stmatthews.com)
 OutgoingPassword – (set type of password to Cleartext) the account‟s password (stored in
encrypted format) (can be left empty when no security is used - otherwise the password
from the user.conf file configured for the Java Email Server for user account
appointmentmanager@stmatthews.com)
Set these properties to the values that are appropriate for your environment.
9. To cater for incoming emails - responses to actionable emails - the following properties
should be set as well:
 IncomingMailIDs - comma separated list of mail accounts that the SOA Suite
should poll for incoming messages. Set to actionable.account@stmatthews.com.
 IncomingUserIDs - comma separated list of user accounts whose mail accounts

the SOA Suite should poll for incoming messages. Set to
actionable.account@stmatthews.com.
 IncomingUserPasswords - comma separated list of the passwords of the user

accounts whose mail accounts the SOA Suite should poll for incoming messages. Set to
the password for user id actionable.account@stmatthews.com.
C-18
10. Click on Apply:
To have these settings take effect, the SOA Server has to be restarted. You can use the options Shutdown and
Start in the dropdown menu option Control to restart the managed server soa_server1. First you may want
to attend to the Workflow Notification properties:
11. We need to set the Workflow Notification Properties - to specify how the workflow should send its
notifications and how it should receive responses to actionable emails. Open option SOA Administration |
C-19
Workflow Notification Properties from the drop down menu on the soa-infra node on soa_server1:
12. The Workflow Notification Properties are shown. Only one is really important at this point: the Notification
Mode (default value is None) must be set to either All or Email, otherwise any notification is not really sent
onwards by the SOA Suite to UMS!
C-20
Note: the Actionable Address is important when you want emails to be actionable - in other words: when
you want users to be able to send in responses (outcomes) to tasks by email. The account used to receive emails
that are in fact the (re)action by a user on a task should be specified here. No human agent should interfere with
this account.
Configure email addresses for users in identity store

Next, we need to go to the identity store to specify the email addresses for the users that need to
receive notifications.
13. Using the default myrealm security realm, we can go to the Web Logic Server console
(http://<host>:7001/console). Navigate to the Security Realms, select myrealm and go to the Users and Groups
tab. Click on user Maggie and navigate to the Attributes tab.
C-21
14. Locate the attribute mail and set it to the email address you have configured to receive notifications at (for
Maggie or the user in your environment). Activate the changes in the console using the button in the upper
left hand corner when so prompted.
When Maggie were to check her Preferences page in the worklist application, she would find that a
Business Email address has been added on the Notification tab. This entry is derived from the identity store – and
cannot be maintained in the worklist application.
Note: if you have other users defined in WebLogic's LDAP directory - like Frank or the
Appointmentmanager, you may want to set their email address attribute too.
Test the email configuration of the SOA Suite

The easiest way to verify whether the email configuration for outgoing notifications is correct, is
by creating, deploying and running a near-default BPEL process that sends out a notification to
user maggie - for whom an email account is configured.
The steps:
15. Run JDeveloper. Create a new SOA Composite application. Accept all defaults. Select the
template with a BPEL component. Again, accepts all defaults.
C-22
16. Open the BPEL editor for the BPEL component.
17. Drag an Email component to the BPEL process and drop it between receive and (callback)
invoke:
C-23
18. Double click the Email activity. Configure the activity's settings and provide some content
for the email:
19. Deploy the composite application.
20. Run the application through the test facility in the EM FMW console.
C-24
21. Check whether Maggie (and patientOne) receive their emails.
Database Schema and Objects

Part of the St Matthews infrastructure is a relational database where patient information is
managed. To represent this database in our local environments, we will create a dedicated
database schema that will hold the same objects as this Patients Database. Note that we will use
the same database that holds the SOA Suite infrastructure environment (not normally a best
practice but rather pragmatic for our purpose).
The DDL and DML statements that are required for these steps can be found in the file
PatientsDatabaseSetup.sql.
22. As a database user with DBA privileges - such as SYS or SYSTEM - create schema
patients_mgt using the statement in the sql-file (adapted to your specific environment). Also
grant the privileges as indicated in this file.
C-25
23. Connect to the database as the new user patients_mgt. Use the DDL statements in the file
PatientsDatabaseSetup.sql to create tables PATIENTS and MDP_DOC_APT_REQUESTS,
types PHYSICALCHARACTERISTIC, PHYSICALCHARACTERISTIC_TBL_T and
PATIENT_T. Finally create package PATIENT_DATA_SERVICES, both specification and
body.
24. Use the two insert statements in this file to create the first two patient records.
25. Now open JDeveloper and create a database connection to the patients_mgt schema.
Open the Resource Palette. Open the navigation panel with IDE Connections. Click on the
Database node (or the New icon at the top). Select New Database Connection in the menu.
Specify the connection name - Patients - and the configuration details for this database
connection:
C-26
Test the connection and upon success, click OK to close the editor.
C-27
26. We can now inspect the objects in the Patients schema using the database [connection]
navigator options in JDeveloper. For example:
Data Source and Database Adapter - Configuring the WebLogic

Server for database access
The technology adapter services rely on resource adapters configured in the WebLogic Server to
which the composite application is deployed.
For each database schema that needs to be accessed through the Oracle database adapter, a new
instance needs to be created and configured with a data source. Data sources are a standard
J(2)EE resource, typically available in application servers. Each data source represents the
connections to a specific schema in some database. Each database adapter instance references
exactly one data source - one that connects to the database and schema required for the adapter
instance. The data source in turn can be used by many different consumers, including web
applications. A data source is associated with a connection pool, a collection of reusable JDBC
connections to the database. Applications reserve, use, and then return these connections to the
pool, thereby ensuring minimal resource usage and maximum scalability. The connection pool
C-28
and the connections within it are created when the connection pool is registered, usually when
starting up WebLogic Server or when deploying the data source to a new target.
The JCA configuration file that is created for a database adapter service in a SOA Composite
Application contains a reference to the JNDI name of a specific database adapter instance in the
WebLogic Server. In order for the application to run successfully, this adapter instance must
have been prepared by the administrator of this server. One could argue that a list of the required
adapter instances should be an explicit element in the deliverables handed from development to
the test and production environment.
After installing the SOA Suite 11g, there is already one database adapter instance configured. Its
JNDI name is eis/DB/SOADemo and it refers to a data source also created during the installation,
called SOADataSource with JNDI name jdbc/SOADataSource. This data source is configured to
connect to the SOAINFRA schema created by the Repository Creation Utility.
Illustration 1 - the relations between the Database Adapter instance and the Data Source
C-29
Our own SOA applications will most likely connect to other database schema in other databases
than the one provided by this SOADataSource. Therefore we need to create both a new data
source - connecting to the desired target schema and database - as well as a new database adapter
instance, associated with this new data source. We will refer to the JNDI name of the database
adapter instance in the configuration of the database adapter service in the composite application.
We need to go through the following steps:
1. Open the WebLogic Administration Console - available at http://<SOA Suite

host>:7001/console. Login with the administrator credentials also used for accessing the
Enterprise Manager Fusion Middleware Control and for deploying the SOA Composite
applications; the default credentials are weblogic/weblogic1.
2. Click on the Data Sources node in the domain structure browser on the left side of the page,
under Services/JDBC.
Illustration 2 - Data Sources in the WebLogic Server Administration Console
C-30
Click on New to create a new JDBC Data Source.
3. The Data Source creation wizard is started. The first step lets you provide the values for
several identifying properties, such as the name of the data source and the JNDI name that is
used to locate the data source. Make sure the name starts with the jdbc/ prefix, for example
jdbc/PatientsDatabase. Accept the defaults for the database type and the Database Driver -
assuming of course that you will connect with an Oracle database.
Illustration 3 - First page in Data Source creation wizard for identification details
C-31
When you press the Next button, the second page provides some information about the
transaction support available with this data source. There are no choices to be made or
values to be provided.
When you press Next, the third page comes up. This is where you provide the database
connection details.
4. The same properties need to be provided as in the database connection editor in JDeveloper:
host, port and SID or database service name as well as username and password.
Illustration 4 - Page three in Data Source creation wizard for connection properties
5. The last page displays a summary of the details you provided. It also has a test button that
you can use to verify that a connection can be to the database schema, using these details.
C-32
After a successful test, click on Finish to conclude the wizard and have the data source
created.
The Summary of Data Sources page is shown. The new data source is listed along with the
preexisting ones.
Illustration 5 - Summary of Data Sources
6. Click on the newly created one. Inspect its details. Go to the tab labeled Targets. Here you
will find a list of the WebLogic servers in the SOA Domain. The checkboxes indicate
whether the data source is deployed on the server. Make sure that this checkbox is checked
for the soa_server1; if it is not, check the box and press the Save button.
C-33
Illustration 6 - Deploying the Data Source to the required targets
Configure Database Adapter Outbound Connection [Pool]

Now that we have configured the Data Source, we can go over to the creation of the new data
adapter instance.
7. Click on the node labeled Deployments in the domain structure browser. In the list of
deployed application that is shown, click on the DbAdapter deployment.
We are taken to the Settings for DbAdapter. Click on the Configuration tab and select the
Outbound Connection Pools within that tab. The currently configured adapter instances are
listed - you should see the preinstalled eis/DB/SOADemo instance we mentioned before.
C-34
Illustration 7 - The Outbound Connection Pools in the DbAdapter deployment
8. Press the New button. Select the javax.resource.cci.ConnectionFactory Outbound

Connection Group by clicking on the radio button (there is only one option available
anyway).
Illustration 8 - Select the Outbound Connection Group
9. Press the Next button. On the next page we have to specify the JNDI name for the database
adapter instance. This is the name we will configure in the database adapter services that we
C-35
create in JDeveloper as part of SOA Composite applications. The name

eis/DB/patientsDatabase is used in this environment.
Illustration 9 - Specify the JNDI name for the Outbound Connection (aka database adapter
instance)
Now press the Finish button.
10. The next page shown is the Save Deployment Plan assistant (this page is only shown the first
time you add a new database adapter instance). The definition of the new database adapter
instance needs to be saved in a deployment plan that is used to extend the configuration of
the DbAdapter deployment when next we restart the WebLogic server. Provide a valid path
and file name.
C-36
Illustration 10 - Enter the name and location for the Database Adapter deployment plan
Then press Save. A success message should be shown, indicating that the deployment plan
has been created and prompting you to restart the DbAdapter deployment. However, before
we do that, we need to associate this new database adapter instance with the JDBC Data
Source jdbc/PatientsDatabase.
11. Click on the Configuration tab and subsequently on the Outbound Connection Pools child
tab. Expand the node javax.resource.cci.ConnectionFactory to show the list of database
adapter instances that should include the new eis/DB/patientsDatabase instance. Click on the
link for that instance. You are taken to the Outbound Connection Properties page. Click on
the cell for the xADataSourceName property in the Property Value column. An editable field
appears. Type the name of the JDBC data source that is to be used by this adapter instance.
Press enter to submit the name of the data source.
C-37
Illustration 11 - Enter the value of the xADataSourceName
After the table has been refreshed with the new property value, press the Save button.
12. The DbAdapter deployment needs to be restarted for all changes to take effect. Go to the
Control tab. Check the box in front of DbAdapter and stop the deployment using one of the
options in the Stop dropdown shown just above the table. When the DbAdapter is stopped,
make it run again. During start up, the new deployment plan is fully activated.
Note: in my experience, changes are not always taking effect with just this update or restart
of the DbAdapter deployment. For example I frequently ran into the exception “Missing
Property Exception. Missing Property: [DBManagedConnectionFactory.userName].” In my
(local) development environment I tend to bounce the entire WebLogic Server, to be sure of
the application of my changes.
C-38
Behind the scenes

The Database Adapter is packaged in a file called DbAdapter.rar, located in the
FMW11G_HOME\Oracle_SOA1\soa\connectors directory. This archive contains the file ra.xml,
which describes the configuration properties of the Database Adapter. The preconfigured
database adapter instance is defined in the deployment descriptor file, weblogic-ra.xml.
Additional, user defined adapters are described in the deployment plan that is created when the
first changes to the database adapter are applied. The database adapter deployment plan is loaded
and applied after the weblogic-ra.xml file has been loaded. With every save of changes in a
database adapter instance configuration is the database adapter deployment plan updated.
Testing the Configuration for Data Source and Database Adapter

The quickest way to ensure that your configuration of data source and database adapter is sound,
is probably by creating, deploying and testing a very simple SOA Composite application that
tries to make use of the database adapter. Let's see how that works:
1. Open JDeveloper. Create a new SOA Composite Application. Accept all defaults. Select the
Empty Composite template.
2. Open the Composite editor - if it does not open by itself. Drag the Database Adapter to the
References area.
C-39
3. The DB Adapter wizard appears. Call it ReadPatients. Press Next.
In the Service Connection dialog, click the icon to browse for the IDE Connection Patients to
the patients_mgt schema in the database. Select this connection and have it copied to the
application.
Take great care to enter the correct value for the JNDI name of the database adapter
(connection pool): eis/DB/patientsDatabase
C-40
Press Next.
4. Select the operation type 'Select' on the next page:
and press Next.
5. Click on the Import Tables button to select the Table to select data from. Select table
PATIENTS (the only table available). Click OK. Wait a little while. The name of the table
appears in the list of selected tables.
C-41
Click Next.
6. Click on Next until you can click on a Finish button. Accepts all defaults on all pages that
you go through.
7. Back in the composite editor, right click on the Exposed Services area. In the Insert list,
select the option Web Service.
The Create WebService dialog appears. Click on the browse for WSDL icon and select the
C-42
ReadPatients.wsdl that was created when you configured the outbound database adapter
service. Accept all defaults and press OK.
8. Wire the newly created Service1 inbound WebService binding to the ReadPatients database
adapter reference. The database adapter provides the implementation for the WebService.
Here we have the simplest application based on a database adapter I believe, exposing a
perfectly useful data retrieval service.
C-43
9. Deploy the composite application to the SOA Suite.
10. When deployment is complete, open the Enterprise Manager FMW console. Locate the
Project1 service - as the default name is likely to be.
11. Open the Test WebService window for this Project1 service. Press the Test Web Service
button and if the configuration of the Database Adapter and the Data Source is relies on is
correct, the records in the PATIENTS table in the patients_mgt schema show up in the
response:
C-44
When the expected response appears, we have proven that - beyond reasonable doubt - both
the Data Source and the Database Adapter Connection Pool have been set up correctly.
File System directories

Several of the composite applications that we will be deploying make use of directories on the
file system of the server running the SOA Suite. With local deployment, that is just localhost.
In this file system, we need a number of directories from which the SOA Composite applications
will read incoming files and will to which they will write logging and other output files. All file
reading and writing happens through the File Adapter.
To prepare for the file system interaction, it is useful to prepare a number of directories.
13. Create a central directory for all files related to the composite applications of St Matthews,
for example d:\stmatthews or c:\temp\stmatthews on Windows or similar on Linux.
C-45
14. Under this central directory, create the following subdirectories:
 IncomingDoctorsAppointmentRequests - for the incoming appointmentrequests

handled by DoctorsAppointmentRequestsProcessor
 IncomingDoctorsAppointmentRequestsArchive - for the archive of incoming

appointmentrequests handled by DoctorsAppointmentRequestsProcessor
 AppointmentRequestsLogs - for the logfile with all processed appointment

requests, written by DoctorsAppointmentRequestsProcessor
 DentistAppointmentReqeuests - for the big file with all requests for dental
appointments, written by DentistsServiceCenter
(1) Configuring the JMS Adapter

Before we can start using the JMS Adapter as well as external queue clients for sending
and consuming JMS messages, we need to configure the JMS Queue(s). JMS It is not part of the
SOA Suite, but is provided by the Oracle Enterprise Messaging Service (OEMS) in WebLogic
Server 10.3. Administration of JMS is done through the WebLogic Server Console that is
accessed through a browser – typically at http://host:7001/console.
C-46
(2)Configure JMS Queue

First we create the JMS Queue we will use for specific message based interaction. Open
the WebLogic Server Console. In the navigation tree Domain Structure on the left side of the
page, select node JMS Modules under Services, Messages. Click on SOAJMSModule in the list
of JMS Modules. Click on the New button in Resource Summary that appears. Select the radio
button Queue for the type of the JMS resource to create.
Set the Name for the new JMS Queue to financeNewPatientsQueue and its JNDI name to
jms/financeNewPatientsQueue; accept None for the template; press Next.
Select the SOASubDeployment on the next page and the SOAJMSServer from the list of
JMS Servers. Click on Finish
Configuring a new JMS Queue financeNewPatientsQueue in the WebLogic Console
C-47
We now have defined the JMS queue that we can use later on to publish messages on.
Note that this queue is not SOA Suite specific; it is a generic JEE JMS Queue that any Java
application could use.
(2)Configure JMS Connection Factory

We also need to configure a JMS ConnectionFactory to power the JMS Adapter instance
that we will be using – as well as other JMS clients. This connection factory is used by the JMS
adapter and other clients to retrieve JMS connections, for example to the queue we have just
configured.
Return to the Summary of Resources table for the SOAJMSModule. Click on New to
create a new resource, this time of type Connection Factory. Enter a name of patientsJmsCF and
a JNDI name of jms/patientsJmsCF. Click on Finish to create the new resource.
(3)Testing the JMS ConnectionFactory and Queue from Java and the WLS Console
In JDeveloper, create a new project, in this case NewPatientsQueueClient. Add library
WebLogic 10.3 Remote Client – to bring the required JNDI and JMS classes, including
WLInitialContextFactory.
Create class JMSQueueHandler – to handle some of the basic plumbing of working with
JMS Queues. This class sets the JNDI properties, retrieves a ConnectionFactory and looks up the
JMS Queue [destination]. This super class contains the constants for the connection properties to
the WLS 10.3 server that hosts the JMS queues as well as the name of the connection factory
jms/patientsJmsCF.
Next create class NewPatientsQueuePublisher that extends from JMSQueueHandler. This

class uses the ConnectionFactory from the super class to create connection. It then creates a JMS
Session on the JMS connection. On the JMS Session, it creates a JMS Producer for the JMS
Queue [destination] looked up by the super class. Finally it produces a new JMS Message
through this producer. This message contains a text message, standard header properties and if so
C-48
desired custom properties as well. The main method in this class calls method publishMessage to
publish the JMS Message on the indicated JMS Queue.
Run class NewPatientsQueuePublisher to have message published on the JMS Queue.

Then, go to the WebLogic Server Console to verify whether the message was successfully put on
the queue. Open the console (http://host:7001/console). In the Domain Structure on the left side
of the screen, click on Services, Messaging, JMS Modules. Click on the SOAJMSModule in the
table of JMS Modules. Find the JMS Queue financeNewPatientsQueue and click on it. In the
page Settings for financeNewPatientsQueue – click on the Monitoring tab.
Monitor JMS Queues in WebLogic Console
The Monitoring page shows a table with all messages sent to and consumed from this
queue. Check the checkbox in front of the queue and click on the Show Messages button. You
will see a listing of the messages currently on the queue, including the one just sent by Java class
NewPatientsQueuePublisher. Click on that message to inspect message details. The JMS
Message Detail page shows the values of the standard header properties, custom header
properties and of course the message payload.
C-49
Inspect the message on financeNewPatientsQueue sent from the Java producer
We will next implement the reverse procedure: consume a JMS message from the queue
and produce that message from the WebLogic Console.
Create a new Java Class in the same project - NewPatientsQueueClient - we used before.
Call the class NewPatientsQueueListener and have it extend from JMSQueueHandler. This class
should implement interface MessageListener. This interface defines a single method –
onMessage – that is invoked whenever a message appears on the JMS Queue(s) that this class is
registered for as a listener. The class has a method prepareToConsumeMessage. This method
acquires a JMS Connection from the connection factory initialized in the super class. It then
creates a session on the connection. It creates a consumer on the session, for the queue
financeNewPatientsQueue. The class itself is registered as the message listener for the consumer.
When the listener is in place, we can start the JMS Connection.
C-50
At this point, there is nothing left to do in the class, except sit back and relax – waiting
for messages to arrive. The one thing we need to make sure of is that the class „stays alive‟. The
main method contains a loop that listens for keyboard input – ensuring that the thread keeps
running until we press q[uit].
With the consumer set up, we can produce a message – either from the Java Class
NewPatientsQueuePublisher or from the WebLogic Console. In this case, we will do the latter.
Open the WebLogic Console. In the Domain Structure on the left side of the screen, click on
Services, Messaging, JMS Modules. Click on the SOAJMSModule in the table of JMS Modules.
Find the JMS Queue financeNewPatientsQueue and click on it. In the page Settings for
financeNewPatientsQueue – click on the Monitoring tab. Check the checkbox in front of the
queue and click on the Show Messages button. Press the New button to create a new message.
Enter the message text and possibly some properties.
Inspect the message on financeNewPatientsQueue consumed by the Java consumer
Click on the OK button to publish the message. Go back to JDeveloper where class
NewPatientsQueueListener is still running and find that it has received the message sent from the
WLS Console.
C-51
(2)Configuring the JMS Adapter

Now we will configure the connection pool of the JMS Adapter. This adapter application
will make use of the patientsJmsCF to get hold of JMS Connections to the queues and topics it
needs to work with as per request of JMS adapter services. The adapter will produce and
consume the JMS messages on behalf of its invoker – typically a SOA Composite application.
We need to create a directory on the file system of the machine that hosts our SOA Suite
installation. This directory is used for the creation and subsequent deployment of the
configuration details for the JMS Adapter. Create a directory called JMSPlan under the directory
FMW_HOME\Oracle_SOA1\soa\connectors.
Click on Deployments in the Domain Structure tree. In the table with deployments, click
on the JMS Adapter.
Click on the Configuration tab.
C-52
Then click on the tab Outbound Connection Pools.
C-53
Click on the New button. Select the one radio button for IJmsConnectionFactory.
Press Next.
C-54
Enter the JNDI name: eis/Queue/patients. Press Finish.
At this point you may be asked for the location for the deployment plan file. If not, it is
already configured and you can safely ignore the next instruction. Set the path to the
JMSPlandirectory you created earlier. Click OK. Verify if the Deployment Plan property has
been set to the directory you indicated.
Return to the Outbound Connection Pools subtab under Configuration. Expand the
IJmsConnectionFactory node. Click on the node for eis/Queue/patients.
C-55
In the properties page that appears, click on the Property Value cell for the
ConnectionFactoryLocation. Type jms/ patientsJmsCF and press enter.
Then click on Save.
These are the steps to go through when the deployment plan should be updated:
C-56
C-57
(3)Test JMS Adapter

Now that we have configured both the JMS Queue and Connection Factory as well as the
JMS Adapter, it is a good moment to verify that the JMS Adapter is actually working when used
in a SOA Composite application.
Create a new composite application, for example called NewPatientsJMSTest. Create an

XSD document, for example FinanceNewPatients.xsd:
<xsd:schema elementFormDefault="qualified"
targetNamespace="http://stmatthews.hospital.com/finance"
xmlns="http://stmatthews.hospital.com/finance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="NewPatient" type="NewPatientType"/>
<xsd:complexType name="NewPatientType">
<xsd:sequence>
<xsd:element name="firstName" type="xsd:string"/>
<xsd:element name="lastName" type="xsd:string"/>
<xsd:element name="insurancePolicyId" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
Add a Mediator to the composite. Call it PublishNewPatientOnJMSQueue. Specify its

interface later on. Drag the service handle from the Mediator to the Services lane. Call the
service PublishNewPatientMessage. Click on the icon to generate the WSDL. Create the request
message based on the NewPatient element in the XSD document. The service has no reply of
fault message.
C-58
Add a JMS Adapter Service to the References lane. It will be used to publish NewPatient
messages to the JMS queue. The Mediator will pass the request messages that it received to this
adapter service. In the first step of the wizard, specify the service name:
PublishNewPatientMessageForFinance. Next, choose the Oracle Enterprise Messaging Service
(OEMS) and pick the WebLogic JMS implementation. On the next page, select the connection to
the Application Server (the same one you use for deploying SOA Composite applications). On
the Adapter Interface page, select the first radio button that says Define from operation and
schema (specified later). On the next page, choose Produce as the operation type and enter
ProduceNewPatientMessage as the name of the operation.
C-59
C-60
The next page, Produce Operation Parameters, is for configuring the queue and the JMS
adapter connection to use. Enter jms/financeNewPatientsQueue for the queue and
eis/Queue/patients as the JNDI name for the JMS Adapter‟s connection pool to use. You may
want to choose persistent and a time to live of 10 seconds or more (that gives you a chance to see
the messages in the WLS console before they expire).
On the Messages page, select the NewPatient element from the FinanceNewPatients.xsd
document – this defines the structure of the message payload. Note that we could also use the
native format schema builder to work with text messages that do not have an XML structure.
This completes the JMS Adapter Wizard. Press Finish. Next, wire the Mediator to the
JMS Adapter Service. Create the mapping – which is very straightforward, as the message
format for the Mediator request input is the same as the input expected by the JMS service.
Deploy the composite application to the SOA Suite.
In the FMW Enterprise Manager, go to the NewPatientsJMSTest composite application.

Click on the Test button and provide some input for the three elements in the request message.
Click on the button Test Web Service to send the request message. Inspect the message flow
trace for this request and verify that the Mediator was activated and in turn invoked the JMS
Adapter service.
C-61
That should mean that a message has been sent on the JMS Queue
financeNewPatientsQueue. Just like we did before, you can go the WLS Console, navigate to the
Monitor Messages page for this queue and hopefully catch the message before it expires. Check
whether the contents of the message corresponds with whatever you entered on the test
webservice page.
C-62
In addition to trying to catch the message in the WebLogic Console, we can run the Java
Client that listens to the queue and monitor the message‟s arrival there.
C-63

OracleSOASuitHandbook AppendixC May2011

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OracleSOASuitHandbook AppendixC May2011

Uploaded by

Copyright:

Available Formats

Oracle 11g SOA Suite Handbook:Appendix C May 25, 2011

(ct) Configuration of Adapters and SOA Suite Infrastructure

(1) Preparation and Configuration of the SOA Suite infrastructure

Installation and configuration of the SOA Suite software

Create users in the WebLogic Server LDAP directory

3. Open the WebLogic Server Console in a web browser

6. Click on the New button in order to add a new user.

EMail: Server and Client

Installing and Configuring the Java EMail Server

The steps to install and configure the mail server:

1. Download the Java EMail Server from

3. Open mail.conf. Add domain stmatthews.com to the domains entry:

4. Open file user.conf. Add the following user accounts:

Installing and Configuring the Thunderbird Mail Client

6. Download Thunderbird from http://www.mozillamessaging.com/nl/thunderbird/ and install

Open the Tools menu and click on Account Settings.

10. Click on the Add Account button

Specify localhost as the Incoming Server. Press Next.

Configuring Email notification in the SOA Suite

Set MailAccessProtocol to POP3.

 IncomingUserIDs - comma separated list of user accounts whose mail accounts

 IncomingUserPasswords - comma separated list of the passwords of the user

10. Click on Apply:

Configure email addresses for users in identity store

Test the email configuration of the SOA Suite

16. Open the BPEL editor for the BPEL component.

19. Deploy the composite application.

21. Check whether Maggie (and patientOne) receive their emails.

Database Schema and Objects

Data Source and Database Adapter - Configuring the WebLogic

We need to go through the following steps:

1. Open the WebLogic Administration Console - available at http://<SOA Suite

Illustration 2 - Data Sources in the WebLogic Server Administration Console

Click on New to create a new JDBC Data Source.

Illustration 5 - Summary of Data Sources

Illustration 6 - Deploying the Data Source to the required targets

Configure Database Adapter Outbound Connection [Pool]

Illustration 7 - The Outbound Connection Pools in the DbAdapter deployment

8. Press the New button. Select the javax.resource.cci.ConnectionFactory Outbound

Illustration 8 - Select the Outbound Connection Group

create in JDeveloper as part of SOA Composite applications. The name

Now press the Finish button.

Illustration 11 - Enter the value of the xADataSourceName

Behind the scenes

Testing the Configuration for Data Source and Database Adapter

3. The DB Adapter wizard appears. Call it ReadPatients. Press Next.

4. Select the operation type 'Select' on the next page:

and press Next.

9. Deploy the composite application to the SOA Suite.

File System directories

14. Under this central directory, create the following subdirectories:

 IncomingDoctorsAppointmentRequests - for the incoming appointmentrequests

 IncomingDoctorsAppointmentRequestsArchive - for the archive of incoming

 AppointmentRequestsLogs - for the logfile with all processed appointment

(1) Configuring the JMS Adapter

(2)Configure JMS Queue

Configuring a new JMS Queue financeNewPatientsQueue in the WebLogic Console

(2)Configure JMS Connection Factory

Next create class NewPatientsQueuePublisher that extends from JMSQueueHandler. This

Run class NewPatientsQueuePublisher to have message published on the JMS Queue.

Monitor JMS Queues in WebLogic Console

Inspect the message on financeNewPatientsQueue sent from the Java producer

Inspect the message on financeNewPatientsQueue consumed by the Java consumer