Create REST WebServices using BC4J

JDeveloper 11.1.1.x and ADF does not provide much support for REST Services, but it does recognize JAX-RS annotations and help configure Jersey. Here are simple steps to create REST Service over ADF Business Components.

1. Create Application Structure
Create Generic Application. Delete generated Project. Add Model Project and Web Project (without Faces). Create Connection (hrdb) to HR Schema.

2. Generate Business Components and Prepare Service API
This is similar to what i did for SOAP Web Service Example.

3. Add dependency to Jersey & Jackson
Add Jersey and Jackson libraries to Web Project.
See my blog about Installing Jersey libraries for JDeveloper. Actually, i am just adding following jars to Project.
jackson-all-1.9.11.jar, asm-3.1.jar, jersey-bundle-1.17.1.jar

4. Create WebService POJO Class
Create POJO class with necessary API method(s). This example is not showing any exception handling, but you can throw Checked Exception to indicate Validation, Application or System type error situations to client.

5. Add annotations
5.1 Add @Path("/hrservice") annotation to HRWebService Java class. Import "javax.ws.rs.Path", when prompted by JDeveloper.

5.2 JDeveloper will provide a hint for you to configure web.xml. You will see a Yellow icon in line gutter next to @Path. Accept the hint and JDeveloper will configure web.xml for Jersey servlet.

 

5.3 Add "com.sun.jersey.api.json.POJOMappingFeature" init param for Jersey servlet in web.xml, value of this init param should be true. This will cause Jersey to use Jackson for generating JSON response. Default implementation (JAXB) has some issues, for example, it will return Object instead of Array if only one item is being returned in List.

5.4 Add GET annotation to getCountryList() method.

6. Add weblogic-application.xml
ADF libraries are included by adding shared library in weblogic-application.xml. This is automatically done if you create Fustion application, otherwise you can add it manually.

7. Test Web Service
Right click Web Service in Application Navigator and select Run or Debug.

Installing Jersey on JDeveloper 11.1.1.x

In order to create REST Services using JDeveloper, you will need to include Jersey jar files in your Projects. I guess you can create other implementations, but Jersey works just fine.

I will be using Jersey 1.17.1, which works great with JDeveloper 11.1.1.x. I have downloaded jersey-archive-1.17.1.zip and jersey-bundle-1.17.1.jar. Ideally you just need jersey-bundle-1.17.1.jar, but it appears that we also need to include asm-3.1.jar from jersey-archive-1.17.1.zip file.

You can just setup Jar files as dependencies on your Project, but it works best if you create a JDeveloper Library. You can install this library on your Developer machine as well as on your Build machine. 

Download - My Extensions Zip Archive

Unzip downloaded myextensions.zip in c:\temp. Using command prompt, go to c:\temp\myextensions. You can now run setup.bat file to install Jersey Library in your JDeveloper installation. You will need to set JDEVELOPER11_INSTALL_HOME environment variable, which should point to your JDeveloper installation.

You can open setup.bat to see what it will copy to your JDeveloper installation. You can obviously modify / extend this to install other types of Libraries.

Once you run setup.bat, start JDeveloper and see Library named My Jersey. (Tools - Manage Libraries).

Create SOAP WebServices using BC4J

ADF Application Module can be enabled as Service Interface (SDO), but i take a different approach to this as shown below.

1. Create Application Structure
Create Generic Application. Delete generated Project. Add Model Project and Web Project (without Faces). Create Connection (hrdb) to HR Schema.

2. Generate Business Components and Prepare Service API
2.1 Generate ADF Business Components using JDevelolper Wizard. Create Application Module later, otherwise initial wizard adds many entries to Application Module's Data Model.
2.2 Create simple POJO for Country object.

2.3 Create service method to return all Country objects. Expose it to Client Interface.

 

Using Application module XML Editor, add this service method to Client Interface (Java tab).

3. Create Web Service POJO class
Create POJO class with necessary API method(s). This example is not showing any exception handling, but you can throw Checked Exception to indicate Validation, Application or System type error situations to client.

Alternatively, you can also start by creating WSDL file to represent your Web Service.

4. Generate SOAP Web Service from POJO
Generate Web Service using JDeveloper wizard. This generates SOAP Web Service only with JDeveloper 11.1.1.x, hopefully future versions of JDeveloper will allow generation of REST Services.

Note annotations added by Wizard.

5. Test Web Service
Right click Web Service in Application Navigator and select Run or Debug.

Why this approach?
1. This approach allows for flexibility in exception handling, as you can control types of exception thrown to client. Service Generation approach from Application Module throws Runtime Exceptions which is seen as SOAP Fault by client and it does not have any useful information.
2. You may want to control WSDL and / or Schema to confirm to your Enterprise Standards, which is possible only when using this approach.
3. This approach is little bit clean, as Web Service and BC4J code is organized in separate projects.

And, It is not at all difficult to generate Web Service from POJO with available Wizards.