001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.rest.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019
020import org.apache.juneau.rest.*;
021
022/**
023 * Annotation that can be applied to a parameter of a {@link RestMethod @RestMethod} annotated method to identify whether or not
024 * the request has the specified multipart form POST parameter.
025 * 
026 * <p>
027 * Note that this can be used to detect the existence of a parameter when it's not set to a particular value.
028 * 
029 * <h5 class='section'>Example:</h5>
030 * <p class='bcode'>
031 *    <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
032 *    <jk>public void</jk> doPost(<ja>@HasFormData</ja>(<js>"p1"</js>) <jk>boolean</jk> p1) {
033 *       ...
034 *    }
035 * </p>
036 * 
037 * <p>
038 * This is functionally equivalent to the following code...
039 * <p class='bcode'>
040 *    <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
041 *    <jk>public void</jk> doPost(RestRequest req) {
042 *       <jk>boolean</jk> p1 = req.hasFormData(<js>"p1"</js>);
043 *       ...
044 *    }
045 * </p>
046 * 
047 * <p>
048 * The following table shows the behavioral differences between <code>@HasFormData</code> and <code>@FormData</code>...
049 * <table class='styled'>
050 *    <tr>
051 *       <th><code>Body content</code></th>
052 *       <th><code><ja>@HasFormData</ja>(<js>"a"</js>)</code></th>
053 *       <th><code><ja>@FormData</ja>(<js>"a"</js>)</code></th>
054 *    </tr>
055 *    <tr>
056 *       <td><code>a=foo</code></td>
057 *       <td><jk>true</jk></td>
058 *       <td><js>"foo"</js></td>
059 *    </tr>
060 *    <tr>
061 *       <td><code>a=</code></td>
062 *       <td><jk>true</jk></td>
063 *       <td><js>""</js></td>
064 *    </tr>
065 *    <tr>
066 *       <td><code>a</code></td>
067 *       <td><jk>true</jk></td>
068 *       <td><jk>null</jk></td>
069 *    </tr>
070 *    <tr>
071 *       <td><code>b=foo</code></td>
072 *       <td><jk>false</jk></td>
073 *       <td><jk>null</jk></td>
074 *    </tr>
075 * </table>
076 * 
077 * <h5 class='topic'>Important note concerning FORM posts</h5>
078 * 
079 * This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody()} method
080 * for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet API to
081 * parse the body content as key-value pairs, resulting in empty content.
082 * 
083 * <p>
084 * The {@link HasQuery @HasQuery} annotation can be used to check for the existing of a URL parameter in the URL string
085 * without triggering the servlet to drain the body content.
086 * 
087 * <h5 class='section'>See Also:</h5>
088 * <ul>
089 *    <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.FormData">Overview &gt; juneau-rest-server &gt; @FormData</a>
090 * </ul>
091 */
092@Documented
093@Target(PARAMETER)
094@Retention(RUNTIME)
095@Inherited
096public @interface HasFormData {
097
098   /**
099    * FORM parameter name.
100    */
101   String name() default "";
102
103   /**
104    * A synonym for {@link #name()}.
105    * 
106    * <p>
107    * Allows you to use shortened notation if you're only specifying the name.
108    */
109   String value() default "";
110}