OCWSD

RESTful web service :

@Path :

  • Paths are relative
  • Paths are relative. For an annotated class the base URI is the application path. For an annotated method the base URI is the effective URI of the containing class. For the purposes of absolutizing a path against the base URI , a leading ‘/’ in a path is ignored and base URIs are treated as if they ended in ‘/’. E.g.:

    @Path("widgets")
    public class WidgetsResource {
    
        @GET
        String getList() {...}
    
        @GET @Path("{id}")
        String getWidget(@PathParam("id") String id) {...}
    
    }
    

    In the above, if the application path is catalogue and the application is deployed at http://example.com/, then GET requests for http://example.com/catalogue/widgets will be handled by the getList() method while requests for http://example.com/catalogue/widgets/nnn (where nnn is some value) will be handled by the getWidget() method. The same would apply if the value of either @Path annotation started with ‘/’.

    A @Path value may or may not begin with a ‘/’, it makes no difference. Likewise, by default, a @Path value may or may not end in a ‘/’, it makes no difference, and thus request URLs that end or do not end in a ‘/’ will both be matched.

  • Regular expression in @Path
  • If it is required that a user name must only consist of lower and upper case alpha-numeric characters then it is possible to declare a particular regular expression, which overrides the default regular expression, “[^/]+?”, for example:

    @Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")
    

    In this type of example the username variable will only match user names that begin with one upper or lower case letter and zero or more alpha numeric characters and the underscore character. If a user name does not match that a 404 (Not Found) response will occur.

    @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”.

    @Produces can be applied at both the class and method levels. Here’s an example:

    @Path("/myResource")
    @Produces("text/plain")
    public class SomeResource {
        @GET
        public String doGetAsPlainText() {
            ...
        }
    
        @GET
        @Produces("text/html")
        public String doGetAsHtml() {
            ...
        }
    }
    

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

    If a resource class is capable of producing more that one MIME media type then the resource method chosen will correspond to the most acceptable media type as declared by the client. More specifically the Accept header of the HTTP request declared what is most acceptable. For example if the Accept header is:

    Accept: text/plain
    

    then the doGetAsPlainText method will be invoked.

    Alternatively if the Accept header is:

    Accept: text/plain; q=0.9, text/html
    

    which declares that the client can accept media types of “text/plain” and “text/html” but prefers the latter, then the doGetAsHtml method will be invoked.

    More than one media type may be declared in the same @Produces declaration, for example:

    @GET
    @Produces({"application/xml", "application/json"})
    public String doGetAsXmlOrJson() {
        ...
    }
    

    The doGetAsXmlOrJson method will get invoked if either of the media types “application/xml” and “application/json” are acceptable. If both are equally acceptable then the former will be chosen because it occurs first.

    The examples above refer explicitly to MIME media types for clarity. It is possible to refer to constant values, which may reduce typographical errors, see the constant field values of MediaType:

    APPLICATION_ATOM_XML          "application/atom+xml"
    APPLICATION_FORM_URLENCODED   "application/x-www-form-urlencoded"
    APPLICATION_JSON              "application/json"
    APPLICATION_OCTET_STREAM      "application/octet-stream"
    APPLICATION_SVG_XML           "application/svg+xml"
    APPLICATION_XHTML_XML         "application/xhtml+xml"
    APPLICATION_XML               "application/xml"
    MULTIPART_FORM_DATA           "multipart/form-data"
    TEXT_HTML                     "text/html"
    TEXT_PLAIN                    "text/plain"
    TEXT_XML                      "text/xml"
    WILDCARD                      "*/*"
    
    Advertisements

    Leave a Reply

    Fill in your details below or click an icon to log in:

    WordPress.com Logo

    You are commenting using your WordPress.com account. Log Out / Change )

    Twitter picture

    You are commenting using your Twitter account. Log Out / Change )

    Facebook photo

    You are commenting using your Facebook account. Log Out / Change )

    Google+ photo

    You are commenting using your Google+ account. Log Out / Change )

    Connecting to %s