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