Chapter 2. Overview of JAX-RS 1.1

2.1. Root Resource Classes

Root resource classes are POJOs (Plain Old Java Objects) that are annotated with @Path have at least one method annotated with @Path or a resource method designator annotation such as @GET, @PUT, @POST, @DELETE. Resource methods are methods of a resource class annotated with a resource method designator. This section shows how to use Jersey to annotate Java objects to create RESTful web services.

2.1.1. @Path

The @Path annotation's value is a relative URI path. In the example above, the Java class will be hosted at the URI path /helloworld. This is an extremely simple use of the @Path annotation. What makes JAX-RS so useful is that you can embed variables in the URIs.

2.1.2. HTTP Methods

@GET, @PUT, @POST, @DELETE and @HEAD are resource method designator annotations defined by JAX-RS and which correspond to the similarly named HTTP methods. In the example above, the annotated Java method will process HTTP GET requests. The behavior of a resource is determined by which of the HTTP methods the resource is responding to.

2.1.3. @Produces

The @Produces annotation is used to specify the MIME media types of representations a resource can produce and send back to the client. In this example, the Java method will produce representations identified by the MIME media type "text/plain".

2.1.4. @Consumes

The @Consumes annotation is used to specify the MIME media types of representations a resource can consume that were sent by the client. 

2.2. Deploying a RESTful Web Service

2.3. Extracting Request Parameters

2.4. Representations and Java Types

2.5. Building Responses

2.6. Sub-resources

2.7. Building URIs

2.8. WebApplicationException and Mapping Exceptions to Responses

2.9. Conditional GETs and Returning 304 (Not Modified) Responses

2.10. Life-cycle of Root Resource Classes

2.11. Security

2.12. Rules of Injection

2.13. Use of @Context

2.14. Annotations Defined By JAX-RS

简单实例：

package sample.hello.resources;

import javax.ws.rs.DefaultValue;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.QueryParam;
import javax.ws.rs.core.MediaType;


//URI path templates are URIs with variables embedded within the URI syntax. 
//These variables are substituted at runtime in order for a resource to respond to 
//a request based on the substituted URI. Variables are denoted by curly braces.
//@Path("/users/{username}")
//public String sayHello(@PathParam("username") String userName)

//f it is required that a user name must only consist of lower and upper case numeric characters 
//then it is possible to declare a particular regular expression, which overrides the default regular expression, "[^/]+?", for example:
//@Path("/hello/{username: [a-zA-Z][a-zA-Z_0-9]*}")

@Path("/hello/{username: [a-zA-Z][a-zA-Z_0-9]*}")
public class HelloResource {
	@GET
	//The @Produces annotation is used to specify the MIME media types of representations a resource 
	//can produce and send back to the client. 
	@Produces(MediaType.TEXT_PLAIN)
	
	//@QueryParam is used to extract query parameters from the Query component of the request URL. The following example is an extract from the sparklines sample:
	//If a query parameter "myname" exists in the query component of the request URI 
	//then the "myname" value will be will extracted and assigned to the step method parameter. 
	//If "myname" does not exist then a default value of nick, as declared in the @DefaultValue annotation, 
	//will be assigned to the step method parameter.
	//http://localhost:8080/testWeb/rest/hello/aaa?myname='John'
	public String sayHello(@PathParam("username") String userName,
			@DefaultValue("nick") @QueryParam("myname") String myname) {
		return "Hello " + userName + " , my name is " + myname;
	}
}

访问URL： http://localhost:8080/testWeb/rest/hello/aaa?myname='bbb'

页面响应：

Hello aaa , my name is 'bbb'