Introduction

The REST software architecture is based on transferring representation of resources. RESTful web services offer some advantages: They are simple, lightweight, and fast. A RESTful web service exposes a set of resources identified by URIs. Resources respond to the HTTP methods GET, POST, PUT, and DELETE. Resources may be accessed in various formats, such as HTML, plain text, XML, PDF, JPEG, or JSON. The Java API for RESTful web services (JAX-RS) is defined in JSR 311. Jersey is a reference implementation for JAX-RS that simplifies development of RESTful web services in Java.

In this article, use the Apache HttpClient library to create a JAX-RS client for Android—the popular smartphone platform. You can download the sample code used in this article.

Back to top

Setting up the environment

Before you can create a client for a JAX-RS web service, you need to set up the environment. See Resources for links.

1. Install Eclipse.
2. Install the Android Development Tools (ADT) plug-in for Eclipse, which provides a set of extensions to develop Android applications in Eclipse.
3. Install the SDK Platform for Android 2.2.The Android SDK provides tools for developing Android applications.
4. Create an Android Virtual Device (AVD), which is an emulator for Android, in Eclipse.
5. Download the Jersey archive, jersey-archive-1.4.zip, containing the Jersey JARs and core dependencies. Download the Jersey bundle JAR jersey-bundle-1.4.jar.

   Jersey is built using JDK 6.0, so you also need to install JDK 6.0.

6. Install a web server such as Tomcat, or an application server such as WebSphere®, or WebLogic server. Add the Jersey JAR files in Listing 1 to the runtime CLASSPATH of the application/web server.
   
   Listing 1. Jersey JAR Files
   

   C:\Jersey\jersey-bundle-1.4.jar;C:\Jersey\jersey-archive-1.4\lib\asm-3.1.jar; C:\Jersey\jersey-archive-1.4\lib\jsr311-api-1.1.1.jar

   
   

Back to top

Creating an Eclipse project

In this section, you will create a web project and add the JAX-RS facet to the project. Use the following steps to create an Eclipse project.

1. Select File > New, and in the New window, select Web > Dynamic Web Project. Click Next.
2. Specify a Project name (for example, AndroidJAX-RS) and click New Runtime, to configure a new target runtime for your WebSphere, Tomcat, or WebLogic server. Figure 1 shows the completed Dynamic Web Project window.
   
   Figure 1. Configure a new runtime
   
   
   
3. In the New Server Runtime Environment window, select a server, such as the Tomcat server, the WebSphere server, or the WebLogic server. Click Next, as in Figure 2.
   
   Figure 2. Select an application or web server
   
   
   
4. In the New IBM WebSphere v6.0 Runtime window, configure a JRE and the IBM WebSphere Installation Directory. Click Next in the Dynamic Web Project dialog. Select the default Java settings for Source folder and Output folder, and click Next.
5. Specify Context root as AndroidJAX-RS, select the default Content Directory, and click Finish.

   A Dynamic Web Project is created and gets added to Project Explorer. Right-click on the project node and select Properties.

6. Select Project Facets, then select the JAX-RS (REST Web Services) 1.1 project facet. Click Further configuration required, as in Figure 3.
   
   Figure 3. Configure the JAX-RS Project Facet
   
   
   
7. In the JAX-RS Capabilities window, specify a Servlet name (JAX-RS Servlet) and configure a JAX-RS Implementation library. Select Type as User Library and click Manage.
8. In the User Libraries window, click New. In the New User Library dialog, specify a User library name and click OK.

   A user library is added. Click Add JARs to add Jersey JARs to the user library. As in Figure 4, add the following Jersey JARs:

   • jersey-bundle-1.4.jar
   • C:\Jersey\jersey-archive-1.4\lib\asm-3.1.jar
   • C:\Jersey\jersey-archive-1.4\lib\jsr311-api-1.1.1.jar
   Click OK.
   
   Figure 4. Add Jersey JAR files
   
   
   
9. In the JAX-RS Capabilities window, specify the JAX-RS servlet class name as com.sun.jersey.spi.container.servlet.ServletContainer, as in Figure 5. Click OK.
   
   Figure 5. Specify the JAX-RS servlet class
   
   
   
10. In the Project Facets window, click Apply as in Figure 6, then click OK.
    
    Figure 6. Apply the JAX-RS Project Facet
    
    
    

The targeted runtimes are configured with the JAX-RS project facet. Click OK in the Properties dialog.

The JAX-RS User libraries get added to the project, and the JAX-RS servlet and servlet mapping get configured in web.xml. You need to add init-param elements for the com.sun.jersey.config.property.resourceConfigClass and the com.sun.jersey.config.property.packages init parameters. Listing 2 shows the web.xml.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/
xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/
ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <servlet>
    <description>JAX-RS Tools Generated - Do not modify</description>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
        <param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
    </init-param>
    <init-param>
        <param-name>com.sun.jersey.config.property.packages</param-name>
        <param-value>jaxrs</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>JAX-RS Servlet</servlet-name>
    <url-pattern>/jaxrs/*</url-pattern>
  </servlet-mapping>
</web-app>

Back to top

Creating and running a resource class

The next step is to create a RESTful web service resource using a root resource class. A root resource class is a POJO annotated with the @PATH annotation. It consists of at least one method annotated with the @PATH annotation or @GET, @PUT, @POST or @DELETE.

1. Select File > New > Other. In the New dialog, select Java > Class, and click Finish.
2. In the New Java Class window, as in Figure 7, specify:
   • A Source folder: AndroidJAX-RS/src
   • Package: jaxrs
   • Class name: HelloWorldResource

   Click Finish.

   
   
   Figure 7. Create the resource class
   
   
   

Annotate the Java class with the @PATH annotation. The code in Listing 3 specifies the URI path on which the Java class shall be hosted as /helloworld.

@Path("/helloworld")
public class HelloWorldResource {
...
}

To add resource methods to produce three different MIME types, add the getClichedMessage(), getXMLMessage(), and getHTMLMessage() methods. Annotate each method with the @GET annotation, which indicates that the methods shall process HTTP GET requests. Specify String as the return type for each of the methods. Annotate each method with the @PRODUCES annotation, and specify a different MIME type for each method.

Now you want to output a "Hello JAX-RS" method using the MIME types text/plain, text/xml, and text/html. The getXMLMessage method is annotated with the @Produces ("text/xml") annotation that produces an XML message. Uncomment only one of the methods annotated with the @GET method. If no other distinguishing path component is specified, the @GET request is routed to the method annotated with @GET. If multiple methods match a request URI, the JAX-RS selection algorithm is used to select the resource method. For example, you can specify multiple methods with the @GET annotation by using a different path id for the methods annotated with @GET. Listing 4 shows the root resource class.

package jaxrs;

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

// The Java class will be hosted at the URI path //"/helloworld"
@Path("/helloworld")
public class HelloWorldResource {

    // 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 getClichedMessage() {
    // Return some cliched textual content
     return "Hello Android";
     }

    // @GET
    // @Produces("text/xml")
    // public String getXMLMessage() {
    // return "<?xml version=\"1.0\"?>" + "<hello> Hello Android" + "</hello>";
    // }

//	@GET
    //@Produces("text/html")
    //public String getHTMLMessage() {
        //return "<html> " + "<title>" + "Hello Android" + "</title>"
            //	+ "<body><h1>" + "Hello Android" + "</body></h1>" + 
    "</html> ";
//	}

}

Run the resource class to produce different types of output. Comment out the methods that are not to be tested, and keep one method uncommented for each of the test runs. First, test the text/xml MIME type as output. Start the application/web server if not already started. Right-click on the resource class and select Run As > Run on Server, as in Figure 8.

On the server, the init parameter com.sun.jersey.config.property.resourceConfigClass is initiated as com.sun.jersey.api.core.PackagesResourceConfig and the init parameter com.sun.jersey.config.property.packages is initiated as jaxrs, as specified in web.xml. The root resource class jaxrs.HelloWorldResource is found. The Jersey application v1.4 is initiated, and the AndroidJAX-RS module deploys on the server.

Back to top

Creating an Android client project

In this section you'll create an Android project in which you create the JAX-RS client for Android.

1. In the Eclipse IDE, select File > New. In the New dialog, select Android > Android Project, then click Next.
2. Complete the fields in the New Android Project window, as in Figure 9.
   • Project name: AndroidJAXRSClient
   • Build Target: Android Platform 2.2 API 8
   • Properties: Application name AndroidJAXRSClient and Package name android.jaxrs
   • Select Create Activity, and specify Activity class AndroidJAXRSClient.

     An activity represents a user interaction, and the class extending the Activity class creates a window for a UI.

   • Minimum SDK Version: 8
   • Click Next
   
   
   Figure 9. Create the JAX-RS client class
   
   
   

The files in the Android project are:

• An activity class (AndroidJAXRSClient), which extends the Activity class
• The res/layout/main.xml file to specify the layout of the Android application
• The AndroidManifest.xml file, which contains application configuration information such as the package name, application components, processes, permissions, and minimum API level for the Android system

In the res/layout/main.xml file, specify the layout of the Android UI components. Create a LinearLayout with android:orientation="vertical". You'll create a UI in which the response from the web service is displayed as a text message. Add a TextView element with id jaxrs to display the JAX-WS web service response for a method call to one of the get methods. The method invocation gets a Hello message as a response in either XML, HTML, or text. Listing 5 shows the main.xml file:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
     android:orientation="vertical" android:layout_width="fill_parent"
     android:layout_height="fill_parent">
     <TextView android:id="@+id/jaxrs"
     android:layout_width="fill_parent" android:layout_height="wrap_content"
                />
</LinearLayout>

To access the JAX-RS web service from an Android device, enable the android.permission.INTERNET permission, in AndroidManifest.xml, which allows applications to open network sockets. Add the uses-permission element in Listing 6.

<uses-permission  android:name="android.permission.INTERNET"></uses-permission> 

Specify the minimum Android version with the uses-sdk element. The AndroidJAXRSClient activity, the intent-filter, and action are specified with the activity element and sub-elements. Listing 7 shows the AndroidManifest.xml file.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="android.jaxrs" android:versionCode="1" android:versionName="1.0">
     <uses-sdk android:minSdkVersion="8" />
     <application android:icon="@drawable/icon" android:label="@string/app_name">
       <activity android:name=".AndroidJAXRSClient" android:label="@string/app_name">
               <intent-filter>
                    <action android:name="android.intent.action.MAIN" />
                    <category android:name="android.intent.category.LAUNCHER" />
               </intent-filter>
       </activity>
     </application>
     <uses-sdk android:minSdkVersion="8" />
     <uses-permission android:name="android.permission.INTERNET"></uses-permission>
</manifest>

The Android SDK includes the Apache HttpClient library. Import the classes in Listing 8 into AndroidJAXRSClient.

org.apache.http.HttpEntity;
org.apache.http.HttpResponse;
org.apache.http.client.ClientProtocolException;
org.apache.http.client.HttpClient;
org.apache.http.client.methods.HttpGet;
org.apache.http.impl.client.DefaultHttpClient;

The AndroidJAXRSClient class extends the Activity class. The onCreate(Bundle savedInstanceState) method is invoked when the activity is first called. Define the user interface using the setContentView method and the layout resource, as in Listing 9.

setContentView(R.layout.main);

Listing 10 shows how to create an Android widget TextView object, using the findViewById method on the TextView element, with the id jaxrs that was defined in main.xml.

TextView jaxrs = (TextView) findViewById(R.id.jaxrs);

The default implementation of HttpClient is DefaultHttpClient. Create a DefaultHttpClient object, as Listing 11.

HttpClient httpclient = new DefaultHttpClient();

Create an HttpGet object to retrieve information from the server, as in Listing 12. Specify the URL to the resource hosted on the URI path /helloworld. Specify the IP address for host instead of localhost. The client runs on the Android device, and localhost for the Android device is not the host on which the JAX-RS web service runs (unless the JAX-RS web service is also hosted on the Android device, which is not the case in this example).

HttpGet request = new HttpGet("http://192.168.1.68:7001/AndroidJAX-RS/jaxrs/helloworld");

Specify acceptable media types using the Accept header. Set only one of the media types, which corresponds to the media type produced in the JAX-RS web service, in the Accept header. In the first run, set the Accept header to text/xml to output the text/xml response, as in Listing 13.

request.addHeader("Accept", "text/xml");
//request.addHeader("Accept", "text/html");
//request.addHeader("Accept", "text/plain");

Test the output of each of the response types (plain text, html, and XML). The accepted response type should match the MIME type produced in the resource class. The MIME type produced by the resource class should match an acceptable MIME type. If the produced MIME type and the acceptable MIME type do not match, a com.sun.jersey.api.client.UniformInterfaceException is generated. For example, set the acceptable MIME type to text/xml and the produced MIME type to application/xml. The UniformInterfaceException is generated. As in Listing 14, invoke the execute() method of the HttpClient, with the HttpGet method as an argument, to retrieve the HttpResponse object.

	
HttpResponse response = httpclient.execute(request);

From the HttpResponse obtain the HttpEntity using the getEntity method (Listing 15).

HttpEntity entity = response.getEntity();

Get the content as an InputStream from the HttpGet using the getContent() method (Listing 16).

InputStream instream = entity.getContent();

Create a StringBuilder for the message returned from the JAX-RS web service (Listing 17).

StringBuilder sb =  new StringBuilder();

Create a BufferedReader from the InputStream (Listing 18).

	
BufferedReader r = new BufferedReader(new InputStreamReader(instream));

Read each line from the BufferedReader and add it to the StringBuilder (Listing 19).

for (String line = r.readLine(); line != null; line = r.readLine()) {
             sb.append(line);	
}

Get the String message from the StringBuilder and close the InputStream (Listing 20).

String jaxrsmessage = sb.toString();		
instream.close();

Set the String message on the TextView UI component (Listing 21).

jaxrs.setText(jaxrsmessage);

Listing 22 shows the AndroidJAXRSClient class.

package android.jaxrs;
import android.app.Activity;
import android.os.Bundle;
import android.widget.TextView;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

public class AndroidJAXRSClient extends Activity {
     /** Called when the activity is first created. */
     @Override
     public void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.main);

          TextView jaxrs = (TextView) findViewById(R.id.jaxrs);
          try {
               HttpClient httpclient = new DefaultHttpClient();
               HttpGet request = new HttpGet(
                  "http://192.168.1.68:7001/AndroidJAX-RS/jaxrs/helloworld");

               //request.addHeader("Accept", "text/html");
          //	request.addHeader("Accept", "text/xml");
               request.addHeader("Accept", "text/plain");
               HttpResponse response = httpclient.execute(request);
               HttpEntity entity = response.getEntity();
               InputStream instream = entity.getContent();
               String jaxrsmessage = read(instream);
               jaxrs.setText(jaxrsmessage);
          } catch (ClientProtocolException e) {
               e.printStackTrace();
          } catch (IOException e) {
               e.printStackTrace();
          }

     }

     private static String read(InputStream instream) {
          StringBuilder sb = null;
          try {
               sb = new StringBuilder();
               BufferedReader r = new BufferedReader(new InputStreamReader(
                         instream));
          for (String line = r.readLine(); line != null; line = r.readLine()) {
               	sb.append(line);
			}

			instream.close();

          } catch (IOException e) {
          }
          return sb.toString();

     }

}

Figure 10 shows the directory structure of the Android client application. (View a larger version of Figure 10.)

Back to top

Running the Android client

Now you're ready to run the Android client to invoke the JAX-RS web service and output the XML message. Right-click on the AndroidJAXRSClient project and select Run As > Android Application, as in Figure 11.

The Android AVD starts and the JAX-RS client application installs on the Android device, as in Figure 12.

The AndroidJAXRSClient activity starts, and the XML message produced by the JAX-RS web service resource is output to the Android device, as in Figure 13.

Similarly, the HTML message is the output if the method that produces the text/html media type is uncommented in the resource class and the Accept header is set to receive the same media type. For example, in the resource class, uncomment the method in Listing 23.

@GET
@Produces("text/html")
public String getHTMLMessage() {
          return "<html> " + "<title>" + "Hello Android" + "</title>"
     + "<body><h1>" + "Hello Android" + "</body></h1>" + "</html> ";
     }

In the client class, uncomment the addHeader invocation in Listing 24.

request.addHeader("Accept", "text/html");

Rerun the AndroidJAXRSClient application to get the HTML response, as in Figure 14.

To get the text response, uncomment the method in the resource class in Listing 25.

@GET
@Produces("text/plain")
public String getClichedMessage() {
return "Hello Android";
 }

In the client class, uncomment the following Accept header media type setting in Listing 26.

request.addHeader("Accept", "text/plain");

Rerun the AndroidJAXRSClient application to get the text message output, as in Figure 15.

Back to top

Summary

In this article, you learned how to create a JAX-RS web service and invoke the web service from an Android client. You sent XML, HTML, and text output to the Android device.

Back to top

Download

Information about download methods

Resources

Learn

• Android: Explore the tools and documentation for creating Android applications.
  
  
• IBM JAX-RS: Developer's Guide: Read more about installing a JAX-RS application.
  
  
• JAX-RS Selection Algorithm: Learn more about the basics of JAX-RS.
  
  
• Develop a Spring client for Android to a JAX-RS web service (Deepak Vohra, developerWorks, Aug 2011): Learn to access a RESTful web service with the Spring Android REST client.
  
  
• Android content on developerWorks: Explore articles, demos, and tutorials about Android.
  
  
• More articles by this author (Deepak Vohra, developerWorks, April 2005-current): Read articles about Android, Ajax, PHP, XML, web services, Ruby on Rails, EJB, and other technologies.
  
  
• SOA and web services: Get articles, tutorials, standards, and other technical resources for web services and SOA on developerWorks.
  
  
• XML area on developerWorks: Find the resources you need to advance your skills in the XML arena, including DTDs, schemas, and XSLT. See the XML technical library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
  
  
• IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
  
  
• developerWorks technical events and webcasts: Stay current with technology in these sessions.
  
  
• developerWorks on Twitter: Join today to follow developerWorks tweets.
  
  
• developerWorks podcasts: Listen to interesting interviews and discussions for software developers.
  
  
• developerWorks on-demand demos: Watch demos ranging from product installation and setup for beginners to advanced functionality for experienced developers.
  
  

Get products and technologies

• Android SDK: Download the Android SDK and get started.
  
  
• Eclipse Downloads: Download Eclipse for Java EE.
  
  
• IBM product evaluation versions: Download or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• XML zone discussion forums: Participate in any of several XML-related discussions.
  
  
• The developerWorks community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Setting up the environment
• Creating an Eclipse project
• Creating and running a resource class
• Creating an Android client project
• Running the Android client
• Summary
• Download
• Resources
• About the author
• Comments

Dig deeper into XML on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers