<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.
</para>
<para>

GET /books?num=5
</para>
<para>

<programlisting>
@GET
public String getBooks(@HeaderParam("From") String from) {
...
}
</programlisting>
</para>
<para>

Like PathParam, your parameter type can be an String, primitive, or class that has a String constructor or static valueOf() method.  For example, MediaType has a valueOf() method and you could do:
</para>
<para>

<programlisting>
@PUT
public void put(@HeaderParam("Content-Type") MediaType contentType, ...)
</programlisting>
</para>
<para>

</para>
<para>


</para>

<section>
<title><classname>HeaderDelegate</classname>s</title>

<para>
In addition to the usual methods for translating parameters to and from strings, parameters annotated
with <classname>@HeaderParam</classname> have another option: implementations of 
<classname>RuntimeDelegate$HeaderDelegate</classname>:
</para>

<programlisting>
    /**
     * Defines the contract for a delegate that is responsible for
     * converting between the String form of a HTTP header and
     * the corresponding &REST-API; type {@code T}.
     *
     * @param &lt;T&gt; a &REST-API; type that corresponds to the value of a HTTP header.
     */
    public static interface HeaderDelegate&lt;T&gt; {

        /**
         * Parse the supplied value and create an instance of {@code T}.
         *
         * @param value the string value.
         * @return the newly created instance of {@code T}.
         * @throws IllegalArgumentException if the supplied string cannot be
         *                                  parsed or is {@code null}.
         */
        public T fromString(String value);

        /**
         * Convert the supplied value to a String.
         *
         * @param value the value of type {@code T}.
         * @return a String representation of the value.
         * @throws IllegalArgumentException if the supplied object cannot be
         *                                  serialized or is {@code null}.
         */
        public String toString(T value);
    }
</programlisting>

<para>
<classname>HeaderDelegate</classname> is similar to <classname>ParamConverter</classname>, but it is not
very convenient to register a <classname>HeaderDelegate</classname> since, unlike, for example,
<classname>ParamConverterProvider</classname>, it is not treated by the &REST-API; specification as a provider.
The class <classname>javax.ws.rs.core.Configurable</classname>, which is subclassed by, for example,
<classname>org.jboss.resteasy.spi.ResteasyProviderFactory</classname> has methods like
</para>

<programlisting>
    /**
     * Register a class of a custom &REST-API; component (such as an extension provider or
     * a {@link javax.ws.rs.core.Feature feature} meta-provider) to be instantiated
     * and used in the scope of this configurable context.
     *
     * ...
     *
     * @param componentClass &REST-API; component class to be configured in the scope of this
     *                       configurable context.
     * @return the updated configurable context.
     */
    public C register(Class&lt;?&gt; componentClass);
</programlisting>

<para>
but it is not clear that they are applicable to <classname>HeaderDelegate</classname>s.
</para>

<para>
RESTEasy approaches this problem by allowing <classname>HeaderDelegate</classname>s to be annotated
with <classname>@Provider</classname>. Not only will <methodname>ResteasyProviderFactory.register()</methodname>
process <classname>HeaderDelegate</classname>s, but another useful consequence is that
<classname>HeaderDelegate</classname>s can be discovered automatically at runtime.
</para>
</section>
</chapter>
