原文：https://docs.jboss.org/author/display/AS7/Java+API+for+RESTful+Web+Services+(JAX-RS)

Content

Tutorial Overview

This chapter describes the Java API for RESTful web services (JAX-RS, defined in JSR331). RESTEasy is an portable implementation of this specification which can run in any Servlet container. Tight integration with JBoss Application Server is available for optimal user experience in that environment. While JAX-RS is only a server-side specification, RESTeasy has innovated to bring JAX-RS to the client through the RESTEasy JAX-RS Client Framework.

Detailed documentation on RESTEasy is available here.

The source for this tutorial is in github repository git://github.com/tdiesler/javaee-tutorial.git

OpenShift, is a portfolio of portable cloud services for deploying and managing applications in the cloud. This tutorial shows how to deploy a RESTful web service on the free OpenShift Express JavaEE cartridge that runsJBossAS 7.

An application running on Android shows how to leverage JBoss technology on mobile devices. Specifically, we show how use the RESTEasy client API from an Android device to integrate with a RESTful service running on a JBossAS 7 instance in the cloud.

The following topics are addressed

What are RESTful web services

Creating a RESTful server endpoint

Deploying a RESTful endpoint to a JBossAS instance in the cloud

RESTEasy client running on an Android mobile device

What are RESTful Web Services?

Coming Soon

This section is still under development.

RESTful web services are designed to expose APIs on the web. REST stands for Representational State Transfer. It aims to provide better performance, scalability, and flexibility than traditinoal web services, by allowing clients to access data and resources using predictable URLs. Many well-known public web services expose RESTful APIs.

The Java 6 Enterprise Edition specification for RESTful services is JAX-RS. It is covered by JSR-311 (http://jcp.org/jsr/detail/311.jsp). In the REST model, the server exposes APIs through specific URIs (typically URLs), and clients access those URIs to query or modify data. REST uses a stateless communication protocol. Typically, this is HTTP.

The following is a summary of RESTful design principles:

A URL is tied to a resource using the @Path annotation. Clients access the resource using the URL.

Create, Read, Update, and Delete (CRUD) operations are accessed via PUT, GET, POST, and DELETE requests in the HTTP protocol.

PUT creates a new resource.

DELETE deletes a resource.

GET retrieves the current state of a resource.

POST updates a resources's state.

Resources are decoupled from their representation, so that clients can request the data in a variety of different formats.

Stateful interactions require explicit state transfer, in the form of URL rewriting, cookies, and hidden form fields. State can also be embedded in response messages.

Creating a RESTful endpoint

A RESTful endpoint is deployed as JavaEE web archive (WAR). For this tutorial we use a simple library application to manage some books. There are two classes in this application:

Library

Book

The Book is a plain old Java object (POJO) with two attributes. This is a simple Java representation of a RESTful entity.

The Library is the RESTful Root Resource. Here we use a set of standard JAX-RS annotations to define

The root path to the library resource

The wire representation of the data (MIME type)

The Http methods and corresponding paths

The Library root resource uses these JAX-RS annotations:

AnnotationDescription

@Path

Identifies the URI path that a resource class or class method will serve requests for

@Consumes

Defines the media types that the methods of a resource class can accept

@Produces

Defines the media type(s) that the methods of a resource class can produce

@GET

Indicates that the annotated method responds to HTTP GET requests

@PUT

Indicates that the annotated method responds to HTTP PUT requests

@POST

Indicates that the annotated method responds to HTTP POST requests

@DELETE

Indicates that the annotated method responds to HTTP DELETE requests

For a full description of the available JAX-RS annotations, see the JAX-RS API documentation.

Package and build the endpoint

To package the endpoint we create a simple web archive and include a web.xml with the following content

Review

AS7-1674 Remove or explain why web.xml is needed for RESTful endpoints

The root context is defined in jboss-web.xml

The code for the JAX-RS part of this tutorial is available on https://github.com/tdiesler/javaee-tutorial/tree/master/jaxrs. In this step we clone the repository and build the endpoint using maven. There are a number of JAX-RS client tests that run against a local JBossAS 7 instance. Before we build the project, we set the JBOSS_HOME environment variable accordingly.

Arquillian, the test framework we use throughout this tutorial, can manage server startup/shutdown. It is however also possible to startup the server instance manually before you run the tests. The latter allows you to look at the console and see what log output the deployment phase and JAX-RS endpoint invocations produce.

Deploy the endpoint to OpenShift

First we need to create a free OpenShift Express account and select the JavaEE cartridge that runs JBossAS 7. Once we have received the confirmation email from OpenShift we can continue to create our subdomain and deploy the RESTful endpoint. A series of videos on the OpenShift Express page shows you how to do this. There is also an excellent quick start document that you have access to after login.

For this tutorial we assume you have done the above and that we can continue by creating the OpenShift application. This step sets up your JBossAS 7 instance in the cloud. Additionally a Git repository is configured that gives access to your deployed application.

Next, we can clone the remote Git repository to our local workspace

Because we want to deploy an already existing web application, which we'll build in the next step, we can safely remove the source artefacts from the repository.

Now we copy the JAX-RS endpoint webapp that we build above to the 'deployments' folder and commit the changes.

You can now use curl or your browser to see the JAX-RS endpoint in action. The following URL lists the books that are currently registered in the library.

Building the mobile client

The source associated with this tutorial contains a fully working mobile client application for the Android framework. If not done so already please follow steps described in Installing the SDK. In addition to the Android SDK, I recommend installing the m2eclipse and the EGit plugin to Eclipse.

First, go to File|Import... and choose "Existing Maven Projects" to import the tutorial sources

You project view should look like this

Then go to File|New|Android Project and fill out the first wizard page like this

Click Finish. Next, go to Project|Properties|Build Path|Libraries and add these external libraries to your android project.

You final project view should look like this

To run the application in the emulator, we need an Android Virtual Device (AVD). Go to Window|Android SDK and AVD Manager and create a new AVD like this

Now go to Run|Configuration to create a new run configuration for the client app.

Now you should be able to launch the application in the debugger. Right click on the javaee-tutorial-jaxrs-android project and select Debug As|Android Application. This should launch the emulator, which now goes though a series of boot screens until it eventually displays the Android home screen. This will take a minute or two if you do this for the first time.

When you unlock the home screen by dragging the little green lock to the right. You should see the the running JAX-RS client application.

Finally, you need to configure the host that the client app connects to. This would be the same as you used above to curl the library list. In the emulator click Menu|Host Settings and enter the host address of your OpenShift application.

When going back to the application using the little back arrow next to Menu, you should see a list of books.

You can now add, edit and delete books and switch between your browser and the emulator to verify that the client app is not cheating and that the books are in fact in the cloud on your JBossAS 7 instance.

In Eclipse you can go to the Debug perspective and click on the little Android robot in the lower right corner. This will display the LogCat view, which should display log output from that Android system as well as from this client app

Exploring the mobile client

There is a lot to writing high quality mobile applications. The goal of this little application is to get you started with JBossAS 7 / Android integration. There is also a portable approach to writing mobile applications. A popular one would be through PhoneGap. With PhoneGap you write your application in HTML+CSS+Java Script. It then runs in the browser of your mobile device. Naturally, not the full set of mobile platform APIs would be available through this approach.

The JAX-RS client application uses an annotated library client interface

There are two implementations of this interface available.

LibraryHttpclient

LibraryResteasyClient

The first uses APIs that are available in the Android SDK natively. The code is much more involved, but there would be no need to add external libraries (i.e. resteasy, jackson, etc). The effect is that the total size of the application is considerably smaller in size (i.e. 40k)

The second implementation uses the fabulous RESTEasy client proxy to interact with the JAX-RS endpoint. The details of Http connectivity and JSON data binding is transparently handled by RESTEasy. The total size of the application is considerably bigger in size (i.e. 400k)

Stay tuned for an update on a much more optimized version of the RESTEasy mobile client. Feasible is also a RESTEasy JavaScript library that would enable the portable PhoneGap approach.