<chapter id="_PathParam">
<title>@PathParam</title>

<note>
   <para>
      RESTEasy <link linkend="_NewParam">supports <code>@PathParam</code> annotations with no parameter name.</link>.
   </para>
</note>

<para>

@PathParam is a parameter annotation which allows you to map variable URI path fragments into your method call.
</para>
<para>

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

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

What this allows you to do is embed variable identification within the URIs of your resources.  In the above example, an isbn URI parameter is used
to pass information about the book we want to access.  The parameter type you inject into can be any primitive type, a String, or any Java object that has
a constructor that takes a String parameter, or a static valueOf method that takes a String as a parameter.  For example, lets say we wanted isbn to be a real object.  We could do:
</para>
<para>

<programlisting>
@GET
@Path("/book/{isbn}")
public String getBook(@PathParam("isbn") ISBN id) {...}

public class ISBN {
   public ISBN(String str) {...}
}
</programlisting>
</para>
<para>

Or instead of a public String constructors, have a valueOf method:
</para>
<para>

<programlisting>
public class ISBN {
    public static ISBN valueOf(String isbn) {...}
}
</programlisting>
</para>
<para>

</para>
<para>


</para>
<sect1 id="Advanced__PathParam_and_Regular_Expressions">
<title>Advanced @PathParam and Regular Expressions</title>

<para>

There are a few more complicated uses of @PathParams not discussed in the previous section.
</para>
<para>

</para>
<para>


</para>
<para>

You are allowed to specify one or more path params embedded in one URI segment.  Here are some examples:
</para>
<para>

<programlisting>
1. @Path("/aaa{param}bbb")
2. @Path("/{name}-{zip}")
3. @Path("/foo{name}-{zip}bar")
</programlisting>
</para>
<para>

So, a URI of &quot;/aaa111bbb&quot; would match #1.  &quot;/bill-02115&quot; would match #2.  &quot;foobill-02115bar&quot; would match #3.
</para>
<para>


</para>
<para>

We discussed before how you can use regular expression patterns within @Path values.
</para>
<para>

<programlisting>
@GET
@Path("/aaa{param:b+}/{many:.*}/stuff")
public String getIt(@PathParam("param") String bs, @PathParam("many") String many) {...}
</programlisting>
</para>
<para>

For the following requests, lets see what the values of the &quot;param&quot; and &quot;many&quot; @PathParams would be:
</para>
<para>

<table frame="topbot">
<tgroup cols="3" rowsep="1" colsep="1">
<thead>
<row>
<entry>
Request</entry>
<entry>
param</entry>
<entry>
many</entry>
</row>
</thead>
<tbody>
<row>
<entry>
GET /aaabb/some/stuff</entry>
<entry>
bb</entry>
<entry>
some</entry>
</row>
<row>
<entry>
GET /aaab/a/lot/of/stuff</entry>
<entry>
b</entry>
<entry>
a/lot/of</entry>
</row>
</tbody>
</tgroup>
</table>

</para>
<para>


</para>
</sect1>
<sect1 id="_PathParam_and_PathSegment">
<title>@PathParam and PathSegment</title>

<para>

The specification has a very simple abstraction for examining a fragment of the URI path being invoked on  javax.ws.rs.core.PathSegment:
</para>
<para>

<programlisting>
public interface PathSegment {

    /**
     * Get the path segment.
     * &lt;p&gt;
     * @return the path segment
     */
    String getPath();
    
    /**
     * Get a map of the matrix parameters associated with the path segment
     * @return the map of matrix parameters
     */
    MultivaluedMap&lt;String, String&gt; getMatrixParameters();

}
</programlisting>
</para>
<para>

You can have RESTEasy inject a PathSegment instead of a value with your @PathParam.
</para>
<para>

<programlisting>
@GET
@Path("/book/{id}")
public String getBook(@PathParam("id") PathSegment id) {...}
</programlisting>
</para>
<para>

This is very useful if you have a bunch of @PathParams that use matrix parameters.  The idea of matrix parameters is
    that they are an arbitrary set of name-value pairs embedded in a uri path segment.  The PathSegment object gives you
    access to these parameters. See also MatrixParam.
</para>
<para>

A matrix parameter example is:
</para>
<para>

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke
</para>
<para>

The basic idea of matrix parameters is that it represents resources that are addressable by their attributes as well as their raw id.
</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>

</para>
<para>


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