Custom Jersey WADL generation

I had a situation where the auto generated WADL did not match with my Rest services.
The first difference was that the response is presented as an object instead of a collection of objects and the second one is that it could not handle JSONWithPadding as response.  Because I use this WADL in my Rest client generation, I need to fix these issues.

Lucky for me, Jersey JAX-RS allows us to provide the necessary WADL input files so the generated WADL matches with the Rest services.

To make this happen I did the following steps.

First I extended the WadlGeneratorConfig class in which I defined the following properties applicationDocsStream, grammarsStream,  resourceDocStream. These vars point to the xml files which will be used in the WADL generation.

We need to add the following init param com.sun.jersey.config.property.WadlGeneratorConfig to the Jersey servlet. This init param points to your WadlGeneratorConfig class

The first file is the application-doc.xml ( located in my src folder ),  this will be used for the Title and high level description of your Rest service.

<applicationdocs targetnamespace="http://research.sun.com/wadl/2006/10">
 <doc title="Oracle HR Demo API" xml:lang="en"> This is a paragraph that is added to the start of the generated application.wadl </doc>
</applicationdocs>

Next is the application-grammars.xml  ( located in my src folder )  this file contains the location of your own XML schema which contains all our XML Elements and Complextypes.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<grammars xmlns="http://wadl.dev.java.net/2009/02"     xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xi="http://www.w3.org/1999/XML/xinclude">
   <include href="../xsd/schema.xsd" />
</grammars>

Add the schema.xsd with the right definitions to the xsd folder located in the web folder of the web application.

The last file is the resourcedoc.xml, this file will be generated by the Maven javadoc plugin.

To generate the content of this file we need to add some javadoc annotations to our Rest Operation methods
For example the response.representation.200.qname annotation points to the employees element (schema.xsd).

Also the response.representation.200.example annotation points to an example object.

Add the Maven JavaDoc plugin with com.sun.jersey.wadl.resourcedoc.ResourceDoclet to your project pom and generate the resourcedoc.xml

Example of a resourcedoc.xml

Startup your Webapp and now the WADL looks like this

Here is my github demo project.

Coherence 12.1.2 Rest application build with OEPE

With WebLogic 12.1.2 Oracle also released a new version of Coherence and OEPE. The 12.1.2 release contains many new Coherence features like WebLogic Managed Coherence Servers and Coherence Grid Archive ( GAR ) which can be included in an normal EAR. Coherence also has some nice new REST features like direct & named queries,  Custom Query engines and new Security options.
Plus with OEPE you can develop Coherence applications in Eclipse and it has Coherence editors for all the Coherence configuration files.

In this blogpost we will test these tools and features in a demo application which uses the HR Oracle demo schema, JPA and expose these entities as Coherence REST Services.

We start by downloading OEPE Eclipse runtime bundle with WebLogic 12.1.2, Coherence and ADF http://www.oracle.com/technetwork/developer-tools/eclipse/downloads/index.html

Start OEPE and define a new workspace.

Create an Oracle Coherence Application

Provide a project name and make sure you define a target runtime.  Plus enable Add project to EAR.

Use the default Coherence options.

The Coherence application will also add a dynamic Web project.

JPA Project
For this demo I will use JPA so we can use these entities in Coherence.

Also target this to WebLogic 12.1.2 and add this project to the already existing EAR project.

Define an connection to the database this will also add a persistence unit to the JPA project.

Next choose JPA entities from tables, where I select the Departments and Employees tables for this demo

Change the JPA mapping relations between the Department and Employee entities and add for REST the XML annotations.
Like @XmlRootElement(name="Department")  and @XmlTransient on the getters to break the loop of loading the Department and Employee objects.

Coherence Project

Next step is to configure the Coherence.
We can use the OEPE Coherence Editors or go directly to the source tab.

First we change coherence-cache-config.xml file where we will define the Department and Employee cache and connect this to EclipseLink.

HrJPA is the name of the Persistence Unit ( Resource Local )

Create a new file called coherence-rest-config.xml, this contains our REST entity definitions where we add some coherence named queries and enable the direct query option.

<key-class>java.lang.Integer</key-class> must match with the primary Java Data type of the entity


The last file we need to change is the pof-config.xml and add <include>coherence-rest-pof-config.xml</include> to the user-type-list

Also upload the coherence-rest.jar to the lib folder of the CoherenceJPA project.

Web project
Last step is to enable the Web project for Coherence REST. We need to enable the Oracle Coherence Facet on this Web Project.

Remove all the Coherence files located in the src folder, we don't need this.

Add the following Coherence REST Servlet.

Also we need to add the following Jersey and Jackson jars files to the WEB-INF lib folder. ( Located  in the module folder of the oracle_common )

Also create your own servlet, so we can fill the Department and Employee Coherence cache ( else the cache will be empty )

In the Eclipse Servers tab we need to add an WebLogic Domain with a Managed Coherence Server ( maybe use right click to select an WebLogic target other than the default AdminServer.

For we Coherence REST we need to change the default EclipseLink JAXB provider.

Add these parameters to Server startup arguments to the Managed Server
-Dcom.sun.xml.ws.spi.db.BindingContextFactory=com.sun.xml.ws.db.glassfish.JAXBRIContextFactory 
-Djavax.xml.bind.JAXBContext=com.sun.xml.bind.v2.ContextFactory

Publish the EAR from OEPE which also contains the Grid Archive (GAR) to the Coherence Managed Server

Finally we can test the Rest service
Start by invoking the servlet http://wls12:7201/CoherenceJPAWeb/CoherenceServlet

Next we can use a Rest Client to test all the Rest operations.

Get all the department entries
http://wls12:7201/CoherenceJPAWeb/rest/Department

Get Deparment 100
http://wls12:7201/CoherenceJPAWeb/rest/Department/100

Add a new Department

 Delete a department

Direct query ( enabled in the coherence rest config xml )
http://wls12:7201/CoherenceJPAWeb/rest/Department?q=departmentName='Finance'

Location1700 Named query also defined in the coherence rest config xml

Location Named query with a integer parameter

Here you can download or look at the github demo project.

JAX-WS SOAP over JMS

With WebLogic 12.1.2 Oracle now also supports JAX-WS SOAP over JMS. Before 12.1.2 we had to use JAX-RPC and without any JDeveloper support. We need to use ANT to generate all the web service code. See this blogpost for all the details.

In this blogpost I will show you all the necessary JDeveloper steps to create a SOAP over JMS JAX-WS Web Service  ( Bottom up approach) and generate a Web Service Proxy client to invoke this service, plus let you know what works and what not.

We start with a simple HelloService class with a sayHello method.

After this we can start the Create Java Web Service wizard.

Select our HelloService class

Select our sayHello method

This will generated the following code.  Besides @WebService , @WebMethod and @WebParam annotation we can change the name attribute of the WebParam annotation and optional add the WebResult annotation.

Next step is to add the @JMSTransportService annotations on this HelloService class.
This will import com.oracle.webservices.api.jms.JMSTransportService class.

When we click on this annotation we modify all the JMS transport properties in the JDeveloper property window

We can also change this Web Service activation properties.

With this as result.

I will use localhost as jndiURL, when you change this to the server url ( you can't deploy it to an other server)  but then you can invoke this JMS service by generating a JAX-WS proxy client without changing anything.

Before we can deploy this Web Service to a WebLogic Domain we need to extend this domain with the WebLogic JAX-WS SOAP/JMS Extension ( or add $WebLogicHome/common/templates/wls/wls_webservice_soapjms.jar template with WLST )

This will create the following Queues and Connection Factory in its own JMS module and JMS Server

We can deploy the Web Service to the JAX-WS WebLogic Domain. 

Also retrieve the WSDL with HTTP.

The WSDL show all our JMS properties in the SOAP Binding and as one string in the soap address location attribute.

Next step is generating a JAX-WS Client and invoke this JMS service. 

Select our Web Service,  from there we can generate a new Web Service client.

Do this in a new project called JmsClient

Enable Copy WSDL into Project.

Leave the default url as it is, even when it is not valid.

Next we can change the PortClient class so it won't use HTTP to invoke this service. 

The documentation says we can do this in 3 ways ( for me only one way really works )

We can JMSTransportClient annotation to our Service class

@WebServiceClient(name = "HelloService",
                  targetNamespace = "http://jms.ws.amis.nl/",
                  wsdlLocation = "http://localhost:7101/...")

@JMSTransportClient (
 targetService = "HelloService",
 destinationName ="com.oracle.webservices.api.jms.RequestQueue",
 replyToName = "com.oracle.webservices.api.jms.ResponseQueue",
 jndiURL ="t3://devagent30:7001",
 jndiInitialContextFactory="com.oracle.webservices.api.jms.ConnectionFactory" ,
 jndiConnectionFactoryName="weblogic.jms.ConnectionFactory" ,
 timeToLive=1000,
 priority=4,
 messageType=JMSMessageType.TEXT)

public class HelloService_Service extends Service {

or as JMSTransportClientFeature in our PortClient class.

JMSTransportClientFeature feature =
  JMSTransportClientFeature.builder()
    .targetService("HelloService")
    .jndiURL("t3://devagent30:7001")
    .destinationName("com.oracle.webservices.api.jms.RequestQueue")
    .replyToName("com.oracle.webservices.api.jms.ResponseQueue")
    .destinationType(JMSDestinationType.QUEUE)
    .messageType(JMSMessageType.TEXT)
    .jndiInitialContextFactory("com.oracle.webservices.api.jms.ConnectionFactory")
    .priority(4)
    .build();

HelloService_Service helloService_Service =
  new HelloService_Service(url,new WebServiceFeature[]{feature});

But the only thing what works for me is changing the SOAP service address location url

like this

HelloService helloService = helloService_Service.getHelloServicePort();

BindingProvider bp = (BindingProvider) helloService;
bp.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"jms:jndi:com.oracle.webservices.api.jms.RequestQueue"+
"?targetService=HelloService&"+
"replyToName=com.oracle.webservices.api.jms.ResponseQueue&" +
"jndiURL=t3://devagent30:7001&messageType=TEXT&"+
"deliveryMode=PERSISTENT&priority=4");

System.out.println(helloService.sayHello("hi"));

You can now invoke the JMS Service with proxy client and check the message count on the request and response queue in the WebLogic console.

Here you can look and download my test project.