JAX-RS Concepts

Introduction to JAX-RS concepts - TBD

Applications

A JAX-RS application consists of one or more resources and zero or more providers. A JAX-RS application is packaged as a Web application in a .war file. The Application subclass, resource classes, and providers are packaged in WEB-INF/classes file and the required libraries are packaged in WEB-INF/lib. Included libraries can also contain resource classes and providers as desired.
When using a Servlet 3 container, the Application subclass is optional. By default, all root resource classes and providers packaged in the web application must be included in the published JAX-RS application.

Including Subclasses

An Application subclass can be included in a .war file to override the default behavior. If both getClasses and getSingletons return an empty list then the default "willset" of classes must be used. The implementations should support the Servlet 3 framework pluggability mechanism to enable portability between containers and to avail themselves of container-supplied class scanning facilities.

Servlet Containers

When using a non-JAX-RS aware servlet container, the servlet-class or filter-class element of the web.xml descriptor should name the JAX-RS implementation-supplied Servlet or Filter class respectively. The application-supplied subclass of the application is identified, using an init-param with a param-name of the "javax.ws.rs.application".

Resources

TBD

Providers

TBD

Runtime Delegates

(JSR 311) is a Java API for implementing REST applications. Apache Wink implements JAX-RS 1.0.

For those new to JAX-RS or developing REST applications, follow this in-progress user guide. If you have comments or questions, send an e-mail to the appropriate Apache Wink mailing lists.

While this user guide covers common scenarios, it is not intended to detail the JAX-RS specification itself. Please read the (brief yet understandable) specification if it is available to you.

Simple JAX-RS Application

• Create Resource
• Create javax.ws.rs.core.Application sub-class
• How to Package Apache Wink with Web Application
• Install and Run

Application Configuration

• javax.ws.rs.core.Application subclass
• Container environment information

Resources, HTTP Methods, and Paths

• Root Resource Methods
• javax.ws.rs.core.Response
• HTTP Methods
• Subresource Methods
• Subresource Locators
• Regular Expressions

Request and Response Entities (Message Bodies) and Media Types

• Produces/Consumes annotations
• ATOM
• XML
• JSON
• Standard Entity Parameter Types
• Custom application provided Message Body Readers/Writers
• Transfer Encoding
• Content Encoding

Parameters

• Query Parameters
• Path Parameters
• Matrix Parameters
• Header Parameters
• Cookie Parameters

HTTP Headers

• Common HTTP Request Headers
• Common HTTP Response Headers

Content Negotiation

• Using URIs to identify content type
• Using parameters to identify content type
• Using Accept headers

Using Request Context Information

• HTTP Headers
• URI Information
• Security Information
• Request
• Providers

Caching

• Expires
• Cache-Control

...