sun.com docs.sun.com My Sun Worldwide Sites

  Previous Contents Next
Extracting Method Parameters From URIs

There are four types of parameters you can extract for use in your resource class: query parameters, URI parameters, header parameters, and matrix parameters.

Query parameters are extracted from the request URI query parameters, and are specified by using the com.sun.ws.rest.api.QueryParam annotation in the method parameter arguments.

URI parameters are extracted from the request URI, and the parameter names correspond to the URI Template variable names specified in the @UriTemplate class-level annotation. URI parameters are specified using the com.sun.ws.rest.api.UriParam annotation in the method parameter arguments.

Header parameters (indicated by decorating the parameter with com.sun.rest.api.HeaderParam) bind HTTP headers to method parameters, class fields, or bean properties. Matrix parameters (indicated by decorating the parameter with com.sun.rest.api.MatrixParam) bind URI matrix parameters to method parameters, class fields, or bean properties. Both of these parameters are beyond the scope of this tutorial.

@QueryParam and @UriParam can only be used on the following types:

  • all primitive types except char

  • all wrapper classes of primitive types except Character

  • String

  • any class with the static method valueOf(String)

  • any class with a constructor that takes a single String as a parameter

The following example shows how to use @UriTemplate variables and the @UriParam annotation in a method:

@UriTemplate("/{userName}")
public class MyResourceBean {
	...
	@HttpMethod("GET")
	public String printUserName(@UriParam("userName") String userId) {
		...
	}
}

In the above snippet, the URI Template variable name userName is specified as a parameter to the printUserName method. The @UriParam annotation is set to the variable name userName. At runtime, before printUserName is called, the value of userName is extracted from the URI and cast to a String. The resulting String is then available to the method as the userId variable.

If the URI Template variable cannot be cast to the specified type, the REST API runtime returns an HTTP “400 Bad Request” error to the client.

Using Entities and Representations

The Entity<?> types represent HTTP request entities, and are used to process request parameters. They are identified by MIME types specified in the ConsumeMime class or method-level annotation.

Like entities, the Representation<?> types make it easier to send a response back to the client. Representations isolate the relevant data required to respond to a request from the common data needed in the response.

The API includes a number of common Representation<?> and Entity<?>classes, but you can create custom representations for cases where the default representations will not work.

The com.sun.ws.rest.api.representation package contains classes that implement com.sun.ws.rest.api.Entity<T>. The Representation<T> generic base class represents a resource available on the web. The following table lists the default representations included in the API.

Table 6-4 Common Entities and Representations

Representation Class

Description

AtomEntryRepresentation

Representation of an ATOM entry

AtomFeedRepresentation

Representation of an ATOM feed

FormURLEncodedRepresentation

Representation of a URL-encoded form from a web page, as a java.util.Map<String, String>

JAXBRepresentation<T>

Representation of a JAXB element

MimeMultipartRepresentation

Representation of a javax.mail.internet.MimeMultipart resource, as a java.util.Map<String, DataSource>

StringRepresentation

Representation of a String

To create your own custom representation, implement the Entity<T> interface. The Representation<T> class implements Entity<T>, and is a helper class to aid in creating custom representations. To create custom representations, create a new representation class that extends Representation<T>.

Customizing Requests and Responses

The information sent to a resource and then passed back to the client is specified as a MIME type in the headers of an HTTP request or response. You can specify which MIME type a resource can respond to or produce by using the com.sun.ws.rest.api.ConsumeMime and com.sun.ws.rest.api.ProduceMime annotations.

By default, a resource class can respond to and produce all MIME types specified in the HTTP request and response headers.

The @ConsumeMime Annotation

The @ConsumeMime annotation is used to specify which MIME types a resource class or method can accept. If @ConsumeMime is applied at the class level, all the response methods accept the specified MIME types by default. If @ConsumeMime is applied at the method level, it overrides any @ConsumeMime annotations applied at the class level.

If a resource is unable to consume the MIME type of a client request, the REST API runtime sends back an HTTP “415 Unsupported Media Type” error.

The value of @ConsumeMime is a comma separated list of acceptable MIME types. For example:

@ConsumeMime("text/plain,text/html")

The following example shows how to apply @ConsumeMime at both the class and method levels:

@UriTemplate("/myResource")
@ConsumeMime("multipart/related")
public class SomeResource {
	@HttpMethod("POST")
	public String doPost(Representation<MimeMultipart> mimeMultipartData) {
		...
	}

	@HttpMethod("POST")
	@ConsumeMime("application/x-www-form-urlencoded")
	public String doPost(Representation<FormURLEncodedProperties> formData) {
		...
	}
}

The doPost method defaults to the MIME type of the @ConsumeMime annotation at the class level. The doPost method overrides the class level @ConsumeMime annotation to specify that it can accept URL-encoded form data.

If no resource methods can respond to the requested MIME type, an HTTP 415 error (Unsupported Media Type) is returned to the client.

The @ProduceMime Annotation

Similar to the @ConsumeMime annotation, the @ProduceMime annotation is used to specify the MIME types a resource can produce and send back to the client. If @ConsumeMime is applied at the class level, all the methods in a resource can produce the specified MIME types by default. If it is applied at the method level, it overrides any @ConsumeMime annotations applied at the class level.

If no methods in a resource are able to produce the MIME type in a client request, the REST API runtime sends back an HTTP “406 Not Acceptable” error.

The value of @ProduceMime is a comma separated list of MIME types. For example:

@ProduceMime("image/jpeg,image/png")

The following example shows how to apply @ProduceMime at both the class and method levels:

@UriTemplate("/myResource")
@ProduceMime("text/plain")
public class SomeResource {
	@HttpMethod("GET")
	public String doGetAsPlainText() {
		...
	}

	@HttpMethod("GET")
	@ProduceMime("text/html")
	public String doGetAsHtml() {
		...
	}
}

The doGetAsPlainText method defaults to the MIME type of the @ProduceMime annotation at the class level. The doGetAsHtml method's @ProduceMime annotation overrides the class-level @ProduceMime setting, and specifies that the method can produce HTML rather than plain text.

Previous Contents Next
Company Info Contact Terms of Use Privacy Copyright 1994-2007 Sun Microsystems, Inc.