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.