<chapter id="_OptionalParam">
    <title>Optional parameter types</title>
    <para>RESTEasy offers a mechanism to support a series of <code>java.util.Optional</code> types as a wrapper object types. This
        will give users the ability to use optional typed parameters, and eliminate all null checks by using methods
        like <code>Optional.orElse()</code>.
    </para>
    <para>Here is the sample:</para>
    <programlisting><![CDATA[@Path("/double")
@GET
public String optDouble(@QueryParam("value") OptionalDouble value) {
    return Double.toString(value.orElse(4242.0));
}
]]></programlisting>
    <para>
        From the above sample code we can see that the <code>OptionalDouble</code> can be used as parameter type, and when users
        don't provide a value in <code>@QueryParam</code>, then the default value will be returned.
    </para>
    <para>
        Here is the list of supported optional parameter types:
        <itemizedlist>
            <listitem>
                <para>@QueryParam</para>
            </listitem>
            <listitem>
                <para>@FormParam</para>
            </listitem>
            <listitem>
                <para>@MatrixParam</para>
            </listitem>
            <listitem>
                <para>@HeaderParam</para>
            </listitem>
            <listitem>
                <para>@CookieParam</para>
            </listitem>
        </itemizedlist>
    </para>
    <para>
        As the list shown above, those parameter types support the Java-provided <code>Optional</code> types. Please note that the <code>@PathParam</code> is an exception for which <code>Optional</code> is not available. The reason is that <code>Optional</code> for the <code>@PathParam</code> use case would just be a NO-OP, since an element of the path cannot be omitted.
    </para>

    <para>
      The <code>Optional</code> types can also be used as type of the fields of a <code>@BeanParam</code>'s class.
    </para>

    <para>Here is an example of endpoint with a <code>@BeanParam</code>:</para>

    <programlisting><![CDATA[@Path("/double")
@GET
public String optDouble(@BeanParam Bean bean) {
    return Double.toString(bean.value.orElse(4242.0));
}]]></programlisting>

  <para>The corresponding class <code>Bean</code>:</para>

  <programlisting><![CDATA[public class Bean {
    @QueryParam("value")
    OptionalDouble value;
}]]></programlisting>

  <para> Finally, the <code>Optional</code> types can be used directly as type of the fields of a JAX-RS resource class.</para>

  <para>Here is an example of a JAX-RS resource class with an <code>Optional</code> type:</para>

  <programlisting><![CDATA[@RequestScoped
public class OptionalResource {
    @QueryParam("value")
    Optional<String> value;
    ...
}]]></programlisting>
</chapter>
