Documentation for new param annotations RESTEASY-1880

docbook/reference/en/en-US/master.xml

@@ -14,6 +14,7 @@
                 <!ENTITY _CookieParam SYSTEM "modules/_CookieParam.xml">
                 <!ENTITY _FormParam SYSTEM "modules/_FormParam.xml">
                 <!ENTITY _Form SYSTEM "modules/_Form.xml">
+                <!ENTITY _NewParam SYSTEM "modules/_NewParam.xml">
                 <!ENTITY Cache_NoCache_CacheControl SYSTEM "modules/Cache_NoCache_CacheControl.xml">
                 <!ENTITY _DefaultValue SYSTEM "modules/_DefaultValue.xml">
                 <!ENTITY _Encoded_and_encoding SYSTEM "modules/_Encoded_and_encoding.xml">
@@ -111,6 +112,7 @@ This one is short
    &_CookieParam;
    &_FormParam;
    &_Form;
+   &_NewParam;
    &_DefaultValue;
    &_Encoded_and_encoding;
    &_Context;

docbook/reference/en/en-US/modules/_CookieParam.xml

@@ -1,6 +1,12 @@
 <chapter id="_CookieParam">
 <title>@CookieParam</title>
 
+<note>
+   <para>
+      RESTEasy <link linkend="_NewParam">supports <code>@CookieParam</code> annotations with no parameter name.</link>.
+   </para>
+</note>
+
 <para>
 
 The @CookieParam annotation allows you to inject the value of a cookie or an object representation of an HTTP request cookie into your method invocation

docbook/reference/en/en-US/modules/_FormParam.xml

@@ -1,6 +1,12 @@
 <chapter id="_FormParam">
 <title>@FormParam</title>
 
+<note>
+   <para>
+      RESTEasy <link linkend="_NewParam">supports <code>@FormParam</code> annotations with no parameter name.</link>.
+   </para>
+</note>
+
 <para>
 
 When the input request body is of the type &quot;application/x-www-form-urlencoded&quot;, a.k.a. an HTML Form, you can inject individual form parameters from the request body into method parameter values.

docbook/reference/en/en-US/modules/_HeaderParam.xml

@@ -1,6 +1,12 @@
 <chapter id="_HeaderParam">
 <title>@HeaderParam</title>
 
+<note>
+   <para>
+      RESTEasy <link linkend="_NewParam">supports <code>@HeaderParam</code> annotations with no parameter name.</link>.
+   </para>
+</note>
+
 <para>
 
 The @HeaderParam annotation allows you to map a request HTTP header to your method invocation.

docbook/reference/en/en-US/modules/_MatrixParam.xml

@@ -1,6 +1,12 @@
 <chapter id="_MatrixParam">
 <title>@MatrixParam</title>
 
+<note>
+   <para>
+      RESTEasy <link linkend="_NewParam">supports <code>@MatrixParam</code> annotations with no parameter name.</link>.
+   </para>
+</note>
+
 <para>
 
 The idea of matrix parameters is that they are an arbitrary set of name-value pairs embedded in a uri path segment.  

docbook/reference/en/en-US/modules/_NewParam.xml

@@ -0,0 +1,59 @@
+<chapter id="_NewParam">
+<title>Improved <code>@…Param</code> annotations</title>
+
+<para>
+With the addition of parameter names in the bytecode since Java 8, it is no longer necessary to require users to specify parameter names
+in the following annotations: <link linkend="_PathParam"><code>@PathParam</code></link>, 
+<link linkend="_QueryParam"><code>@QueryParam</code></link>, <link linkend="_FormParam"><code>@FormParam</code></link>,
+<link linkend="_CookieParam"><code>@CookieParam</code></link>, <link linkend="_HeaderParam"><code>@HeaderParam</code></link>
+and <link linkend="_MatrixParam"><code>@MatrixParam</code></link>. In order to benefit from this feature, you have to switch to new annotations
+with the same name, in a different package, which have an optional value parameter. To use this, follow these steps:
+</para>
+<itemizedlist>
+  <listitem>Import the <code>org.jboss.resteasy.annotations.jaxrs</code> package to replace annotations from the JAX-RS spec.</listitem>
+  <listitem>Tell your build system to record method parameter names in the bytecode.</listitem>
+  <listitem>Remove the annotation value if the name matches the name of the annotated variable.</listitem>
+</itemizedlist>
+<para>
+Note that you can omit the annotation name for annotated method parameters as well as annotated fields or JavaBean properties.
+</para>
+<para>
+For Maven users, recording method parameter names in the bytecode can be enabled by setting the <code>maven.compiler.parameters</code> 
+to <code>true</code>:
+</para>
+<programlisting><![CDATA[
+    <properties>
+        <maven.compiler.parameters>true</maven.compiler.parameters>
+    </properties>
+]]></programlisting>
+<para>Usage:</para>
+<programlisting>
+import org.jboss.resteasy.annotations.jaxrs.*;
+
+@Path("/library")
+public class Library {
+
+   @GET
+   @Path("/book/{isbn}")
+   public String getBook(@PathParam String isbn) {
+      // search my database and get a string representation and return it
+   }
+}
+</programlisting>
+
+<para>If your annotated variable does not have the same name as the path parameter, you can still
+specify the name:</para>
+<programlisting>
+import org.jboss.resteasy.annotations.jaxrs.*;
+
+@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>
+</chapter>

docbook/reference/en/en-US/modules/_PathParam.xml

@@ -1,6 +1,12 @@
 <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.

docbook/reference/en/en-US/modules/_QueryParam.xml

@@ -1,6 +1,12 @@
 <chapter id="_QueryParam">
 <title>@QueryParam</title>
 
+<note>
+   <para>
+      RESTEasy <link linkend="_NewParam">supports <code>@QueryParam</code> annotations with no parameter name.</link>.
+   </para>
+</note>
+
 <para>
 
 The @QueryParam annotation allows you to map a URI query string parameter or url form encoded parameter to your method invocation.