August 26, 2009

Jersey Test Framework re-visited!

Posted in REST at 6:53 AM by bsnaresh

   One of the previous entries introduced the Jersey Test Framework, which has since been adopted and used by a good number of developers. However, there has been some feedback suggesting ways for making the framework a better one.

Based on all this feedback, we have worked on making some changes in the framework. With the release of Jersey 1.1.2-ea, we have this new version of the framework which is better than the previous version in the following ways:

• Introduced the concept of test container factories
• Various test container types, defined by the different test container factory implementations
• Support for the new In-Memory or In-Process test container
• Loosely-coupled with the test container factory implementations
• Loose coupling allows the definition and pluggability of custom test container factory implementations
• Support for running tests on an application pre-deployed on an external container

But, there have been some major changes in the API, which seemed obvious for the cause.

This entry will describe what are the API changes, and how an user test can be defined, etc.

Breaking changes from 1.1.1-ea to
1.1.2-ea

• The maven project groupId has changed from
  “com.sun.jersey.test.framework” to “com.sun.jersey”. 

                <dependency>

                    <groupId>com.sun.jersey</groupId>

                    <artifactId>jersey-test-framework</artifactId> 

                    <version>1.1.2-ea</version>

                <dependency>

• The extending of Jersey unit test and configuration has changed.

                   The test class has to just pass an instance of AppDescriptor. For instance, the constructor of the spring-annotations sample test, passes this information as follows:

 public SpringAnnotationsWebAppTest() throws Exception {
      super(new WebAppDescriptor.Builder("com.sun.jersey.samples.springannotations.resources.jerseymanaged")
                .contextPath("spring")
                .contextParam("contextConfigLocation", "classpath:applicationContext.xml")
                .servletClass(SpringServlet.class)
                .contextListenerClass(ContextLoaderListener.class)
                .build());
    }

           Note the use of the Builder design pattern, which makes it really easy to define an instance of the AppDescriptor while defining all the application attributes.

• The test container type with which to run the tests has to be specified using the System Property test.containerFactory. Note that it used to be container.type till the previous version.
• Unlike the previous implementation, the test container type value is not a string which maps to the container type, but the fully qualified class name of the test container factory is passed as value for the property test.containerFactory.

   mvn test -Dtest.containerFactory=com.sun.jersey.test.framework.spi.container.grizzly.web.GrizzlyWebTestContainerFactory

About the AppDescriptor

            AppDescriptor is an abstract class which is extended by two classes – the LowLevelAppDescriptor and the WebAppDescriptor. These classes allow the definition of the various attributes of the application – like its
context-path, url-pattern, root resource classes or packages, etc. While the LowLevelAppDescriptor can be used is cases were tests are to be run on light-weight containers like Grizzly or HTTPServer, the WebAppDescriptor is used in cases where tests could be run on the web-based containers like EmbeddedGlassFish, Grizzly Web Container, and the light-weight containers as well*.

Test Container Factories

       The test framework comes with a set of test container factory implementations which are responsible for creating the test container(s).

The following low-level test container factories are provided:

• GrizzlyTestContainerFactory for testing with the low-level
  Grizzly HTTP container.
• HTTPContainerFactory for testing with the Light Weight HTTP
  server distributed with Java SE 6.
• InMemoryTestContainerFactory for testing in memory without
  using underlying HTTP client and server side functionality
  to send requests and receive responses.

The following Web-based test container factories are provided:

• GrizzlyWebTestContainerFactory for testing with the Grizzly
  Web container and Servlet support.
• EmbeddedGlassFishTestContainerFactory for testing with
  embedded GlassFish.
• ExternalTestContainerFactory for testing when the Web
  application is independently deployed in a separate JVM to that of the
  tests. For example, the application may be deployed to the
  Glassfish v2 or v3 application server.

Running Tests using Maven

      As previously said, the container on which the tests have to be run is specified using the system property test.containerFactory which holds the fully-qualified classname of the test container factory which creates an instance of the test container, i.e.,

          mvn clean test -Dtest.containerFactory=<container-factory fully-qualified class name>

      Note:

           1. If tests are to be run on external container like GlassFish, the application has to be explicity deployed on the container before running the tests.

               a. Package the application:

               mvn clean package -Dmaven.test.skip=true

               b. Deploy the generated application war file 

               c. Run the tests:

              mvn test -Dtest.containerFactory=com.sun.jersey.test.framework.spi.container.external.ExternalTestContainerFactory

           2. If the  tests are to be run on EmbeddedGlassFish, one additional property container.type has to be set along with test.containerFactory:

              mvn clean test -Dtest.containerFactory=com.sun.jersey.test.framework.spi.container.embedded.glassfish.EmbeddedGlassFishTestContainerFactory -Dcontainer.type=EmbeddedGF 

           3. If the property test.containerFactory is not set, the tests would be run on the Grizzly Web container by default.

Enable Logging

The framework allows the logging of the HTTP requests and responses being sent over the wire during the test process. All that is needed to enable this logging is set the flag enableLogging.

           mvn clean test -Dtest.containerFactory=<test container factory class> -DenableLogging

Programmatically setting the test container factory

      The framework also allows setting the test container factory programmatically. This could be done by overriding the JerseyTest class’s getTestContainerFactory method and returning the appropriate test container factory’s instance. For example if Grizzly Web container has to be set as the default test container factory, it could be done as follows:

    @Override
    protected TestContainerFactory getTestContainerFactory() {
        return new GrizzlyWebTestContainerFactory();
    }

                       That’s a brief description of the new version of the Jersey Test Framework. Please send an email to the Jersey user’s mailing list users@jersey.dev.java.net  in case you have any issues. Wish you a happy testing of your RESTful Web Services       

Permalink 22 Comments

April 17, 2009

Jersey Test Framework makes it easy!

Posted in REST at 6:11 AM by bsnaresh

   Does your application have RESTful Web Services? Do you want to ensure that these services are working properly on a wide range of containers – both light weight and heavy weight ones?

     Have you ever felt the need of an infrastructure setup, which you can use to test your services against all these containers without having to worry about things like deployment descriptors, etc? If so, you have a news. Jersey 1.0.3 got released day before yesterday, and it comes with a testing framework called the Jersey Test Framework. 

     The Jersey Test Framework currently allows you to run your tests on any of the following three light weight containers:

• Embedded GlassFish
• Grizzly Web Server
• Lightweight HTTP Server

The framework is built over JUnit 4.x using Maven.

How do I use the Jersey Test Framework?

          Using the framework is simple. All that you will need  is do this:

1. Add the following dependency to your pom.xml:
• <dependency>
              <groupId>com.sun.jersey.test.framework</groupId>
              <artifactId>jersey-test-framework</artifactId>
              <version>1.0.3</version>
              <scope>test</scope>
   </dependency>
2. Create a class which extends com.sun.jersey.test.framework.JerseyTest.
3. Some minimal number of parameters need to be passed by the test class to the JerseyTest class. This can be done in one of the following ways:
• super(String rootResourcePackage): Pass the root resource package name to the super constructor. This constructor will then take care of initialising, starting and/or stopping the test container.
• super(String contextPath, String servletPath, String resourcePackageName): Pass the application context path, servlet path and root resource package name to the super constructor if you are working on a web application. Again this constructor will take care of initializing, starting and/or stopping the test container.
• super(): When you call the default no parameter super constructor, you still can pass the information to the JerseyTest class by creating an instance of the com.sun.jersey.test.framework.util.ApplicationDescriptor class, setting the parameters using the setter methods defined in that class. This has to be done in your test class’s constructor. Also, a call needs to be made to the JerseyTest class’s setupTestEnvironment(ApplicationDescriptor applicationDescriptor) method. This call would take care of the init, start and/stop of the test container.
4. Annotate your test methods with the org.junit.Test annotation.
5. The handles to com.sun.jersey.api.client.Client and com.sun.jersey.api.client.WebResource instances – client and webResource get inherited from the JerseyTest class. You can use them in your test methods for building URIs and sending HTTP requests.
6. Run the tests using the maven command – mvn clean test. This will by default run the tests against the Grizzly Web Server. If you want to run the tests on the container of your choice, set the system property container.type with one of the following values:
• EmbeddedGF : Makes the tests run against Embedded GlassFish.
• GrizzlyWeb : Makes the tests run against the Grizzly Web container.
• HTTPServer : Makes the tests run against the Simple HTTP Server.
7. The framework also provides an option of seeing the HTTP requests and responses sent over the wire. It could be done by just setting the system property enableLogging, i.e., if you want to see the request and response sent over the wire, while running tests against Embedded GlassFish, execute the following command:
• mvn clean test -Dcontainer.type=EmbeddedGF -DenableLogging
8. And that’s it. You have got the framework working.

Are there any samples which are using this framework?

                 Some of the samples that come with the Jersey distribution have been modified to use this framework. These are:

• helloworld
• helloworld-webapp
• extended-wadl-webapp
• entity-provider
• simple-console
• jsonp
• jaxb

You should try running tests of these samples and see how the test framework works. I’m sure you will like it

If you see some of these samples do not have a deployment descriptor, but still you are able to run the tests against Embedded GlassFish. This is because the framework generates a deployment descriptor on the fly in such cases.

Future Enhancements

It is being planned to support the following features in the coming versions:

1. Support for external containers – GlassFish v2 and GlassFish v3
2. Giving the user an option to specify the containers which his test doesn’t support.

If you have any queries or see any issues with the current implementation or feel there should be something more, please send an email to the Jersey user mailing list – users@jersey.dev.java.net

Permalink 4 Comments

March 2, 2009

Jersey Client API in Action

Posted in REST at 7:54 AM by bsnaresh

In one of the previous entries we saw that Jersey provides a Client API for consuming RESTful Web Services. In this entry, we shall see how to use this API and consume the HelloWorld service.

Before we go ahead and create the client, lets overwrite the HelloResource class with the following code:

@Path("hello")
public class HelloResource {
    /** Creates a new instance of HelloResource */
    public HelloResource() {
    }
    /**
     * Retrieves representation of an instance of
*  mycompany.resources.HelloResource
     * @return an instance of java.lang.String
     */
    @GET
    @Produces("text/plain")
    public String sayHello(@QueryParam ("name") String name) {
        if ( name != null ) {
            return "Hello " + name + "!";
        }
        return "Hello World!";
    }
    @GET
    @Path("{name}")
    @Produces("text/plain")
    public String sayHello2(@PathParam ("name") String name) {
        return "Hello " + name + "!";
    }
}

public static void main(String[] args) {
        // Create Client and Handle to web resources
        String BASE_URI = "http://localhost:8080/HelloWorldWebapp/resources";
        Client client = Client.create();
        WebResource webResource = client.resource(BASE_URI);
        // send a GET request with Accept header set to "text/plain"
        String response = webResource.path("hello").accept(MediaType.TEXT_PLAIN).get(String.class);
        System.out.println(response);
        // send GET request with a query parameter value for 'name'
        response = webResource.path("hello").queryParam("name", "Pranabh").get(String.class);
        System.out.println(response);
        // send GET request to /hello without any query param
        response = webResource.path("hello").get(String.class);
        System.out.println(response);
        // send GET request to /hello/{name}
        response = webResource.path("hello").path("Ranjita").accept(MediaType.TEXT_PLAIN).get(String.class);
        System.out.println(response);
        // send a GET request and get the response encapsulate in ClientResponse
        ClientResponse clientResponse = webResource.path("hello").get(ClientResponse.class);
        System.out.println(clientResponse.getEntity(String.class));
 }

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import javax.ws.rs.core.MediaType;

Hello World!
Hello Pranabh!
Hello World!
Hello Ranjita!
Hello World!

Permalink 6 Comments