Deploying Jersey (JAX-RS) RESTful Web Services on WebLogic Server

If you have to deploy a Jersey based RESTful web service on WebLogic server, you will have to deploy the jersey library on the WebLogic server and reference it from your weblogic.xml descriptor file.

WebLogic 11g comes bundled with Jersey library but we have to explicitly deploy & make it available for consumption. Use the following command to deploy the Jersey library on your WebLogic server;

java -classpath <Middleware_Home>/wlserver_10.3/server/lib/weblogic.jar weblogic.Deployer -verbose -noexit -source <Middleware_Home>/wlserver_10.3/common/deployable-libraries/jersey-bundle-1.9.war -targets AdminServer -adminurl t3://localhost:7001 -user weblogic -password xxxxxx -deploy -library

This command would invoke the weblogic.Deployer which will deploy the Jersey bundle library as a shared library on your WebLogic server.

Now, all we need to do is to reference this library from the RESTful webservice application via weblogic.xml

<?xml version = '1.0' encoding = 'windows-1252'?>
<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
    <library-ref>
        <library-name>jax-rs</library-name>
        <specification-version>1.1</specification-version>
        <implementation-version>1.9</implementation-version>
        <exact-match>false</exact-match>
    </library-ref>
</weblogic-web-app>

Now, you can deploy your Jersey based RESTful webservice on WebLogic server.

Oracle SOA 11g HTTP POST Send/Receive (with example)

In this post let us see how to send and consume HTTP POST request using SOA 11g.

Sample attached with this post will send a file in base64encoded format as a HTTP POST request and the same will be consumed by another BPEL process which is exposed to consume the file in HTTP protocol.

We will use the following XML schema (XSD) to build our HTTP POST service;

Exposing a SOA 11g BPEL process as a HTTP service (POST):

Step 1: Create a SOA Project with empty composite and name it "HttpPostRestService"

Step 2: Drag and Drop a HTTP Binding adapter on the "Exposed Services" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Service [You will choose "Reference" if you need to consume a HTTP REST service]
Operation Type: Request-Response [For 2-way communication. Choose One-way if the service doesn't return a response]
Operation Name: Defaults to Request-Response [You can change it as you please]
Verb: POST [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: XML [For HTTP POST, you get 2 options url-encoded and XML. Since our payload will be huge, url-encoded will not make sense due to size restrictions]

Step 7: In the Messages dialog, select the RestPost.xsd, <Input> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary page, click "Finish" to complete service

Now that we have completed the HTTP binding service adapter which will expose the SOA 11g BPEL process as a HTTP service, you can choose to build a BPEL process which will consume the POST message for further processing.

Deploy the completed process and obtain the HTTP service URL from EM console. We will invoke this service from another SOA composite.

Consuming a HTTP (POST) service in SOA 11g BPEL process:

Step 1: Create a SOA Project with empty composite and name it "InvokeHttpPostService"

Step 2: Drag and Drop a HTTP Binding adapter on to the "External References" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Reference [Since we are consuming a HTTP service - POST]
Operation Type: Request-Response [Default selection for references]
Operation Name: Request-Response [Default]
Verb: POST [This specifies the HTTP method that will be invoked]
Payload Type: XML
Endpoint: Provide the HTTP URL for the REST service to be invoked.

Step 7: In the Messages dialog, select the RestPost.xsd, <Input> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary screen, click Finish to complete the service adapter

Now, build and complete your SOA composite which will invoke a HTTP service using POST method.

Source code can be downloaded here

Let me know your thoughts in comments section.

WebLogic Application Deployment & Shared Library

In an enterprise application deployment scenario, there are many cases where some libraries are used/referenced by multiple applications. It would indeed be a bad design to include such common libraries with every application deployed on the WebLogic server. Not only does it prevent redundancy of resources on the server, it also consumes valuable space & deployment time - especially when the libraries are huge.

WebLogic server offers the shared library concept using which EARs, JARs, EJBs and WARs can be shared across applications in a WebLogic domain.

Let us now see how to package and deploy a shared library in WebLogic server;

Step 1: Create a folder structure as shown below

Step 2: Copy all the libraries (in this case JAR files) that you would want to share across applications to the lib folder under WEB_INF
Step 3: Create a file under META_INF folder by name "MANIFEST.MF"
Step 4: Contents of the MANIFEST.MF file are shown below

Manifest-Version: 1.0
Specification-Title: CommonJars
Specification-Version: 1.0
Implementation-Title: CommonJars Implementation
Implementation-Version: 1.0
Implementation-Vendor: Oracle
Extension-Name: CommonJars

Step 5: From the root folder location, execute the following command to generate a WAR file

jar -cvf sharedlib.war *.*

Step 6: Now, login to Oracle WebLogic console, choose "Deployments" and deploy the generated WAR as a shared library - steps with screenshots below

Step 7: Now that the shared library is deployed, let us refer this shared library from another application

Open the weblogic.xml file. If it is not present in your application, create this file under WEB-INF folder of your application and refer the shared library as shown below;

<?xml version = '1.0' encoding = 'windows-1252'?>
<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
    <library-ref>
        <library-name>CommonJars</library-name>
    </library-ref>
</weblogic-web-app>

Enjoy sharing libraries across your enterprise applications.

Processing No Namespace XML Messages SOA 11g

Many a time, we encounter messages that are communicable but grammatically unsound.

Applying the analogy of modern day SMS (Simple Messaging Service) or IM (Instant Messaging) conversations, where messages communicated are something like shown below.

hw r u?
doin grt
wassup?

Although these convey intents, yet if you lookup these on a dictionary you will never be able to find a synonym :)

Often in IT sphere, especially in service-oriented architectures where XML is bread & butter, we see transactions from external sources which are XML-ish which are well-formed but doesn't subscribe/conform to a grammar (XSD).

This is more prevalent in cases where XML is constructed by a legacy system where namespaces are ignored.

Okay, how do we then process these XML messages - we don't have any control whatsoever on the sender/generation of the message.

Consider the following example;

<?xml version="1.0" encoding="UTF-8" ?>
<Order>
    <OrderNumber>101</OrderNumber>
    <ProductName>Apple IPad</ProductName>
    <Description>32 GB</Description>
    <Quantity>1</Quantity>
    <Cost>899</Cost>
</Order>

We are facing the same situation as the aforesaid analogy - Although the XML document is well-formed, ensures data integrity, it just doesn't conform to the rule book and hence SOA rejects messages that are not grammatically sound.

If you try and generate a XML schema from the above XML, the XSD will have a target namespace associated.

Based on this XSD, if the SOA project & XML transformations (XSLT) are built, the incoming XML in the above format will not be processed as it doesn't exactly conform to the XSD (No Namespace Definition).

In such cases, XSD must be manually edited to remove targetnamespace and namespace prefixes.

Also, XSLT transformations must be edited based on incoming XML. If there are no namespace, then remove the namespace prefixes in your XPath - disassociating elements from the namespace.

In a little more complex scenario, you may encounter XMLs in the following format (Notice the empty namespaces in sub-elements);

<?xml version="1.0" encoding="UTF-8" ?>
<Order xmlns="http://www.sathyam-soa.blogspot.com">
    <OrderNumber xmlns="">101</OrderNumber>
    <ProductName xmlns="">Apple IPad</ProductName>
    <Description xmlns="">32 GB</Description>
    <Quantity xmlns="">1</Quantity>
    <Cost xmlns="">899</Cost>
</Order>

In this case, the XML document will be consumed successfully by your SOA project but transformations (XSLT) will not be successful. This is because of the empty namespace URIs in the sub-elements although root element contains the proper namespace as per XSD.

To resolve transformation issues, ensure that in your XSLT/XPath, the namespace prefixes for all elements with empty namespace URIs are removed.

/tns:Order/tns:OrderNumber
/tns:Order/tns:Quantity

must be modified to reflect as shown below

/tns:Order/OrderNumber
/tns:Order/Quantity

Reason: Although the root element in the XML document <Order> is qualified with a namespace, empty namespaces for child nodes (xmlns="") negates the qualification and hence these will become hanging nodes.

Learner Series: Build/Consume HTTP REST Services in SOA 11g (with example)

Today REST (Representational State Transfer) has become a norm for building services on the web. REST brings along its own merits & demerits - choice of REST vs SOAP/WSDL, when and where is an architectural decision. So, how does Oracle SOA BPEL support HTTP based RESTful web services.

For all HTTP based interactions, Oracle SOA 11g provides an out-of-box HTTP Binding adapter.

This post will illustrate the following;

a) Expose a SOA 11g BPEL process as a HTTP REST service
b) Consume/Invoke a HTTP REST service from a SOA 11g BPEL process [We will consume service that we will build as part of (a)]

As part of this exercise, we will build a REST service that will take customer name & id as input and greets the customer.

Before dunking into building the SOA composites, let's quickly take a look at the XML schema that will form the REST service contract.

Exposing SOA 11g BPEL Process as HTTP REST service:

Step 1: Create a SOA Project with empty composite and name it "HttpGetRestService"

Step 2: Drag and Drop a HTTP Binding adapter on the "Exposed Services" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

 Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Service [You will choose "Reference" if you need to consume a HTTP REST service]
Operation Type: Request-Response [For 2-way communication. Choose One-way if the service doesn't return a response]
Operation Name: Defaults to Request-Response [You can change it as you please]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [For HTTP GET method, SOA 11g support only payload type of url-encoded (name-value pairs). For HTTP POST, you get 2 options url-encoded and XML]

Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary page, click "Finish" to complete service

Now, drag and drop a BPEL Process on the "Components" section.

Name the process as "GreetCustomerProcess" and choose to define service later.

You can now proceed to build the BPEL process as you please. As part of this sample, I have concatenated the customer name input with "Welcome" prefix so that the service returns the greeting as response.

Finally, deploy this project to your SOA server.

On deployment you can notice that the service is exposed both as a WSDL based webservice and HTTP based REST service. This will enable clients to interface through either standards.

You can test this service either via Enterprise Manager (EM) console - test mode or via normal browser.

For testing your SOA 11g based HTTP service refer to my blog entry here

Consuming a HTTP REST service in SOA 11g BPEL process:

Step 1: Create a SOA Project with empty composite and name it "InvokeHttpGetService"

Step 2: Drag and Drop a HTTP Binding adapter on to the "External References" swimlane in the SOA composite (SCA)

Step 3: Choose Next in the Welcome page of the wizard

Step 4: Enter service name

 Step 5: Choose "Define from operation and schema (specified later)" option

Step 6: Choose the following options and click Next

Type: Reference [Since we are consuming a HTTP REST service]
Operation Type: Request-Response [Default selection for references]
Operation Name: Request-Response [Default]
Verb: GET [This specifies the HTTP method. You have 2 options GET/POST]
Payload Type: url-encoded [Default]
Endpoint: Provide the HTTP URL for the REST service to be invoked. In this case, you can obtain the HTTP URL from enterprise manager console.

Step 7: In the Messages dialog, select the GreetCustomer.xsd, <CustomerInput> and <Response> XML elements for "Request Message Schema" & "Response Message Schema" respectively.

Step 8: In the summary screen, click Finish to complete the service adapter

Now, drag and drop a BPEL Process on to the Components section of your SOA composite. Provide a name to the process, accept other defaults and click OK

Wire the BPEL process with the HTTP Binding adapter in the SOA composite.

Inside the BPEL process, just map the input payload element to the <Name> element of the greeting rest service and deploy to SOA server.

You can now test and check both SOA services in action. One will expose itself as a REST service and the other will invoke it.

Source code can be downloaded here

Let me know your thoughts in comments section.

Testing SOA 11g based HTTP REST services (Resolving Invalid Query String Error)

When a SOA 11g service is exposed as a HTTP service (using HTTP Binding adapter), it can be easily tested through Enterprise Manager (EM) console. Refer here to find out more on how to build/consume/trigger HTTP based REST services in SOA 11g.

However, the purpose of exposing the service accessible via HTTP standard is to ensure it can be directly consumed over a browser.

Typically for a HTTP-GET service, parameters (if any) to the service are passed as query strings (name-value pairs).

From the EM console, HTTP Endpoint for the deployed service can be obtained.

But just invoking the service endpoint via browser along with query string throws the following exception;
 "Invalid Query String"

To resolve this issue, pass the "operationName" query string (mandatory parameter) along.

For eg., if your current endpoint looks like:

http://localhost:7001/soa-infra/services/default/HttpGetRestService/HttpGet?name=Sathya

Modify this to:

http://localhost:7001/soa-infra/services/default/HttpGetRestService/HttpGet?name=Sathya&operationName=Request-Response

Here operation name value is the operation name that was specified during the HTTP Binding adapter creation. By default operation name defaults to "Request-Response".

Creating JDBC Connection Pool in GlassFish Server

Documenting the steps required to create a JDBC data source & connection pool in GlassFish server.

1. Copy the ojdbc*.jar to the following location;
<GLASSFISH_DOMAIN_HOME>/lib/ext

You can find the ojdbc*.jar under the following folder of DB installation;
<DB_HOME>/server/jdbc/lib

Note: Restart your GlassFish server

2. Login as admin user to GlassFish server Admin Console eg., http://localhost:4848/

3. On the home page, choose "Create New JDBC Connection Pool" option. Alternatively, you can also choose Resources -> JDBC -> JDBC Connection Pools from the "Common Tasks" left panel

4. Click "New..." option from the JDBC Connection Pools page

5. Enter the following details in the "General Settings" page

Pool Name: TestPool
Resource Type: javax.sql.DataSource
Database Driver Vendor: Oracle (You can choose appropriate DB vendor here..)

and click "Next"

6. Configure the following "Additional Properties" and leave the other default values

User: DB Username/Schema Name
Database Name: ORCL (SID of your DB connection)
Password: DB Password
URL: jdbc:oracle:thin:@localhost:1521:ORCL
ServerName: localhost
PortNumber: 1521

7. Click Finish

8. In the final page, you can choose to ping the connection to test the connectivity

Lets now create a data source.

9. Go to "JDBC Resources" and choose "New..."

10. Enter a JNDI name (eg., jdbc/test), choose the created connection pool from the list (TestPool) and click on OK.

Now, all your applications deployed on GlassFish server can gain access to your backend via the data source.

Learner Series: Oracle BPEL Receive & Pick Activity With Example

This post is part of the Oracle SOA BPEL learner series.

I have been getting lots of requests to write on basic SOA BPEL use-cases from my blog readers who are starting up on SOA initiatives. One such request that often comes across is the basic difference  between the usage of a pick and receive constructs in a BPEL process.

I have created a working BPEL use-case which contains both pick & receive activities in one SOA project.

A quick introduction to BPEL Pick & Receive Constructs;

Receive Activity: This is the first activity in most of the BPEL processes. As the name indicates, this construct receives information/message from a partner link.

Pick Activity: This activity is very similar to the receive construct. But unlike the receive activity which gets triggered only when a partner link invokes it, the Pick activity has 2 choices (On Message & On Alarm) - It waits for a message from a partner link or triggers another set of activities on timeout.

Use-Case: (Hypothetical but conveys the message)

A BPEL process (ReceivePick) gets a "Customer Name" as input, calls another BPEL process (CustomerCreditScoreWS) to get the customer's credit score. The CustomerCreditScoreWS process validates if the customer name starts with "A" and returns a credit rating immediately; else the process waits for 10 seconds before returning a blank response. The ReceivePick BPEL process waits for a message (credit score) from the CustomerCreditScoreWS process. If it gets a response (On Message: credit score), the process completes by returning a "Success" message; otherwise in the event of not getting a response for 8 seconds (On Alarm: 8 seconds) the process waits and terminates by returning a "Failure".

Receive-Pick BPEL Constructs at a glance

You can download the source code for this sample here

OER (Oracle Enterprise Repository) Reporting Feature (BI Publisher)

Oracle Enterprise Repository (OER) provides total control and manageability of all your SOA assets and also tracing the relationships between various services, business processes and other assets in your enterprise.

By SOA governance through OER, you can gain greater visibility into your SOA assets, reduce redundancy, track usage, credit projects that reuse assets thereby promote reuse of the same - resulting in cost savings & better maintenance.

One of the core features of any SOA governance product is the support to render various reports;

In order to enable OER reports, you will need to have BI publisher installed which will augment detailed analytic & reporting capability to OER. Without this, OER reports screen will display the following message;

Please set the system setting for Report Server URL. Reports cannot be run until this has been properly set.

Once BI publisher is installed, perform the following configurations to enable OER reporting;

Configure BI Publisher with OER:

1. Stop BI Publisher server
2. In the OER server install, Extract the 11.1.1.7.0-OER-BIP11gReports.zip file [This zip file can be found under <OER_HOME>/core/tools/solutions/reports]
3. Copy "OER" folder from the "Oracle" folder (Assuming the install is on Oracle DB - else copy OER folder from appropriate DB folders that are supported) into the following BI publisher directory;

<BIDomain>/config/bipublisher/repository/reports

4. Start the BI Publisher server and verify whether the OER folder is shown under the "Shared Folders" by visiting the following URL;
http://<hostname>:<port>/xmlpserver

Configure OER JDBC Data Source:

1. Login to BI Publisher as admin user (eg. weblogic)
2. Click on the "Administration" tab

3. Under the "Data Sources" section, choose "JDBC Connection"

4. Click on "OER" data source and ensure that BI Publisher can successfully connect to OER

Configuring the Reporting settings on OER:

1. Login to OER as admin user and click on "Admin" tab

2. Click on "System Settings" in the left admin panel

3. In the "Search" text box, type "report" - This will automatically filter the setting results and show only the "Reports" section

4. Ensure that the following properties are set properly

• Enable Reports - True
• Report Server URL - http://<hostname>:&lt:port>/xmlpserver/OER
• Report Server Endpoint URL - http://<hostname>:&lt:port>/xmlpserver/services/PublicReportService
• Report Server Username: admin (user to connect to BI Publisher server)
• Report Server Password: password for admin user

5. Save the settings

Now, go back to the "Reports" page in OER and enjoy generating reports. There are many out-of-box reports that OER provides. You can also create custom reports in BI publisher and make them available in OER - That will be a topic for my next post :)

If you want to enable single sign-on between OER & BI Publisher, then you will have to create a OER user on BI Publisher server and assign the BI groups (OER_Reports) to this user. You will have to then configure this user under the OER reports section for seamless access.

Solving BPM PS6 (11.1.1.7) Webform Rendering Issue

When the server host name is not properly set during SOA installation, BPM picks up the default server URL while rendering webforms. This could cause rendering issue since webform expects full server hostname (localhost or short server hostname will not render the webform content).

Check out here for further configuration required for BPM PS6 WebForms...

Often the easier fix would be to manually update the host name in the enterprise manager for each of the human tasks in the BPM process. But that could be time consuming especially if you have many human tasks in your process and redo this every time you redeploy the process.

To have a permanent fix in place so that all human task webforms in future use the fully qualified hostname, set the FusionAppsFrontEndHostUrl property in your soa-infra as shown below;

1. Login to EM console as administrator (eg. weblogic)

2. Expand SOA, Right-Click on soa-infra -> choose SOA Administration -> Workflow Properties

3. In the resulting "Workflow Notification Properties" screen click "More Workflow Notification Configuration Properties..."

4. Enter the required fully qualified URL in the "FusionAppsFrontEndHostUrl" property in the following format;
*=http://hostname:port

5. Click on "Apply" and save the settings.

Henceforth, all BPM deployments would make use of the FusionAppsFrontEndHostUrl to render the forms.

BPM 11.1.1.7 Composer Web Form Creation

Web Forms are one of the most anticipated features delivered as part of the latest Oracle BPM PS6 release (11.1.1.7). What is so special about it? Well, until PS5 Oracle BPM supported only one form of human task UI development - the out of the box ADF style of development which required the use of Oracle JDeveloper IDE and in complex scenarios invariably required the help of IT dept.

Starting PS6, Oracle BPM supports Web Forms which is a welcome feature especially for business analysts/process owners who have very high business process knowledge but little IT/development. Oracle BPM PS6 allows business users to create & implement a complete end-to-end business process (including user task UIs) from a blank canvas via their web browsers.

However, while trying to create a web form from BPM composer, you may encounter the following error;

Error getting form: OrderProcessForm
Caused by: Could not instantiate form: got wrong status=500

This is just a configuration issue which can be resolved in a jiffy.

Just make a note of the fully qualified machine hostname where BPM PS6 is installed.
For eg., sathyam-lap.oracle.com

1. Login to WebLogic console [http://sathyam-lap.oracle.com:7001/console]
2. Expand Environment and choose Servers from the "Domain Structure" panel

3. Click on the managed server where SOA/BPM is installed from the list of servers [Generally, soa_server1 on port 8001]
4. In the "Settings for soa_server1" page, choose "Protocols" tab from top menu & "HTTP" tab in the sub menu bar [You can update this for all servers to keep the URLs uniform]
5. Update the "Frontend Host" entry with the fully qualified machine hostname

Now, login to BPM composer and try to create/access your webform and it must be rendered properly.
Note that you must always access all server URLs using the fully qualified hostname
eg., http://sathyam-lap.oracle.com:8001/bpm/composer