<chapter id="Using_Path">
<title>Using @Path and @GET, @POST, etc.</title>

<para>

<programlisting>
@Path("/library")
public class Library {

   @GET
   @Path("/books")
   public String getBooks() {...}

   @GET
   @Path("/book/{isbn}")
   public String getBook(@PathParam("isbn") String id) {
      // search my database and get a string representation and return it
   }

   @PUT
   @Path("/book/{isbn}")
   public void addBook(@PathParam("isbn") String id, @QueryParam("name") String name) {...}

   @DELETE
   @Path("/book/{id}")
   public void removeBook(@PathParam("id") String id {...}
   
}
</programlisting>
</para>
<para>

Let's say you have the RESTEasy servlet configured and reachable at a root path of http://myhost.com/services.  The requests would be handled by the Library class:
</para>
<para>

<itemizedlist>

<listitem>
 GET http://myhost.com/services/library/books
</listitem>

<listitem>
 GET http://myhost.com/services/library/book/333
</listitem>

<listitem>
 PUT http://myhost.com/services/library/book/333
</listitem>

<listitem>
 DELETE http://myhost.com/services/library/book/333
</listitem>

</itemizedlist>

</para>
<para>

The @jakarta.ws.rs.Path annotation must exist on either the class and/or a resource method.  If it exists on both the class and method, the relative path to the resource method is a concatenation of the class and method.
</para>
<para>

In the @jakarta.ws.rs package there are annotations for each HTTP method.  @GET, @POST, @PUT, @DELETE, and @HEAD.  You place these on public methods that you want to map to that certain kind of HTTP method.  As long as there is a @Path annotation on the class, you do not have to have a @Path annotation on the method you are mapping.  You can have more than one HTTP method as long as they can be distinguished from other methods.
</para>
<para>

When you have a @Path annotation on a method without an HTTP method, these are called JAXRSResourceLocators.
</para>
<para>


</para>
<sect1 id="_Path_and_regular_expression_mappings">
<title>@Path and regular expression mappings</title>

<para>

The @Path annotation is not limited to simple path expressions.  You also have the ability to insert regular expressions into @Path's value.  For example:
</para>
<para>

<programlisting>
@Path("/resources)
public class MyResource {

   @GET
   @Path("{var:.*}/stuff")
   public String get() {...}
}
</programlisting>
</para>
<para>

The following GETs will route to the getResource() method:
</para>
<para>

<programlisting>
GET /resources/stuff
GET /resources/foo/stuff
GET /resources/on/and/on/stuff
</programlisting>
</para>
<para>

The format of the expression is:
</para>
<para>

<programlisting>
"{" variable-name [ ":" regular-expression ] "}"
</programlisting>
</para>
<para>

The regular-expression part is optional.  When the expression is not provided, it defaults to a wildcard matching of one particular segment.  In regular-expression terms, the expression defaults to 
<programlisting>
"([]*)"
</programlisting>
</para>
<para>

For example:
</para>
<para>

@Path(&quot;/resources/{var}/stuff&quot;)
</para>
<para>

will match these:
</para>
<para>

<programlisting>
GET /resources/foo/stuff
GET /resources/bar/stuff
</programlisting>
</para>
<para>

but will not match:
</para>
<para>

<programlisting>
GET /resources/a/bunch/of/stuff
</programlisting>
</para>
<para>

</para>
<para>

</para>
<para>


</para>
</sect1>
</chapter>
