Tuesday Feb 07, 2012

JAX-RS 2.0 Early Draft Explained - Java EE 7 Making Progress


JAX-RS 2.0 Early Draft has been available for about 3 months now. JAX-RS 2.0, just like JPA 2.1, was one one of the first JSRs to be filed as part of Java EE 7. Several other specifications in Java EE 7 have released early drafts as well (JavaServer Faces 2.2CDI 1.1, EJB 3.2, and more coming as well) and I'll cover them in later blogs.

Here are the topics covered so far:
JAX-RS 2.0 is a brand new specification and here are the main highlights so far:
  • Client API: The HTTPUrlConnection is too low level and is not RESTful-oriented. Invoking a RESTful resource using this class would look like:

    URL url = new URL("http://.../atm/balance");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("GET");
    conn.setDoInput(true);
    conn.setDoOutput(false);
               
    BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream()));
    String line;
    while ((line = br.readLine()) != null) {
        out.println(line);
    }


    Notice, how much code has to be written and its brittle. Some JAX-RS 1.0/1.1 implementations already provide a higher-level client-side API to access the Web resources. For example, read TOTD #57 for more details about Jersey Client API. A slightly more advanced sample to access Twitter timeline using Jersey Client API is described in TOTD #143.

    JAX-RS 2.0 introduces a standard Client API to in javax.ws.rs.client package to access the Web resource. It also share features with JAX-RS server API (readers/writers).

    A simple usage looks like:

    Client client = ClientFactory.newClient();
    String balance = client.target("http://.../atm/balance")
                           .request("text/plain")
                           .get(String.class);


    Instead of Client client = ClientFactory.newClient(), would you like @Inject Client client then vote for JAX_RS_SPEC-170.

    Path and query parameters can be easily specified using the builder pattern as shown below:

    Client client = ClientFactory.newClient();
    String balance = client.target("http://.../atm/{card}/balance")
                           .pathParam("card", "1111222233334444")
                           .queryParam("pin", "1234")
                           .request("text/plain")
                           .get(String.class);


    See how the template in the target path is automatically substituted with the correct value. The request type is specified to be "text/plain" and GET method of this web resource is invoked. This will be translated to:

    http://.../atm/1111222233334444/balance?pin=1234

    A POST request will look like:

    Money balance = client.target("http://.../atm/{card}/withdraw")
                          .pathParam("card", "1111222233334444")
                          .queryParam("pin", "1234")
                          .request("application/json")
                          .post(text("50.0"), Money.class);

    There is also generic command pattern that enables separation of concern between the creator and submitteruseful for batch processing using Invocation. And the code would look like:

    Invocation inv1 = client.target("http://.../atm/{card}/balance")
                            .pathParam("card", "1111222233334444")
                            .queryParam("pin", "1234")
                            .request("text/plain")
                            .buildGet();


    Invocation inv2 = client.target("http://.../atm/{card}/withdraw")
                            .pathParam("card", "1111222233334444")
                            .queryParam("pin", "1234")
                            .request("application/json")
                            .buildPost(text("50.0"));

    And once the Invocations are ready then they can be invoked.

  • Filters and Handlers: The filters and handlers allow app developers to perform message request pre-processing and response post-processing via well-defined extension points on the client- and server-side. This is yet another feature that was supported by several JAX-RS 1.0/1.1 implementations with each using slightly different semantics and now getting standardized in JAX-RS 2.0.

    Filters are non-wrapping extension points, allow pre-processing without modifying the request itself. A filter implements interface RequestFilter or ResponseFilter or both and is annotated with @Provider. A logging filter that simply logs the message may look like:

    @Provider
    class LoggingFilter implements RequestFilter, ResponseFilter {

        @Override
        public FilterAction preFilter(FilterContext ctx) throws IOException {
            logRequest(ctx.getRequest());
            return FilterAction.NEXT;
        }

        @Override
        public FilterAction postFilter(FilterContext ctx) throws IOException {
            logResponse(ctx.getResponse());
            return FilterAction.NEXT;
        }
    }

    Multiple filters are grouped in filter chains. The response from preFilter and postFilter indicate whether the next filter in the chain need to be executed (FilterAction.NEXT) or stopped (FilterAction.STOP).

    Handlers provide wrapping extension points. A handler implements interface ReadFromHandler or WriteToHandler or both and is annotated with @Provider. A GZIP filter that provides deflate and inflate capabilities may look like:

    @Provider
    class GzipHandler implements ReadFromHandler, WriteToHandler {
        @Override
        public Object readFrom(ReadFromHandlerContext ctx) throws IOException {
            InputStream old = ctx.getInputStream();
            ctx.setInputStream(new GZIPInputStream(old));
            try {
                return ctx.proceed();
            } finally {
                ctx.setInputStream(old);
            }
        }

        @Override
        public Object writeTo(WriteToHandlerContext ctx) throws IOException {
            OutputStream old = ctx.getOutputStream();
            GZIPOutputStream gzipOutputStream =
    new GZIPOutputStream(old);
            ctx.setInputStream(gzipOutputStream);
            try {
                return ctx.proceed();
            } finally {
                gzipOutputStream.finish();
                ctx.setOutputStream(old);
            }
        }
    }

    Multiple handlers are grouped in handler chains. The proceed method must be explicitly called in order for the next handler in the chain to be invoked.

    In the direction of flow the filters always executed before handlers. The following diagram shows the exact execution order on client and server-side:



    The handlers and filters can be associated to each method of a resource specifically using @NameBinding. The specification defines @GlobalBinding to associate handlers and filters to all methods of a resource but the recent version of the specification removes it and makes it a default. Also look at JAX_RS_SPEC-146 that asks for a mechanism to override the global filters/handlers.

    The dynamic binding, enabled by implementing DynamicBinding, provide more control on the association with resources and methods.
  • Hypermedia: Linking resources together is one of the main RESTful principles. There are structural links that are used to avoid sending a complete representation of a resource and enable lazy loading. The clients can follow these type of links to retrieve the "pieces" they need. A transitional link is used to update the state of a resource and is typically identified by a "rel" attribute. Structural links are normally in the entity; transitional links could be in link headers or the entity.

    JAX-RS 2.0 will only support transitional links in headers using newly added Link and LinkBuilder classes. The proposed Client API can also create a target from a link. The code may look like:

    Response r = client.target("/product").request("application/json").get();
    ResponseHeaders rh = r.getHeaders();
    if (rh.hasLink("ship")) {
        client.invocation(rh.getLink("ship")).invoke();
    }


    On the server side, ResponseBuilder has support for adding one or more link headers. The code may look like:

    @Path("/products")
    public class MyResponse {

        @GET
        @Path("{id}")
        @Produces({"application/json", "application/xml"})
        public Response getProduct(@PathParam("id")int id) {
            Product product = new Product(id);
            return Response
                    .ok(product)
                    .link("http://.../orders/" + id + "/ship", "ship")
                    .build();
        }
    }


  • Validation: Web resources must validate data received in query or header parameters or entity bodies. Currently this validation has to be performed in the application code. The Bean Validation specification already defines a extensible mechanism to specify validation constraints on a bean. So the JAX-RS specification leverages that and introduces support for declarative validation. The constraint annotations can be specified in public constructor parameters, method parameters, fields and bean properties. In addition, they can also decorate resource classes, entity parameters and resource methods. Here is a sample class augmented with constraint annotations:

    @Path("/")
    class ProductResource {

        @POST
        @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
        public void addProduct(@NotNull @FormParam("productName") String name,
                               @NotNull @Category @FormParam("category") String category) {
            . . .
        }
    }


    The @NotNull is a pre-defined constraint in the Bean Validation API and ensures that the target parameters are not null. The @Category is a user-defined constraint using the extensible mechanism provided by the Bean Validation API. If the constraints are violated then the resource method is not invoked and instead a response with status code 400 (Bad Request) and an entity that describe the violations is returned to the client.

    Here is a sample code of how to validate request entity bodies when they are mapped to resource method parameters:

    @CheckProduct
    class Product { . . . }

    @Path("/")
    class ProductResource {

        @POST
        @Consumes(MediaType.APPLICATION_JSON)
        public void addProduct(@Valid Product product) {
            . . .
        }
    }


    The presence of @Valid (a pre-defined annotation in Bean Validation API) next to the method parameter ensures that the @CheckProduct constraint is called to verify the mapped entity.

    The JAX-RS specification also defines the sequence to validate root resource class instances. The recommendation is to return as many violations as possible instead of aborting after the first violation is encountered.
  • Asynchronous Processing: JAX-RS 2.0 introduces asynchronous processing on server- and client-side APIs for the usual reasons. The server-side code will look like:

    @Path("/async")
    class ProductResource {
        @Context ExecutionContext ctx;

        @GET
        @Suspend
        public Product longOp() {
            Executors.newSingleThreadExecutor().submit(
                new Runnable() {
                    public void run() {
                        Proruct product = longQueryFromDatabase();
                        ctx.resume(product);
                    }
                }
            );
        }
    }

    The longOp method is invoked when this resource is accessed using GET, forks a new thread, and returns immediately without producing the result. Once longQueryFromDatabase returns the product then the connection is resumed and the response is returned by calling ctx.resume and setting the value.

    ExecutionContext also provide suspend() that allows to override the values, such as timeout, specified in the annotation based upon the runtime state.

    On the client-side, the code will look like:

    Client client = ClientFactory.newClient();
    Future<String> future = client.target("http://.../atm/{card}/balance")
                                  .pathParam("card", "1111222233334444")
                                  .queryParam("pin", "1234")
           
                           .request("text/plain")
                  
                    .async()
                         
             .get();

    The async() is called during building the client request. The return Future<String> can be used to query/cancel the status of execution on the server-side using isDone and cancel. Once the response is ready then Future<T>.get() is invoked to receive an instance of T if the response was successful or null if the invocation failed.

    Optionally an InvocationCallback<T> may be registered during the request invocation. The completed method is called when the invocation completes successfully and a response is available and failed method is called when the invocation fails. The code looks like:

    Future<String> future = client.target("http://.../atm/{card}/balance")
                                  .pathParam("card", "1111222233334444")
                                  .queryParam("pin", "1234")
           
                           .request("text/plain")
                  
                    .async()
                         
             .get(
                                      new InvocationCallback<String>() {
                                          @Override
                                          public void completed(String result) {
                                              // got the correct result
                                              System.out.println(result);
                                          }

                                          @Override
                                          public void failed(InvocationException error) {
                                              // ouch, got an error!
                                              System.err.println(error.getCause());
                                          }
                                      }
                                   );


    Notice, the type of the result is specified as type parameter to InvocationCallback.

    Client and server developers optimize their resources (threads) depending upon their needs and are independent of each other. A client really can't tell if a resource is implemented asynchronously or not and shouldn't even need to know.

  • Improved connection negotiation: This would allow a server to specify a preferred MIME type if the client does not care about it. This can be easily specified using the "qs" qualifier as shown below:

    @Path("/")
    class ProductResource {

        @GET
        @Produces({ "text/xml
    ;qs=0.75", "application/json"})
        public Product[] getProducts() {
            . . .
        }
    }


    The default server-side qs-value and the final order of server-side served types preferences follow the same rules as those specified for HTTP Accept Header. Per those rules an unspecified value takes the default value of 1. So the above @Produces rule says "application/json" will be served as the preferred type if there is no Accept header from the client. The section 3.5 talks more about qs parameter and the section 3.8 in the specification provide complete details about how media type of the response is chosen by a JAX-RS runtime.

The Appendix D in the specification provide a comprehensive list of changes from the previous version of the specification.

Here are some final set of references for you:

And of course, it'll all be delivered as part of GlassFish 4.0!

Learn the latest and greatest about JAX-RS 2.0 from Marek Potociar's talk on JAX-RS at Devoxx 2011:

Wednesday Aug 04, 2010

TOTD #143: Retrieve Twitter user timeline using using Jersey and OAuth

The Basic Authentication for authorizing with Twitter API will be turned off on Aug 16th. After that OAuth will be the only way to invoke the API.

Beginner's guide to OAuth provide an excellent explanation to OAuth. The typical analogy for OAuth is a "valet key" to the car which is a stripped down version of your regular key. These keys are meant for valet drivers who don't need to open trunk or glove compartment and don't need to drive the car for longer distance. So even though they have access to the entire car but are restricted to the limited functionality.

OAuth is used to share your resources (photos, videos, bank accounts, etc) stored on one site with another site without having to share your username and password. The site storing the resources is "Service Provider", the site requesting the access is "Consumer", you are the "User", "Tokens" are "valet key" that provide required access to the resources.

This Tip Of The Day (TOTD) explains how Jersey, the Reference Implementation for JAX-RS, provides seamless support for OAuth by creating a simple desktop application that retrieves user timeline on Twitter using OAuth. This blog is going to combine the instructions outlined in Understanding the guts of Twitter's OAuth for client apps and Using Jersey client OAuth support with Smugmug to achieve that.

Lets get started!

  1. Create a Maven project as:
    mvn -DarchetypeVersion=1.0 -DgroupId=org.glassfish.samples -DarchetypeArtifactId=maven-archetype-quickstart -Dversion=1.0-SNAPSHOT -DarchetypeGroupId=org.apache.maven.archetypes -Dpackage=org.glassfish.samples.twitter -DartifactId=twitter
    
  2. Update the generated "pom.xml" with the following fragments:
    <repositories>
      <repository>
        <id>glassfish-repository</id>
        <name>Java.net Repository for Glassfish</name>
        <url>http://download.java.net/maven/2/</url>
      </repository>
    </repositories>
    <dependencies>
      <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>3.8.1</version>
        <scope>test</scope>
      </dependency>
      <dependency>
        <groupId>com.sun.jersey</groupId>
        <artifactId>jersey-client</artifactId>
        <version>1.1.3-SNAPSHOT</version>
      </dependency>
      <dependency>
        <groupId>com.sun.jersey</groupId>
        <artifactId>jersey-json</artifactId>
        <version>1.1.3-SNAPSHOT</version>
      </dependency>
      <dependency>
        <groupId>com.sun.jersey.oauth</groupId>
        <artifactId>oauth-signature</artifactId>
        <version>1.1.2-ea-SNAPSHOT</version>
      </dependency>
      <dependency>
        <groupId>com.sun.jersey.oauth</groupId>
        <artifactId>oauth-client</artifactId>
        <version>1.1.2-ea-SNAPSHOT</version>
       </dependency>
    </dependencies>
    <build>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-compiler-plugin</artifactId>
          <version>2.0.2</version>
          <configuration>
            <source>1.6</source>
            <target>1.6</target>
          </configuration>
        </plugin>
      </plugins>
     </build>
    

    The Jersey dependencies add the core Jersey libraries and OAuth functionality in Jersey.
  3. Register your app with Twitter - Register your application with Twitter by clicking on Register a new application >>. The complete list of registered applications can be seen at Applications using Twitter. Select "Client" as the app type, select "Yes, use Twitter for login" and leave the "Callback URL" empty. The registration gives you "consumer key" and "consumer secret". These are used to obtain temporary credentials (or request tokens) from Twitter.
  4. Obtain Twitter OAuth credentials - Each OAuth request is an HTTP request with "Authorization" header specifying the information by OAuth service provider. Jersey provides a OAuthClientFilter to add this header to the outbound client request. Twitter API Wiki explains the authentication as multiple step process for desktop applications. Each step involves sending some parameters to twitter and getting a result back and the intent of each method/request is clearly explained in Understanding the guts of Twitter's OAuth for client apps. In our case, each request is created by using Jersey Client API and attaching OAuthClientFilter and is explained next.
    1. Request temporary credentials, a.k.a request token, from Twitter using oauth/request_token.
      1. In "App.java", create an instance of Jersey client in the constructor and attach a LoggingFilter to dump inbound/outbound messages as:
        public App() {
            // Create a Jersey client
            client = Client.create();
        
            client.addFilter(new LoggingFilter());
        }
        
      2. Request temporary credentials by adding the following method:
        public void getRequestToken() {
            client.removeAllFilters();
        
            // Create a resource to be used to make Twitter API calls
            WebResource resource = client.resource(REQUEST_TOKEN_URL);
        
            // Set the OAuth parameters
            OAuthSecrets secrets = new OAuthSecrets().consumerSecret(CONSUMER_SECRET);
            OAuthParameters params = new OAuthParameters().consumerKey(CONSUMER_KEY).
                    signatureMethod("HMAC-SHA1").version("1.0");
            // Create the OAuth client filter
            OAuthClientFilter oauthFilter =
                    new OAuthClientFilter(client.getProviders(), params, secrets);
        
            // Add the filter to the resource
            resource.addFilter(oauthFilter);
        
            // make the request and print out the result
            System.out.println(resource.get(String.class));
        }
        
        
        Note, "OAuthClientFilter" is used to populate the "Authorization" header instead of handcrafting it. The REQUEST_TOKEN_URL is "http://twitter.com/oauth/request_token", CONSUMER_SECRET and CONSUMER_KEY are the values obtained from registering your application.
      3. Edit "AppTest.java" and change "testApp" method such that it looks like:
        public void testApp() {
            App app = new App();
            app.getRequestToken();
        }
        
      4. Obtain the temporary credentials by running this application as:
        mvn test
        

        and see an output as:
        oauth_token=REQUEST_OAUTH_TOKEN&oauth_token_secret=REQUEST_OAUTH_TOKEN_SECRET&oauth_callback_confirmed=true
        

        REQUEST_OAUTH_TOKEN, a temporary token, is used to authorize on twitter.com.
    2. Authorize the user and obtain PIN
      1. Go to "https://twitter.com/oauth/authorize?oauth_token=REQUEST_OAUTH_TOKEN" in a browser window.
      2. If not already logged in, enter your twitter credentials and click "Allow".
      3. Copy the PIN.
    3. Request permanent credentials, a.k.a access token, from Twitter using oauth/access_token.
      1. Request permanent credentials by adding the following method in "App.java"
        public void getAccessToken() {
                client.removeAllFilters();
        
                // Set the OAuth parameters
                OAuthSecrets secrets = new OAuthSecrets().consumerSecret(CONSUMER_SECRET);
                OAuthParameters params = new OAuthParameters().consumerKey(CONSUMER_KEY).
                        signatureMethod("HMAC-SHA1").
                        version("1.0").
                        token(REQUEST_OAUTH_TOKEN).
                        verifier(PIN);
                // Create the OAuth client filter
                OAuthClientFilter oauthFilter =
                        new OAuthClientFilter(client.getProviders(), params, secrets);
        
                // Create a resource to be used to make Twitter API calls
                WebResource resource = client.resource(ACCESS_TOKEN_URL);
        
                // Add the filter to the resource
                resource.addFilter(oauthFilter);
        
                // make the request and print out the result
                System.out.println(resource.get(String.class));
            }
        
        REQUEST_OAUTH_TOKEN is the temporary token obtained earlier, ACCESS_TOKEN_URL is "https://twitter.com/oauth/access_token".

        Notice, REQUEST_OAUTH_TOKEN and PIN are now added to the OAuthClientFilter.
      2. Invoke this method by editing "AppTest.java" as:
        public void testApp() {
             App app = new App();
        //     app.getRequestToken();
             app.getAccessToken();
        }
        
      3. Obtain the permanent credentials by running this application as:
        mvn test
        

        and see an output as:
        oauth_token=ACCESS_OAUTH_TOKEN&oauth_token_secret=ACCESS_OAUTH_TOKEN_SECRET&user_id=USER_ID&screen_name=USER_NAME
        

        ACCESS_OAUTH_TOKEN is the authorized token that can be used for making any future requests, USER_ID and USER_NAME are identifiers for the user who signed in on twitter.com. 
  5. Get the last 20 status messages for the user from Twitter
    1. Add the following method in "App.java:
      public void getUserTimeline() {
          client.removeAllFilters();
      
          // Set the OAuth parameters
          OAuthSecrets secrets = new OAuthSecrets().consumerSecret(CONSUMER_SECRET);
          OAuthParameters params = new OAuthParameters().consumerKey(CONSUMER_KEY).
                  signatureMethod("HMAC-SHA1").
                  version("1.0").
                  token(ACCESS_OAUTH_TOKEN);
          // Create the OAuth client filter
          OAuthClientFilter oauthFilter =
                  new OAuthClientFilter(client.getProviders(), params, secrets);
      
          // Create a resource to be used to make Twitter API calls
          WebResource resource = client.resource(USER_TIMELINE_URL);
      
          // Add the filter to the resource
          resource.addFilter(oauthFilter);
      
         // Parse the JSON array
          JSONArray jsonArray = resource.get(JSONArray.class);
          List<String> statuses = new ArrayList<String>();
      
          try {
              for (int i = 0; i < jsonArray.length(); i++) {
                  JSONObject jsonObject = (JSONObject) jsonArray.get(i);
                  StringBuilder builder = new StringBuilder();
                  builder.append(jsonObject.getString("text")).
                          append(jsonObject.getString("created_at"));
                  statuses.add(builder.toString());
              }
          } catch (JSONException ex) {
              Logger.getLogger(App.class.getName()).log(Level.SEVERE, null, ex);
          }
      } 
      USER_TIMELINE_URL is "http://api.twitter.com/1/statuses/user_timeline.json". The "getTimelineElements" method can be updated to pick other elements from the return JSON object. The complete JSON schema for the response is described here.
    2. Edit "AppTest.java" as:
      public void testApp() {
          App app = new App();
      //    app.getRequestToken();
      //    app.getAccessToken();
          app.getUserTimeline();
      }
      
    3. Finally get the last 20 status updates by giving the command:

      mvn test
      


      and see the output similar to:
      Running org.glassfish.samples.twitter.AppTest
      [Developing OSGi-Enabled Java EE Applications- http://bit.ly/aOim34 (via 
      @JavaOneConf) #javaone10Wed Aug 04 23:53:13 +0000 2010, Google Wave goes
       bye bye (via @google:)Update on Google Wave http://bit.ly/bIoDWAWed Aug
       04 21:16:07 +0000 2010, @gdaniels Yeah, I expected #wave to bye bye as
       well, but this is fairly quick!Wed Aug 04 21:15:41 +0000 2010,
      

And that's it!

This Tip Of The Day explained how to use Jersey to retrieve last 20 status messages that a user posted on twitter. Here are some other future possible additions:

  • POST status update
  • Integrate Search API using OAuth (is it possible ?)
  • Integrate Streaming API (need more investigation)
  • Create a web-base client that automatically redirects the user from application to twitter.com and then back to the application.

Jersey and OAuth wiki provides more details about how to use OAuth with Jersey.

Technorati: totd jaxrs jersey restful webservices oauth twitter glassfish

Thursday Feb 18, 2010

TOTD #124: Using CDI + JPA with JAX-RS and JAX-WS

This is a follow up blog to TOTD #120 and TOTD #123. These two blogs together have created a simple Java EE 6 application and showed the following features so far:

  • No-interface view for EJB
  • EJBs packaged in a WAR file
  • Optional "faces-config.xml" for Java Server Faces
  • FacesServlet registered using Servlet 3.0 programmatic registration APIs
  • Java Server Faces navigation rules using convention-over-configuration
  • Optional "web.xml" for Servlets 3.0
  • Add database access using Java Persistence API 2.0
  • Show type-safe Criteria API from JPA 2.0
  • Use Context & Dependency Injection for JSF managed beans
  • Add Ajax effects from Java Server Faces 2.0
  • Add Bean Validation to the JSF managed bean

GlassFish v3 is the Java EE 6 Reference Implementation and comes bundled with a complete SOAP Web services stack (Metro/JAX-WS) and a RESTful stack (JAX-RS/Jersey). This blog will update the previously created Maven project with:

  • A SOAP Web service using JAX-WS
  • A RESTful Web service using JAX-RS
  • Use Context & Dependency Injection with JAX-WS and JAX-RS
  • Query the database using JPA 2 based upon criteria from the Web service invocation

Lets get started!

  1. Use the Maven project from TOTD #123 and update the directory structure as follows:
    src
    src/main
    src/main/java
    src/main/java/org
    src/main/java/org/glassfish
    src/main/java/org/glassfish/samples
    src/main/java/org/glassfish/samples/ActorResource.java
    src/main/java/org/glassfish/samples/RESTApplication.java
    src/main/java/org/glassfish/samples/SakilaBean.java
    src/main/java/org/glassfish/samples/SimpleBean.java
    src/main/java/org/glassfish/samples/SimpleEJB.java
    src/main/java/org/glassfish/samples/SimpleServlet.java
    src/main/java/org/glassfish/samples/SOAPService.java
    src/main/resources
    src/main/webapp
    src/main/webapp/index.jsp
    src/main/webapp/index.xhtml
    src/main/webapp/sakila.xhtml
    src/main/webapp/show.xhtml
    src/main/webapp/WEB-INF
    src/main/webapp/WEB-INF/beans.xml
    src/main/webapp/WEB-INF/web.xml
    

    The changes are:
    • "ActorResource.java" is added for the RESTful representation of Actor table.
    • "SOAPSevice.java" is added to invoke the SOAP-based Web service.
    • "SakilaBean.java" is updated to query the database for an Actor identified by "id".
  2. The updated files are explained below.
    • A new method is added to SakilaBean.java as shown below:
       public Actor findActorById(int id) {
          EntityManager em = emf.createEntityManager();
      
          CriteriaBuilder cb = emf.getCriteriaBuilder();
          CriteriaQuery<Actor> criteria = cb.createQuery(Actor.class);
      
          // FROM clause
          Root<Actor> actor = criteria.from(Actor.class);
      
          // SELECT clause
          criteria.multiselect(actor.<Short>get("actorId"),
                               actor.<String>get("firstName"),
                               actor.<String>get("lastName"));
      
          // WHERE clause
           criteria.where(cb.equal(actor.<Short>get("actorId"), id));
      
          Query q = em.createQuery(criteria);
          ((org.eclipse.persistence.jpa.JpaQuery)q).getDatabaseQuery().dontMaintainCache();
      
          return (Actor)q.getResultList().get(0);
      }
      

      This method queries the database for an actor by his id and uses the typesafe Criteria API to achieve the purpose. The FROM, SELECT, and WHERE clause are highlighted in the code. A cast to EclipseLink specific class is required because of the bug #303205.
    • SOAPService.java
      package org.glassfish.samples;
      
      import javax.inject.Inject;
      import javax.jws.WebService;
      import sakila.Actor;
      
      @WebService
      public class SOAPService {
          @Inject SakilaBean bean;
      
          public String sayHello(int id) {
              Actor a = bean.findActorById(id);
              return "Hello " + a.getFirstName();
          }
      }
      

      The key points in the code are:
      • Standard JAX-WS annotations from "javax.jws.\*" package are used to represent the Web service.
      • The Web service has only one method "sayHello" that concatenates the string "Hello" with the first name of "Actor" identified by "id".
      • No deployment descriptor modifications are required to publish this Web service.
      • "SakilaBean" is injected using @Inject annotation and used to query the database. This allows to encapsulate all the database details in one class and injected in a typesafe manner.
    • RESTApplication.java
      package org.glassfish.samples;
      
      import javax.ws.rs.ApplicationPath;
      import javax.ws.rs.core.Application;
      
      @ApplicationPath("/sakila")
      public class RESTApplication extends Application {
      }
      

      This is a marker class to inform Jersey of the root resource to be registered. By default, all classes with @Path and @Provider annotations are included. It also specifies the base path at which all resources are accessible.

      An alternative to this class is to specify the required information in "web.xml" as:
      <servlet>
           <servlet-name>Jersey Web Application</servlet-name>
           <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
       </servlet>
      
       <servlet-mapping>
           <servlet-name>Jersey Web Application</servlet-name>
           <url-pattern>/sakila/\*</url-pattern>
       </servlet-mapping>
      

      So only one of RESTApplication.java or changes in "web.xml" are required.
    • ActorResource.java
      package org.glassfish.samples;
      
      import javax.enterprise.context.RequestScoped;
      import javax.inject.Inject;
      import javax.ws.rs.GET;
      import javax.ws.rs.Path;
      import javax.ws.rs.Produces;
      import javax.ws.rs.PathParam;
      import sakila.Actor;
      
      @Path("/actor/{id}")
      @RequestScoped
      public class ActorResource {
          @Inject SakilaBean sakila;
      
          @GET
          @Produces("application/json")
          public Actor getActor(@PathParam("id") int id) {
              return sakila.findActorById(id);
          }
      }
      
      The key points in the code are:
      • Standard JAX-RS annotations from "javax.ws.rs" package are used to represent the RESTful resource.
      • "getActor" method is invoked when the resource is accessed using HTTP GET.
      • The resource is accessible at "/actor/{id}" URL where "{id}" is mapped to the "id" parameter of "getActor" method.
      • SakilaBean is injected in a typesafe manner using @Inject annotation. This bean is then used to query the database using the "id" parameter.
      • "getActor" method produces JSON representation, as defined by the "@Produces" annotation. This is easily achieved by updating our Persistence Unit (PU) created in TOTD #122 and adding "@javax.xml.bind.annotation.XmlRootElement" as the class level annotation on "sakila.Actor" class. Make sure to install the updated PU to your local Maven repository.

Package and deploy the application as:
mvn clean package
./bin/asadmin deploy --force=true ~/samples/javaee6/simplewebapp/target/simplewebapp-1.0-SNAPSHOT.war

Now the SOAP web service is accessible at "http://localhost:8080/simplwebapp-1.0-SNAPSHOT/SOAPServiceService" and looks like:


Notice, the URL in your case may be different if the Web service class name was different. The default URL is "http://<HOST>:<PORT>/<CONTEXT ROOT><WEB SERVICE CLASS NAME>Service".

This Web service can be easily tested by using the in-built tester accessible at "http://localhost:8080/simplwebapp-1.0-SNAPSHOT/SOAPServiceService?tester" and looks like:

The WSDL describing the Web service can be seen by clicking on the "WSDL File" link. The Web service method can be invoked by entering a value ("id" of the Actor) in the text box and clicking on "sayHello" button. Here is a sample run:

Clicking on "Submit" invokes the Web service which then uses the injected "SakilaBean" to query the database using the parameter specified. The first name from the response from the database is then extracted, concatenated with the string "Hello" and returned as Web service response.

The RESTful resource is accessible at "http://localhost:8080/simplwebapp-1.0-SNAPSHOT/sakila/actor/5" and looks like:

As in the SOAP-based Web service, the "5" in the URL is mapped to a parameter in the "ActorResource.java", the injected "SakilaBean" is then used to query the database and returns the JSON representation. Specifying a different number in the URL will show the RESTful JSON representation for that particular actor.

More Java EE 6 features will be covered in subsequent blogs. Are you interested in any particular ones ?

Technorati: jaxws metro webservices jaxrs rest jersey glassfish v3 cdi jsr299 weld

Monday Feb 01, 2010

Screencast #29: Web service using NetBeans 6.8 and GlassFish v3 (Accessing database in business method)

GlassFish v3 comes bundled with Metro - a secure, reliable, transactional, and .NET interoperable Web services stack. Metro is compliant with JAX-WS and provides additional quality of service attributes that can be easily enabled using NetBeans IDE.

This blog contains a screencast that shows how to create a simple Web service using NetBeans 6.8, implement the business logic by accessing a database table using Java Persistence API, and deploy on GlassFish v3.

Please post your questions to users@glassfish.dev.java.net.

Several other screencasts on GlassFish v3and related topics are available here.

Technorati: netbeans jax-ws metro webservice glassfish jpa database

Tuesday Jan 12, 2010

TOTD #117: Invoke a JAX-WS Web service from a Rails app deployed in GlassFish

A user on GlassFish Forum tried invoking a JAX-WS Web service from a Rails application and faced some issues. This Tip Of The Day (TTOD) will discuss the different approaches and shows their current status.

A Rails app can be deployed on GlassFish in 3 different ways:

  1. Directory Deployment in GlassFish v3 Server - TOTD #72 explains how to deploy a trivial Rails application (with just a scaffold) on GlassFish v3 server. Even though the blog uses a Rails application, any Rack-based application can be deployed on the server. This server is also the Reference Implementation for Java EE 6 and can also run Grails and Django applications.
  2. Directory Deployment using light-weight GlassFish Gem - GlassFish Gem is a light-weight version of the full-blown server and is stripped to run, just like the server, any Rack-based application such as Merb, Rails, and Sinatra. TOTD #70 shows how to deploy the same application using GlassFish Gem.
  3. WAR file in GlassFish v2.x or v3 - TOTD #73 explains how to deploy a Rails application as WAR file on GlassFish v2. The JNDI connection pooling part of the blog may be skipped to simplify the steps but the concepts are still valid. TOTD #44 shows how to do JNDI connection pooling for GlassFish v3. As GlassFish v2 has in-built support for session replication, TOTD #92 demonstrate how Rails application can leverage that functionality.

Now lets get to the issue reported by the user using these 3 deployment models.

First, lets deploy a simple Web service endpoint and generate a JAR file of the client-side artifacts:

  1. This blog will use a simple Web service as defined in screencast #ws7. The Web service endpoint looks like:
    package server;
    
    import javax.jws.WebService;
    
    /\*\*
     \* @author arungupta
     \*/
    @WebService()
    public class HelloService {
     public String sayHello(String name) {
     return "Hello " + name;
     }
    }
    

  2. Generate Web service client-side artifacts as:
    ~/samples/v3/rails/webservice/tmp >wsimport -keep http://localhost:8080/HelloWebService/HelloServiceService?wsdl
    parsing WSDL...
    
    
    generating code...
    
    
    compiling code...
    
  3. Create a Web service client jar file as:
    jar cvf wsclient.jar ./server
    

Now lets write a Rails application and invoke this Web service:

  1. Create a simple Rails application as:
    jruby -S rails webservice
    

    Optionally you may specify "-d mysql" to use MySQL database. Or better un-comment the following line:
    # config.frameworks -= [ :active_record, :active_resource, :action_mailer ]
    

    in "config/environment.rb" as no database interaction is required.
  2. Create a controller and view as:
    jruby script/generate controller home index
    
  3. Update the Controller in "app/controllers/home_controller.rb" as:
    include Java
    
    class HomeController < ApplicationController
     def index
     service = Java::server.HelloServiceService.new
     port = service.getHelloServicePort
    
     @result = port.sayHello("Duke")
     end
    
    end
    
  4. Change the View in "app/views/home/index.html.erb" as:
    <h1>Home#index</h1%gt;
    <p>Find me in app/views/home/index.html.erb</p>
    
    <%= @result %>
    

Now lets deploy this Web service using the 3 different deployment models mentioned above.

GlassFish v3 allows a directory-based deployment of Rails applications. This application needs to locate the Web service client classes. The "wsclient.jar" can be copied to the "lib" directory of Rails application ("webservice/lib" in our case), "domains/domain1/lib/ext" or "JRUBY_HOME/lib". The library can also be passed during deployment using "--libraries" switch. None of this approach seem to work correctly as explained in issue# 11408. So for now, invoking a JAX-WS Web service from a Rails application deployed directly on GlassFish v3 is not possible, at least until the bug is fixed.

In order to deploy the same application using GlassFish Gem, you can copy "wsclient.jar" to the "lib" directory of your Rails application. And also add the following line to "app/controllers/home_controller.rb":

require 'lib/wsclient.jar'

Alternatively you can copy it to "JRUBY_HOME/lib" directory if this Web service client is accessed my multiple applications. In this case there is no need to add any "require" statement to your Controller. Anyway, running the application as:

jruby -S glassfish

and accessing "http://localhost:3000/home/index" shows the following output:

And finally as explained in TOTD #73, bundle up your original Rails application as WAR and then deploy on GlassFish v3 as:

asadmin deploy webservice.war

Make sure to copy "wsclient.jar" to the "lib" directory of your Rails application and then Warbler will copy it to "WEB-INF/lib" of the generated WAR file. The output is shown as below:

So if you want to invoke a Metro/JAX-WS Web service from a Rails application, then run your Rails application using GlassFish Gem or deploying as a WAR file. It'll work on GlassFish v3 server when issue# 11408 is fixed.

Here are some additional links:

  • TOTD #104 also shows how popular Rails applications such as Redmine, Typo, and Substruct can be easily deployed on GlassFish.
  • Rails applications can be easily clustered using Apache + mod_proxy or  nginx.

A complete archive of all the TOTDs is available here.

Technorati: totd glassfish v3 jruby rails webservice jax-ws metro

Monday Aug 24, 2009

TOTD #98: Create a Metro JAX-WS Web service using GlassFish Tools Bundle for Eclipse


Now that you've installed GlassFish Tools Bundle for Eclipse 1.1, lets use this bundle to create a simple Metro/JAX-WS compliant Web service and deploy on GlassFish. These steps will work with either Eclipse 3.4.2 or 3.5 with WTP Java EE support.

  1. Lets create a simple "Dynamic Web Project" as shown below:


  2. Name the project "HelloMetro" and take all other defaults:



    Click on "Finish" to complete the project creation.
  3. Metro allows to create a Web service from a POJO class. So let's add a POJO to the project by right-clicking on the project and selecting "New", "Class" as shown below:

      

    Specify the package name as "server", class name as "HelloService" and click on "Finish".
  4. Add a simple method to the newly generated class as:

    public String sayHello(String name) {
          return "Hello " + name + "!!";
    }
  5. Expand the project, go to "HelloService.java" in "server" package, right-click, select "Web Services", "Create Web service".
  6. Click on "Web service runtime: Apache Axis" and select "Metro (JAX-WS) Runtime" as the Web service runtime as shown below:

  7. Move the slider on the left to top. This will enable testing of the deployed Web service. The completed configuration looks like:



    and click on "Next >".
  8. Select the checkbox "Copy Metro library jars to the project" to resolve the references correctly as shown below:



    and click on "Next >". This bundles the application and deploys to GlassFish and provides an option to test the deployed Web service as shown below:



    Clicking on the "Launch" button shows the following output in the browser:



    The WSDL is hosted at "http://localhost:8083/HelloMetro/HelloServiceService?wsdl".
  9. Click on "sayHello" method, click on "Add" and enter the value as "Duke" as shown below:



    Click on "Go" and the response is shown as:



    Clicking on "Source" in the response window shows the SOAP request/response messages as shown below:

  10. Alternatively, you can click on "Finish" to complete the dialog. Then click on "Run" menu item, "Launch the Web Services Explorer" to see a screen as:



    Enter the URL of the WSDL in "WSDL URL" box as "http://localhost:8083/HelloMetro/HelloServiceService?wsdl" and click on "Go". Now you are seeing the similar screen to test the Web service within the integrated browser as shown below:


A future blog will cover how to write a database-enabled application using the bundled Dali JPA Tools and MySQL pre-registered JDBC driver.

Please send your questions and comments to users@glassfishplugins.dev.java.net.
Please leave suggestions on other TOTD that you'd like to see. A complete archive of all the tips is available here.

Technorati: totd glassfish eclipse galileo webservices metro jax-ws

Wednesday Dec 03, 2008

JavaFX 1.0 launched - access services hosted on embedded GlassFish


Today Sun announces the availability of Java FX 1.0.

JavaFX 1.0 is a rich client platform for creating and delivering Rich Internet Applications across all screens (desktop, browser, and mobile) of your life. It consists of the following key components:


  • JavaFX SDK includes JavaFX script compiler and runtime tools, and a host of libraries to create RIAs for desktop, browser and mobile platforms, command-line tools & Ant tasks and other goodies.
  • NetBeans 6.5 support (as plugin or bundled with IDE) that allows to build, preview and debug JavaFX applications using NetBeans IDE. If you prefer CLI support then SDK can be downloaded.
  • Production Suite is a suite of tools and plugins for creative tools (such as Illustrator CS3+) that allows graphical assets to be exported to JavaFX applications.
The beauty of JavaFX is that its fully integrated with the Java Runtime and takes advantage of the performance and ubiquity of Sun's Java Runtime Environment that is installed on literally billions of devices worldwide. Hence, JavaFX applications will run on any desktop, browser, mobile device or any other connected device that runs the Java Runtime Environment.

This blog shows how to create a simple JavaFX application using NetBeans IDE. The application plays a movie, allows the viewer to cast a vote if they liked it, and see aggregate response from other viewers. The application is developed using NetBeans 6.5, JavaFX 1.0 plugin, and coded using JavaFX Script. The voting engine is deployed as a RESTful Web service using Jersey on GlassFish.

In terms of user experience, running the NetBeans project shows a window playing the movie. The first mouse hover over the window allows the viewer to click on "I love it" or "Not so great" and cast their vote as shown below:



Any subsequent mouse hover shows aggregated results from other viewers as shown below:



The results are not interesting if there is a single viewer of the movie. But for a production environment, this movie will be played by multiple users concurrently and the percentage numbers will be more meaningful. You can close the window and run the project again to vote again, as many times as you like :)

For those who like to see quick results, here is a 4-step guide to get started:
  1. In NetBeans 6.5 IDE, install JavaFX plugin as explained here and RESTful Web services plugin as explained here. Both the plugins may be installed in one step by selecting the required plugins together.
  2. Download NetBeans project for JavaFX client from here and add Jersey dependencies as explained in bullet #5 below. 
  3. Download Web service endpoint Maven project from here and deploy the endpoint as explained in bullet #4 below.
  4. Run the JavaFX application as explained here.
The remainder of this blog explains the details and shows how to construct the demo from scratch.

Lets first create the JavaFX application that plays the video movie.
  1. In NetBeans 6.5, install "JavaFX SDK" plugin.  In the "Tools" menu, "Plugins", search on "JavaFX", select "JavaFX SDK" and click on "Install".
  2. Create a new project of type "JavaFX", "JavaFX Script Application". Take the default values as shown below:



    and click on "Finish".
  3. The source code for this class can be downloaded from here or alternatively constructed as explained in the sub-bullets.
    1. In the newly created class, change the Stage (root area for all scene content) to:

      Stage {
         title: "GlassFish Media Player"
         width: 625
         height: 360
         resizable: false
         scene: myScene
      }
    2. Create a scene that contains the view of the media to be played and controls the display of the Vote or Result nodes:

      var myScene: Scene = Scene {
         content: MediaView {
                 fitWidth: 625
                 fitHeight: 360
                 mediaPlayer: bind myPlayer

                 onMouseEntered: function( e: MouseEvent ):Void {
                     println("mouse entered");
                     if (voted == false) {
                         insert Vote{} into myScene.content;
                     } else {
                         insert Result{} into myScene.content;
                     }
                 }

                 onMouseExited: function( e: MouseEvent ):Void {
                     delete myScene.content[1]
                 }

             }
      }
    3. Create a Media Player to use with the scene:

      var myPlayer: MediaPlayer = MediaPlayer{
          autoPlay: true
          media: bind myMedia
      };
    4. Create the media object to be used with the Media Player:

      var myMedia: Media = Media {
          source: "http://sun.edgeboss.net/download/sun/media/1460825906/1460825906_2957290001_DayEarth-Bluray.flv"
         };

      You can change the location of the movie here in the media player. For example, changing it to "http://mediacast.sun.com/users/ArunGupta/media/v3prelude-nb65-webapp.flv" will start playing the screencast #27.
    5. Create a Vote class that is a CustomNode and appears when a user's mouse enters the scene where the video is playing. The user can select whether he likes the clip or not and the vote is recorded making a Web service call using Jersey Client APIs:

      class Vote extends CustomNode {
         override function create():Node {
             return Group {
                 content: [
                     Rectangle {
                         fill: Color.GREEN
                         x: 185
                         y: 145
                         width: 243
                         height: 38
                         arcWidth: 20
                         arcHeight: 20
                     },

                     Text {
                         x: 195
                         y: 170
                         fill: Color.WHITE
                         font: Font {
                             size: 18
                         }
                         content: "I love it"
                     },

                     Rectangle{
                         x: 191
                         y: 148
                         smooth: false
                         width: 73
                         height: 32
                         fill: Color.TRANSPARENT

                         onMouseClicked: function( e: MouseEvent ):Void {
                             println("clicked I love it");
                             voted = true;
                             wsClient.voteLoveIt();
                             delete myScene.content[1]
                         }
                     },

                     Text{
                         x: 305
                         y: 170
                         fill: Color.WHITE
                         font: Font {
                             size: 18
                         }
                         content: "Not so great"
                         },

                     Rectangle {
                         x: 301
                         y: 148
                         smooth: false
                         width: 118
                         height: 32
                         fill: Color.TRANSPARENT
                        
                         onMouseClicked: function( e: MouseEvent ):Void {
                             voted = true;
                             println("clicked Not so great");
                             wsClient.voteNotSoGreat();
                             delete myScene.content[1]
                         }
                     }
                 ]
             }
         }
      };
    6. Create a Result class that is a CustomNode and simply reports on how many voters like this clip:

      class Result extends CustomNode {
         override function create():Node {
             var resultPercent = wsClient.showResults();
             var resultString = "{resultPercent} voters liked this clip";

             return Group {
                 content: [
                     Rectangle {
                         fill: Color.BLUE
                         x: 187
                         y: 145
                         width: 244
                         height: 38
                         arcWidth: 20
                         arcHeight: 20

                         onMouseClicked: function( e: MouseEvent ):Void {
                             delete myScene.content[1]
                         }
                     },

                     Text {
                         x: 199
                         y: 170
                         fill: Color.WHITE
                         font: Font {
                             size: 18
                         }
                         content: resultString
                     }
                 ]
             }
         }
      };
    7. Add two instance variables:

      var voted = false;
      var wsClient = new WebserviceClient;

      The first variable captures if the viewer has already voted and the second variable is an instance to the RESTful Web service client.
    8. Add the following import statements:

      import javafx.scene.\*;
      import javafx.scene.input.MouseEvent;
      import javafx.scene.media.Media;
      import javafx.scene.media.MediaPlayer;
      import javafx.scene.media.MediaView;
      import javafx.scene.paint.Color;
      import javafx.scene.shape.Rectangle;
      import javafx.scene.text.Font;
      import javafx.scene.text.Text;
      import javafx.stage.Stage;

      "Fix Imports" should be able to fix them and bug #154307 is already filed for that.
  4. Create a new class that is used to capture the Vote as:

    @javax.xml.bind.annotation.XmlRootElement
    public class VoteBean {
        public static enum VOTE { LOVE_IT, NOT_SO_GREAT };
       
        public VOTE vote;

        public VoteBean() { vote = VOTE.LOVE_IT; }
        public VoteBean(VOTE vote) {
            this.vote = vote;
        }
    }

    This is a simple Javabean with a standard JAXB annotation. This ensures that XML is used as the data format for transfering results between client and endpoint. The source code for this class is available here.
  5. Add Jersey libraries to the project by right-clicking on Project, select Libraries, click on "Add Library...", select "JAX-RS 1.0" and "Jersey 1.0 (JAX-RS RI)", and click on "Add Library".



    If these libraries are not available then install the "RESTful Web Services" plugin from the Plugin Center.
  6. And finally add the class that invokes the RESTful Webservice endpoint:

    public class WebserviceClient {

        private static com.sun.jersey.api.client.WebResource createWebResource() {
            return com.sun.jersey.api.client.Client.create().
                    resource("http://localhost:8080/movie-feedback-webapp/webresources/myresource");
        }

        public static void voteLoveIt() {
            createWebResource().type("application/json").
                    post(new VoteBean(VoteBean.VOTE.LOVE_IT));
        }

        public static void voteNotSoGreat() {
            createWebResource().type("application/json").
                    post(new VoteBean(VoteBean.VOTE.NOT_SO_GREAT));
        }

        public static String showResults() {
            return createWebResource().get(String.class);
        }
    }

    The Webservice endpoint will be hosted at "http://localhost:8080/movie-feedback-webapp/webresources/myresource". A WebResource is created from the Client. The POST methods are used to cast the user vote and GET method is used to retrieve the aggregated results. The source code for this class is available here.
Now lets create the RESTful endpoint using Jersey and deploy on GlassFish.
  1. Create and deploy a RESTful Web service endpoint
    1. Create a template RESTful Web service endpoint as described in TOTD #56. Lets use the artifactId as "movie-feedback-webapp".
    2. Create the bean "VoteBean" in "org.glassfish.samples" package. This is the exactly same bean used earlier by the client:

      @javax.xml.bind.annotation.XmlRootElement
      public class VoteBean {
          public static enum VOTE { LOVE_IT, NOT_SO_GREAT };
          public VOTE vote;

          public VoteBean() { vote = VOTE.LOVE_IT; }
          public VoteBean(VOTE vote) {
              this.vote = vote;
          }
      }
    3. Update the generated resource
      1. Add @com.sun.jersey.spi.resource.Singleton as class annotation so that only one instance of the resource is created for the entire web application. This allows to save state (preferences from other users) in the RESTful resource.
      2. Add two instance variables:

            int loveIt;
            int noSoGreat;
      3. Add a method that will process HTTP POST requests as:

            @POST
            public void postOneVote(VoteBean bean) {
                if (bean.vote == VoteBean.VOTE.LOVE_IT) {
                    loveIt++;
                } else {
                    noSoGreat++;
                }
                System.out.println("In POST: " + bean.vote);
            }

        This method stores the vote in the resource. The handling of POST request messages by Jersey is explained in TOTD #58.
      4. Add a method that will process HTTP GET requests as:

            @GET
            @Produces("text/plain")
            public String getOpinion() {
                if (loveIt == 0 && noSoGreat == 0)
                    return "No votes cast yet!";
                return (loveIt \* 100) / (loveIt + noSoGreat) + "%";
            }

        This method calculates the percentage of viewers who liked the movie.
    4. Deploy the endpoint using "mvn glassfish:run" in "movie-feedback-webapp" directory.
Now run the JavaFX application by right-clicking on the project and selecting "Run Project" and start voting! The percentage results will vary if the movie is voted upon more than once.

This blog showed:
  • How to install JavaFX capabilities to an existing NetBeans 6.5 installation
  • How to create a simple JavaFX application that plays media files
  • Integrate it with existing Java libraries (Jersey client libraries in this case)
  • Invoke services hosted on GlassFish
The steps followed in this blog allows for rapid development/debugging of JavaFX application accessing resources using embeddable GlassFish but are not ideal for production deployments. A future blog will show how this JavaFX application can be deployed as a Java Web Start application and scaled for mulitple users.

The javafx.com/samples has loads of samples and javafx.com/tutorials shows how to build your own applications. The JavaFX Community Wiki is a great place to collaborate.

Send your Jersey questions to users@jersey.dev.java.net, GlassFish questions to GlassFish Forum, and JavaFX questions to JavaFX Forums.

Technorati: glassfish v3 jersey webservices javafx netbeans

Sunday Nov 30, 2008

TOTD #58: Jersey and GlassFish - how to process POST requests ?


Lets extend the Jersey endpoint (TOTD# 56) and client (TOTD# 57) such that it can accept a POST request and then invoke it.
  1. Add a new method to "MyResource.java" from TOTD# 56 as:

        @POST
        @Consumes("application/json")
        @Produces("application/json")
        public Greeting postIt(Greeting greeting) {
            System.out.println("In POST: " + greeting.greeting);
            return greeting;
        }

    The first line indicates that the Java method will process HTTP POST requests. The second and third line shows that the method consumes and produces JSON data format.
  2. Add a new method to "AppTest.java" from TOTD# 57 as:

        public void testPost() {
            Greeting result = createResource().
                    type("application/json").
                    post(Greeting.class, new Greeting("yo!"));
            assertTrue(result.greeting.equals("yo!"));
        }

    The main difference from the "testApp()" method is specifying the MIME type of the generated outbound request as "application/json".
  3. Running the test as "mvn test" shows the following output:

    Running org.glassfish.samples.AppTest
    1 \* Out-bound request
    1 > GET http://localhost:8080/helloworld-webapp/webresources/myresource
    1 >
    1 < 200
    1 < X-Powered-By: Servlet/2.5
    1 < Transfer-Encoding: chunked
    1 < Content-Type: text/plain
    1 < Server: GlassFish/v3
    1 < Date: Tue, 25 Nov 2008 20:19:34 GMT
    1 <
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?><greeting><greeting>Hi there!</greeting></greeting>
    1 \* In-bound response
    1 \* Out-bound request
    1 > POST http://localhost:8080/helloworld-webapp/webresources/myresource
    1 > Content-Type: application/json
    1 >
    {"greeting":"yo!"}
    1 < 200
    1 < X-Powered-By: Servlet/2.5
    1 < Transfer-Encoding: chunked
    1 < Content-Type: application/json
    1 < Server: GlassFish/v3
    1 < Date: Tue, 25 Nov 2008 20:19:34 GMT
    1 <
    {"greeting":"yo!"}
    1 \* In-bound response
    Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.191 sec

    The output shows request/response messages when both the tests are run together. Here are some highlights:
    1. "GET" and "POST" methods are clearly highlighted.
    2. The two "Content-Type" headers with value "text/plain" and "application/json" are output from two tests. The output from POST method has two Content-Type headers, one for outbound request and another one for inbound response.
    3. The body content of POST method is using JSON format.
Jersey and GlassFish provides a complete server-side and client-side API and framework for deploying and invoking RESTful Web service endpoints.

How are you using Jersey ?

Send all your questions to users@jersey.dev.java.net.

Please leave suggestions on other TOTD (Tip Of The Day) that you'd like to see. An archive of all the tips is available here.

Technorati: totd glassfish v3 embeddable jersey jsr311 rest json webservices

Tuesday Nov 25, 2008

TOTD #57: Jersey Client API - simple and easy to use

TOTD #56 explains how to create a RESTful Web service endpoint using Jersey and publish the resource using JSON representation. The blog entry showed how the endpoint can be accessed from a Web browser. This Tip Of The Day explains how to use Jersey Client APIs to invoke the published endpoint.

Lets get started!
  1. Create a new directory "./src/test/java/org/glassfish/samples"
  2. Add a test
    1. Add a template test file "AppTest.java" as shown below:

      package org.glassfish.samples;

      import junit.framework.Test;
      import junit.framework.TestCase;
      import junit.framework.TestSuite;

      /\*\*
       \* Unit test for simple App.
       \*/
      public class AppTest
          extends TestCase
      {
          /\*\*
           \* Create the test case
           \*
           \* @param testName name of the test case
           \*/
          public AppTest( String testName )
          {
              super( testName );
          }

          /\*\*
           \* @return the suite of tests being tested
           \*/
          public static Test suite()
          {
              return new TestSuite( AppTest.class );
          }

          /\*\*
           \* Rigourous Test :-)
           \*/
          public void testApp()
          {
              assertTrue(true);
          }
      }
    2. Add a new method "createResource()" as:

          private WebResource createResource() {
              Client client = Client.create();
              WebResource resource = client.resource("http://localhost:8080/helloworld-webapp/webresources/myresource");
              return resource;
          }

      This code creates a default instance of Jersey Client and creates a Web resource from that client for the URI passed as an argument.
    3. Change the implementation of "testApp()" method as:

              Greeting result = createResource().get(Greeting.class);
              assertTrue(result.greeting.equals("Hi there!"));

      This invokes the GET method on the resource by passing specific type and compares the returned and expected value.
    4. Add the following "imports":

      import com.sun.jersey.api.client.Client;
      import com.sun.jersey.api.client.WebResource;
    5. Copy "Greeting.java" from TOTD #56 to "./src/test/java/org/glassfish/samples" directory.
  3. Run the test
    1. Deploy the endpoint as "mvn glassfish:run".
    2. Run the test as "mvn test". The following output is shown:

      ~/samples/jersey/helloworld-webapp >mvn test
      [INFO] Scanning for projects...
      [INFO] ------------------------------------------------------------------------
      [INFO] Building helloworld-webapp Jersey Webapp
      [INFO]    task-segment: [test]
      [INFO] ------------------------------------------------------------------------
      [INFO] [resources:resources]
      [INFO] Using default encoding to copy filtered resources.
      [INFO] [compiler:compile]
      [INFO] Nothing to compile - all classes are up to date
      [INFO] [resources:testResources]
      [INFO] Using default encoding to copy filtered resources.
      [INFO] [compiler:testCompile]
      [INFO] Compiling 1 source file to /Users/arungupta/samples/jersey/helloworld-webapp/target/test-classes
      [INFO] [surefire:test]
      [INFO] Surefire report directory: /Users/arungupta/samples/jersey/helloworld-webapp/target/surefire-reports

      -------------------------------------------------------
       T E S T S
      -------------------------------------------------------
      Running org.glassfish.samples.AppTest
      Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.587 sec

      Results :

      Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESSFUL
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 4 seconds
      [INFO] Finished at: Mon Nov 24 16:50:17 PST 2008
      [INFO] Final Memory: 18M/43M
      [INFO] ------------------------------------------------------------------------
  4. View request and response messages
    1. Change the implementation of "createResource()" method as (changes highlighted in bold):

              Client client = Client.create();
              WebResource resource = client.resource("http://localhost:8080/helloworld-webapp/webresources/myresource");
              resource.addFilter(new LoggingFilter());
              return resource;
    2. Running the tests as "mvn test" now shows the output, with request and response messages, as shown below:

      Running org.glassfish.samples.AppTest
      1 \* Out-bound request
      1 > GET http://localhost:8080/helloworld-webapp/webresources/myresource
      1 >
      1 < 200
      1 < X-Powered-By: Servlet/2.5
      1 < Transfer-Encoding: chunked
      1 < Content-Type: application/json
      1 < Server: GlassFish/v3
      1 < Date: Tue, 25 Nov 2008 07:07:51 GMT
      1 <
      {"greeting":"Hi there!"}
      1 \* In-bound response
      Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.074 sec
Really easy!

Even though the APIs are used to invoke a RESTful endpoint deployed using Jersey but are very generic and can be used to invoke any RESTful endpoint. Paul's blog explain in detail on the usage. You can also see how these APIs can be used to consume a service hosted using Apache Abdera.

com.sun.jersey.api.client, com.sun.jersey.api.client.config, and com.sun.jersey.api.client.filter packages documents all the classes that provide support for client-side communication with HTTP-based RESTful Web services.

Technorati: totd glassfish v3 embeddable jersey jsr311 rest json webservices

Monday Nov 24, 2008

TOTD #56: Simple RESTful Web service using Jersey and Embeddable GlassFish - Text and JSON output


Jersey is the open source, production quality, JAX-RS (JSR 311) Reference Implementation for building RESTful Web services in the GlassFish community. It also provides an API that allows developers to extend Jersey to suite their requirements.

This Tip Of The Day (TOTD) shows how to create a simple RESTful Web service using Jersey and run it using embeddable GlassFish (glassfish:run). Maven is used to create and run the application. It also shows how the output format can be easily coverted from Text to JSON.

Lets get started!
  1. Create a simple web app using Maven as:

    ~/samples/jersey >mvn archetype:generate -DarchetypeCatalog=http://download.java.net/maven/2
    [INFO] Scanning for projects...
    [INFO] Searching repository for plugin with prefix: 'archetype'.
    [INFO] ------------------------------------------------------------------------
    [INFO] Building Maven Default Project
    [INFO]    task-segment: [archetype:generate] (aggregator-style)
    [INFO] ------------------------------------------------------------------------
    [INFO] Preparing archetype:generate
    [INFO] No goals needed for project - skipping
    [INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
    [INFO] Setting property: velocimacro.messages.on => 'false'.
    [INFO] Setting property: resource.loader => 'classpath'.
    [INFO] Setting property: resource.manager.logwhenfound => 'false'.
    [INFO] [archetype:generate]
    [INFO] Generating project in Interactive mode
    [INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
    Choose archetype:
    1: remote -> jersey-quickstart-grizzly (Archetype for creating a RESTful web application with Jersey and Grizzly)
    2: remote -> jersey-quickstart-webapp (Archetype for creating a Jersey based RESTful web application WAR packaging)
    Choose a number:  (1/2): 2
    [INFO] snapshot com.sun.jersey.archetypes:jersey-quickstart-webapp:1.0.1-SNAPSHOT: checking for updates from jersey-quickstart-webapp-repo
    Define value for groupId: : org.glassfish.samples
    Define value for artifactId: : helloworld-webapp
    Define value for version:  1.0-SNAPSHOT: :
    Define value for package: : org.glassfish.samples
    Confirm properties configuration:
    groupId: org.glassfish.samples
    artifactId: helloworld-webapp
    version: 1.0-SNAPSHOT
    package: org.glassfish.samples
     Y: :
    [INFO] ----------------------------------------------------------------------------
    [INFO] Using following parameters for creating OldArchetype: jersey-quickstart-webapp:1.0.1-SNAPSHOT
    [INFO] ----------------------------------------------------------------------------
    [INFO] Parameter: groupId, Value: org.glassfish.samples
    [INFO] Parameter: packageName, Value: org.glassfish.samples
    [INFO] Parameter: package, Value: org.glassfish.samples
    [INFO] Parameter: artifactId, Value: helloworld-webapp
    [INFO] Parameter: basedir, Value: /Users/arungupta/samples/jersey
    [INFO] Parameter: version, Value: 1.0-SNAPSHOT
    [INFO] \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* End of debug info from resources from generated POM \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
    [INFO] OldArchetype created in dir: /Users/arungupta/samples/jersey/helloworld-webapp
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESSFUL
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 21 seconds
    [INFO] Finished at: Mon Nov 24 14:09:27 PST 2008
    [INFO] Final Memory: 12M/30M
    [INFO] ------------------------------------------------------------------------
  2. Edit the generated "pom.xml" to add dependencies on GlassFish plugin
    1. Add the following plugin in the "pom.xml" under <build>/<plugins>:

                  <plugin>
                      <groupId>org.glassfish</groupId>
                      <artifactId>maven-glassfish-plugin</artifactId>
                  </plugin>
    2. Add the following plugin repositories:

          <pluginRepositories>
              <pluginRepository>
                  <id>maven2-repository.dev.java.net</id>
                  <name>Java.net Repository for Maven</name>
                  <url>http://download.java.net/maven/2/</url>
                  <layout>default</layout>
              </pluginRepository>
              <pluginRepository>
                  <id>maven-repository.dev.java.net</id>
                  <name>Java.net Maven 1 Repository (legacy)</name>
                  <url>http://download.java.net/maven/1</url>
                  <layout>legacy</layout>
              </pluginRepository>
          </pluginRepositories>
    3. Optionally, if the generated dependencies in "pom.xml" as shown below:

              <dependency>
                  <groupId>org.glassfish.distributions</groupId>
                  <artifactId>web-all</artifactId>
                  <version>10.0-build-20080430</version>
                  <scope>test</scope>
              </dependency>
              <dependency>
                  <groupId>org.glassfish.embedded</groupId>
                  <artifactId>gf-embedded-api</artifactId>
                  <version>1.0-alpha-4</version>
                  <scope>test</scope>
              </dependency>

      are changed to:

              <dependency>
                  <groupId>org.glassfish.distributions</groupId>
                  <artifactId>web-all</artifactId>
                  <version>10.0-SNAPSHOT</version>
                  <scope>test</scope>
              </dependency>
              <dependency>
                 <groupId>org.glassfish.embedded</groupId>
                 <artifactId>glassfish-embedded-all</artifactId>
                 <version>3.0-Prelude-SNAPSHOT</version>
              </dependency>

      then the latest version of Embedded GlassFish APIs are used.
    4. Also optionally, if you want to run against Jersey 1.0 bits then change the following property from "1.0.1-SNAPSHOT" to "1.0".

          <properties>
              <jersey-version>1.0</jersey-version>
          </properties>
  3. Run the application
    1. The generated source code is:

      package org.glassfish.samples;

      import javax.ws.rs.GET;
      import javax.ws.rs.Path;
      import javax.ws.rs.Produces;

      // The Java class will be hosted at the URI path "/helloworld"
      @Path("/myresource")
      public class MyResource {
         
          // The Java method will process HTTP GET requests
          @GET
          // The Java method will produce content identified by the MIME Media
          // type "text/plain"
          @Produces("text/plain")
          public String getIt() {
              return "Hi there!";
          }
      }

      Invoking "mvn glassfish:run" starts the embedded GlassFish and shows the following output:

      ~/samples/jersey/helloworld-webapp >mvn glassfish:run
      [INFO] Scanning for projects...
      [INFO] Searching repository for plugin with prefix: 'glassfish'.
      [INFO] ------------------------------------------------------------------------
      [INFO] Building helloworld-webapp Jersey Webapp
      [INFO]    task-segment: [glassfish:run]
      [INFO] ------------------------------------------------------------------------
      [INFO] Preparing glassfish:run
      [INFO] [resources:resources]
      [INFO] Using default encoding to copy filtered resources.
      [INFO] [compiler:compile]
      [INFO] Compiling 1 source file to /Users/arungupta/samples/jersey/helloworld-webapp/target/classes
      [INFO] [glassfish:run]
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: HK2 initialized in 229 ms
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.naming.impl.ServicesHookup@2470b02c Init done in 237 ms
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.v3.server.Globals@13b3d787 Init done in 239 ms
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.v3.server.SystemTasks@61bedd7d Init done in 244 ms
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.v3.services.impl.HouseKeeper@2b9f7952 Init done in 245 ms
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.v3.services.impl.CmdLineParamProcessor@5249d560 Init done in 248 ms
      JMXMP connector server URL = service:jmx:jmxmp://localhost:8888
      Nov 24, 2008 2:36:05 PM com.sun.enterprise.v3.services.impl.GrizzlyProxy start
      INFO: Listening on port 8080
      Nov 24, 2008 2:36:06 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: com.sun.enterprise.v3.services.impl.GrizzlyService@1baa56a2 startup done in 551 ms
      Nov 24, 2008 2:36:06 PM com.sun.enterprise.v3.services.impl.ApplicationLoaderService postConstruct
      INFO: loader service postConstruct started at 1227566166208
      Nov 24, 2008 2:36:06 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: Application Loader startup done in 740 ms
      Nov 24, 2008 2:36:06 PM com.sun.enterprise.v3.server.AppServerStartup run
      INFO: Glassfish v3 started in 740 ms
      Nov 24, 2008 2:36:07 PM com.sun.enterprise.web.WebModuleContextConfig authenticatorConfig
      SEVERE: webModuleContextConfig.missingRealm
      Nov 24, 2008 2:36:07 PM com.sun.jersey.api.core.PackagesResourceConfig init
      INFO: Scanning for root resource and provider classes in the packages:
        org.glassfish.samples
      Nov 24, 2008 2:36:07 PM com.sun.jersey.api.core.PackagesResourceConfig init
      INFO: Root resource classes found:
        class org.glassfish.samples.MyResource
      Nov 24, 2008 2:36:07 PM com.sun.jersey.api.core.PackagesResourceConfig init
      INFO: Provider classes found:
      Hit ENTER for redeploy

      Notice how GlassFish v3 starts up in sub-second (740 ms in this case).
    2. "http://localhost:8080/helloworld-webapp" shows the following output:

    3. Clicking on "Jersey resource" redirects to "http://localhost:8080/helloworld-webapp/webresources/myresource" and shows the following output:

  4. Change the output representation to produce JSON representation
    1. Add a new JAXB bean:

      package org.glassfish.samples;

      import javax.xml.bind.annotation.XmlRootElement;

      /\*\*
       \* @author arungupta
       \*/
      @XmlRootElement
      public class Greeting {
          public String greeting;

          public Greeting() { }
          public Greeting(String greeting) {
              this.greeting = greeting;
          }
      }
    2. Change the method implementation in MyResource as:

      //    @Produces("text/plain")
          @Produces("application/json")
          public Greeting getIt() {
              return new Greeting("Hi there!");
          }
    3. And now "http://localhost:8080/helloworld-webapp/webresources/myresource" shows the following output:



      Notice the output is now in JSON format.
  5. Optionally a WAR file can be created using the command:

    mvn clean package

    and the WAR file is generated in "target/helloworld-webapp.war". If Jersey is installed using GlassFish v3 Update Center then you can use "maven-assembly-plugin" to customize packaging of WAR and drastically reduce the size.
The JSON representation can be configured in multiple ways as explained in Configuring JSON for RESTful Web Services in Jersey 1.0. This has certainly come a long way from TOTD #8 and is much more effecient now.

The Jersey Wiki documents an extensive set of resources to get started.

Send all your questions to users@jersey.dev.java.net.

Please leave suggestions on other TOTD (Tip Of The Day) that you'd like to see. An archive of all the tips is available here.

Technorati: totd glassfish v3 embeddable jersey jsr311 rest json webservices
About

profile image
Arun Gupta is a technology enthusiast, a passionate runner, author, and a community guy who works for Oracle Corp.


Java EE 7 Samples

Stay Connected

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today