Andy Computer Blog: Principle of Jersey

1. Basci principle
REST is an architectural style which is based on web-standards and the HTTP protocol.

REST allows that resources have different representations, e.g., text, XML, JSON etc. The REST client can ask for a specific representation via the HTTP protocol (content negotiation

The PUT, GET, POST and DELETE methods are typical used in REST based architectures. The following table gives an explanation of these operations.

GET defines a reading access of the resource without side-effects. The resource is never changed via a GET request, e.g., the request has no side effects (idempotent).
PUT creates a new resource. It must also be idempotent.
DELETE removes the resources. The operations are idempotent. They can get repeated without leading to different results.
POST updates an existing resource or creates a new resource.

Reference: article

2. About jersey

Jersey is

2.1. JAX-RS

Java defines REST support via the Java Specification Request (JSR) 311. This specification is called JAX-RS (The Java API for RESTful Web Services). JAX-RS uses annotations to define the REST relevance of Java classes.

2.2. Jersey

The Jersey implementation provides a library to implement Restful webservices in a Java servlet container. It is the reference implementation for the JSR 311 specification.

Jersey provides a servlet implementation which scans predefined classes to identify RESTful resources. You use annotations in the class and methods to define their responsibility.

2.3 Histroy

Biggest difference between Jersey 1 and Jersey 2 in this regard is used namespace. Jersey 1 uses prefix com.sun.jersey (even for property names) which is not true for the namespace of Jersey 2 that starts with org.glassfish.jersey. Besides that Jersey 2 does NOT support properties from Jersey 1 and you need to use specific ones (from Jersey 2) to make things work. ref

3. Jersey annotation

Annotation:J2SE 5.0 中對 metadata 提出的功能是 Annotation，metadata 就是「資料的資料」（Data about data），突然看到這樣的解釋會覺得奇怪，但以表格為例，表格中呈現的就是資料，但有時候還會有額外的資料用來說明表格的作用，從這個角度來看，metadata 就不這麼的奇怪。

在 J2SE 5.0 中，Annotation 的主要目的介於原始碼與 API 文件說明之間，Annotation 對程式碼作出一些說明與解釋，Class 中可以包含這些解釋，編譯器或其它程式分析工作可以使用 Annotation 來作分析，您可以從 java.lang.Override、java.lang.Deprecated、java.lang.SuppressWarnings 這三個 J2SE 5.0 中標準的 Annotation 型態開始瞭解 Annotation 的作用。 ref

Annotation Description

Annotation	Description
@PATH(your_path)	Sets the path to base URL + /your_path. The base URL is based on your application name (the context root), the servlet and the URL pattern from the `web.xml` configuration file.
@POST	Indicates that the following method will answer to an HTTP POST request.
@GET	Indicates that the following method will answer to an HTTP GET request.
@PUT	Indicates that the following method will answer to an HTTP PUT request.
@DELETE	Indicates that the following method will answer to an HTTP DELETE request.
@Produces(MediaType.TEXT_PLAIN[, more-types])	@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text ("text/plain") is produced. Other examples would be "application/xml" or "application/json".
@Consumes(type[, more-types])	@Consumes defines which MIME type is consumed by this method.
@PathParam	Used to inject values from the URL into a method parameter. This way you inject, for example, the ID of a resource into the method to get the correct object.

@PATH(your_path)

Sets the path to base URL + /your_path. The base URL is based on your application name (the context root), the servlet and the URL pattern from the web.xml configuration file.

@POST

Indicates that the following method will answer to an HTTP POST request.

@GET

Indicates that the following method will answer to an HTTP GET request.

@PUT

Indicates that the following method will answer to an HTTP PUT request.

@DELETE

Indicates that the following method will answer to an HTTP DELETE request.

@Produces(MediaType.TEXT_PLAIN[, more-types])

@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text ("text/plain") is produced. Other examples would be "application/xml" or "application/json".

@Consumes(type[, more-types])

@Consumes defines which MIME type is consumed by this method.

@PathParam

Used to inject values from the URL into a method parameter. This way you inject, for example, the ID of a resource into the method to get the correct object.

Reference: article.html

4. Return code

1xx: Informational - Communicates transfer protocol-level information
2xx: Success -Indicates that the client’s request was accepted successfully.
3xx: Redirection - Indicates that the client must take some additional action in order to complete their request.
4xx: Client Error - This category of error status codes points the finger at clients.
5xx: Server Error - The server takes responsibility for these error status codes.