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.httppart.*;
021import org.apache.juneau.rest.*;
022
023/**
024 * Annotation that can be applied to a parameter of a {@link RestMethod @RestMethod} annotated method to identify it as a form post
025 * entry converted to a POJO.
026 * 
027 * <h5 class='section'>Example:</h5>
028 * <p class='bcode'>
029 *    <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
030 *    <jk>public void</jk> doPost(RestRequest req, RestResponse res,
031 *             <ja>@FormData</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@FormData</ja>(<js>"p2"</js>) String p2, <ja>@FormData</ja>(<js>"p3"</js>) UUID p3) {
032 *       ...
033 *    }
034 * </p>
035 * 
036 * <p>
037 * This is functionally equivalent to the following code...
038 * <p class='bcode'>
039 *    <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
040 *    <jk>public void</jk> doPost(RestRequest req, RestResponse res) {
041 *       <jk>int</jk> p1 = req.getFormData(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
042 *       String p2 = req.getFormData(String.<jk>class</jk>, <js>"p2"</js>);
043 *       UUID p3 = req.getFormData(UUID.<jk>class</jk>, <js>"p3"</js>);
044 *       ...
045 *    }
046 * </p>
047 * 
048 * <h5 class='topic'>Important note concerning FORM posts</h5>
049 * 
050 * This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody()} method
051 * for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet
052 * API to parse the body content as key-value pairs resulting in empty content.
053 * 
054 * <p>
055 * The {@link Query @Query} annotation can be used to retrieve a URL parameter in the URL string without triggering the
056 * servlet to drain the body content.
057 * 
058 * <h5 class='section'>See Also:</h5>
059 * <ul>
060 *    <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.FormData">Overview &gt; juneau-rest-server &gt; @FormData</a>
061 * </ul>
062 */
063@Documented
064@Target(PARAMETER)
065@Retention(RUNTIME)
066@Inherited
067public @interface FormData {
068
069   /**
070    * The default value for this form-data parameter if it's not present in the request.
071    */
072   String def() default "";
073
074   /**
075    * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
076    * 
077    * <p>
078    * Normally, we expect single parameters to be specified in UON notation for representing collections of values
079    * (e.g. <js>"key=(1,2,3)"</js>.
080    * This annotation allows the use of multi-part parameters to represent collections (e.g.
081    * <js>"key=1&amp;key=2&amp;key=3"</js>.
082    * 
083    * <p>
084    * This setting should only be applied to Java parameters of type array or Collection.
085    */
086   boolean multipart() default false;
087
088   /**
089    * FORM parameter name.
090    */
091   String name() default "";
092
093   /**
094    * Specifies the {@link HttpPartParser} class used for parsing values from strings.
095    * 
096    * <p>
097    * The default value for this parser is inherited from the servlet/method which defaults to {@link UonPartParser}.
098    * <br>You can use {@link SimplePartParser} to parse POJOs that are directly convertible from <code>Strings</code>.
099    */
100   Class<? extends HttpPartParser> parser() default HttpPartParser.Null.class;
101
102   /**
103    * A synonym for {@link #name()}.
104    * 
105    * <p>
106    * Allows you to use shortened notation if you're only specifying the name.
107    */
108   String value() default "";
109}