Running JAX-RS/Jersey/JSR311 on weblogic

Please check the bottom of this post for the latest information.

Now that JSR311 has been approved I thought it was time to have a quick go at running a simple hello world service using JDeveloper / Weblogic. These instructions should give you enough of a hint though if you are using Ant/Eclipse or some other tool to build your services. Turns out for weblogic there a few issues to be work around first before you will get a running service.

First of all you need to download some jar files, not quite sure why but the jersey folks seem to go about of there way to make things harder for you if you are not using Maven. You need to follow the "Download" link from the main jersey page. (I can't provide a hyperlink as this page moves with each release, this instructions are based on 0.9). The minimum list of jars you need to run simple services is:

• jersey-bundle-*.jar
• jsr311-api.jar
• asm-*.jar

In JDeveloper create a new library against a project with these three jar files in them. Make sure you mark the library as "Deploy Always". For the moment you wont find these jars in a j2ee server.

In the project you want to create you RESTful services in you need to create a web.xml that contains a reference to the root JAX-RS servlet. This wont be required when we get JEE6; but it doesn't take too much effort to put the extra entries in place. Once you have finished your web.xml will look like:

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5" xmlns="http://java.sun.com/xml/ns/javaee">
    <description>Empty web.xml file for Web Application</description>
    <session-config>
        <session-timeout>35</session-timeout>
    </session-config>
    <mime-mapping>
        <extension>html</extension>
        <mime-type>text/html</mime-type>
    </mime-mapping>
    <mime-mapping>
        <extension>txt</extension>
        <mime-type>text/plain</mime-type>
    </mime-mapping>
    <servlet>
        <display-name>JAX-RS Servlet</display-name>
        <servlet-name>jersey</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
        <init-param>
            <param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
            <param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
        </init-param>
        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>project1</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>jersey</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

You need to edit the value for "com.sun.jersey.config.property.packages" to contain a ';' separated list of package names to search. The default configuration class that scans the entire classpath doesn't work on weblogic. Hopefully they will fix this before 1.0 comes out.

So let quickly create a hello world service so we can test things out:

1  package project1;
 2  
 3  import javax.ws.rs.Path;
 4  import javax.ws.rs.GET;
 5  import javax.ws.rs.Produces;
 6  
 7  
 8  @Path("/helloworld")
 9  public class HelloRS {
10   
11      // The Java method will process HTTP GET requests
12      @GET
13      // The Java method will produce content identified by the MIME Media
14      // type "text/plain"
15      @Produces("text/plain")
16      public String getClichedMessage() {
17          // Return some cliched textual content
18          return "Hello World";
19      }
20  }

You have a little bit more work to do to get this working, since JDeveloper doesn't "know" about JAX-RS you have to deploy rather than just run this java file So create a WAR file deployment profile for the project and a EAR file deployment profile that contains the WAR at the application level. Finally create a weblogic-application.xml deployment descriptor for the EAR and add the following text. (In the application navigator go to the "Application Resource Section", then Descriptors->META-INF and the context menu "Create Weblogic Descriptor".

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<weblogic-application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-application.xsd" xmlns="http://www.bea.com/ns/weblogic/weblogic-application">
  <prefer-application-packages>
    <package-name>org.objectweb.*</package-name>
  </prefer-application-packages>
</weblogic-application>

This makes sure that the version of asm that comes with JAX-RS overrides the one that is built into weblogic. Otherwise you get a method not found error when the service deploys. You should now be able to deploy the service and test using a URL such as "http://localhost:7101/Application1-Project1-context-root/helloworld". The context root and machine/port will of course vary depending on your environment.

You can test this in a web browser, or in JDeveloper you can test using the HTTP Analyzer. View->HTTP Analyzer, Create New Message toolbar button and navigate to the "HTTP Content" tab. Put your URL in at the top and change the method to "GET" rather than the default "POST". Send the message as you should get back "Hello World" in plain text.

Right no time left to play today, back to fixing bugs.

Update 9 Dec '08:

There is an alternative to creating the weblogic-application.xml file that I discovered recently. I wasn't happy with this solution as it affected the entire EAR file. Instead you can create a "weblogic.xml" under WEB-INF that looks like this:

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app.xsd" xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
<container-descriptor>
    <prefer-web-inf-classes>true</prefer-web-inf-classes>
  </container-descriptor>
</weblogic-web-app>

This has the advantage of only affecting the .war file you are deploying the restful services in. Also I have found out that this problem with the clashing jar files appears to have gone away in the "next" big release of weblogic, but I can't promise you when or even if you will see this fix.

Update 13 Feb 13 '09: With the release of Jersery 1.0.2 you can now download with the basic dependencies, the json libraries and javadoc from the download page. This makes it much easier for non maven users to pick up and use it. Make sure you include both the -server and -core libraries as the -bundle version is not present in the zip.

• jersey-core-*.jar
• jersey-server-*.jar
• jsr311-api-1.0.jar
• asm-*.jar

Update 24 July '09: You can now download all the core dependencies in one big lump in the jersey-archive take a look at the download page for details.

Update 24 July '09: For weblogic server 10.3.1 aka the R1 release you no longer have to use the "prefer-web-inf-classes" modifier as the namespace in the internal copy of asm has been changed.

Update 12th August '09: (We think this only work for the yet unreleased R11PS1/10.3.2 version) For weblogic server 10.x you can can fix the annotation scanner issue so you no longer have to specify the package location. The failure is caused because ServletContext.getRealPath(...) returns null when you deploy an application as a jar file. You can work around this with the fix for weblogic issue CR299135.

In the simplest case this means your web.xml simplifies to:

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5" xmlns="http://java.sun.com/xml/ns/javaee">
    <servlet>
        <display-name>JAX-RS Servlet</display-name>
        <servlet-name>jersey</servlet-name>
        <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>jersey</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

You could create a weblogic.xml under META-INF, see similar instructions before as to how to create weblogic-webservices.xml:

<?xml version = '1.0' encoding = 'ISO-8859-1'?>
<weblogic-web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://www.bea.com/ns/weblogic/weblogic-web-app http://www.bea.com/ns/weblogic/weblogic-web-app/1.0/weblogic-web-app.xsd"
                  xmlns="http://www.bea.com/ns/weblogic/weblogic-web-app">
  <container-descriptor>
    <show-archived-real-path-enabled>true</show-archived-real-path-enabled>
  </container-descriptor>
</weblogic-web-app>

Or make the changes to config.xml mentioned in the CR' above.

Update 1st December '09: Jersey issue 32 has been resolved, if you pull the latest 1.5ea build you should be able to deploy with no workaround. JDeveloper R11 PS1 will unfortunately still create the weblogic.xml automatically; but we can fix this in a future release once 1.5 is production.

Update 11th of March '10: Some final issues, resolved in Jersey 1.1.5.1 specifically for weblogic. Resolved the null pointer in web scanner and some problems with package level filtering that has been reported here.

Update 25 of May '11: Some problems running Jersey with the Oracle XDK in the latest versions of JDeveloper.