001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.commons.*;
025
026/**
027 * REST request form-data annotation.
028 *
029 * <p>
030 *    Identifies a POJO to be used as a form-data entry on an HTTP request.
031 *
032 * <p>
033 * Can be used in the following locations:
034 * <ul>
035 *    <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods.
036 *    <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces.
037 *    <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces.
038 * </ul>
039 *
040 * <h2 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h2>
041 * <p>
042 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as a URL query parameter.
043 *
044 * <p>
045 * Unlike {@link FormData @FormData}, using this annotation does not result in the servlet reading the contents of
046 * URL-encoded form posts.
047 * Therefore, this annotation can be used in conjunction with the {@link Content @Content} annotation or
048 * <c>RestRequest.getContent()</c> method for <c>application/x-www-form-urlencoded POST</c> calls.
049 *
050 * <h2 class='section'>Example:</h2>
051 * <p class='bjava'>
052 *    <ja>@RestGet</ja>
053 *    <jk>public void</jk> doGet(
054 *          <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>,
055 *          <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>,
056 *          <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv>
057 *       ) {...}
058 * </p>
059 *
060 * <p>
061 * This is functionally equivalent to the following code...
062 * <p class='bjava'>
063 *    <ja>@RestGet</ja>
064 *    <jk>public void</jk> doGet(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
065 *       <jk>int</jk> <jv>p1</jv> = <jv>req</jv>.getQueryParam(<js>"p1"</js>).asInteger().orElse(0);
066 *       String <jv>p2</jv> = <jv>req</jv>.getQueryParam(<js>"p2"</js>).asString().orElse(<jk>null</jk>);
067 *       UUID <jv>p3</jv> = <jv>req</jv>.getQueryParam(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>);
068 *       ...
069 *    }
070 * </p>
071 *
072 * <h2 class='section'>See Also:</h2><ul>
073 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
074 *    <li class='extlink'><a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>
075 * </ul>
076 *
077 * <h2 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h2>
078 * <h2 class='section'>See Also:</h2><ul>
079 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Query">@Query</a>
080 * </ul>
081 *
082 * <h2 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h2>
083 * <h2 class='section'>See Also:</h2><ul>
084 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a>
085 * </ul>
086 */
087@Documented
088@Target({ PARAMETER, METHOD, TYPE, FIELD })
089@Retention(RUNTIME)
090@Inherited
091public @interface Query {
092
093   /**
094    * Default value for this parameter.
095    *
096    * @return The annotation value.
097    */
098   String def() default "";
099
100   /**
101    * Optional description for the exposed API.
102    *
103    * @return The annotation value.
104    * @since 9.2.0
105    */
106   String[] description() default {};
107
108   /**
109    * Short, concise summary of the exposed API.
110    *
111    * <p>
112    * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation,
113    * or any context where brevity matters. See {@link Schema#summary()}
114    * for the canonical definition.
115    *
116    * @return The annotation value.
117    * @since 10.0.0
118    */
119   String summary() default "";
120
121   /**
122    * URL query parameter name.
123    *
124    * Required. The name of the parameter. Parameter names are case sensitive.
125    *
126    * <p>
127    * The value should be either a valid query parameter name, or <js>"*"</js> to represent multiple name/value pairs
128    *
129    * <p>
130    * A blank value (the default) has the following behavior:
131    * <ul class='spaced-list'>
132    *    <li>
133    *       If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean,
134    *       then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs.
135    *
136    *       <h4 class='figure'>Examples:</h4>
137    *       <p class='bjava'>
138    *    <jc>// When used on a REST method</jc>
139    *    <ja>@RestPost</ja>
140    *    <jk>public void</jk> addPet(<ja>@Query</ja> JsonMap <jv>allQueryParameters</jv>) {...}
141    *       </p>
142    *       <p class='bjava'>
143    *    <jc>// When used on a remote method parameter</jc>
144    *    <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>)
145    *    <jk>public interface</jk> MyProxy {
146    *
147    *       <jc>// Equivalent to @Query("*")</jc>
148    *       <ja>@RemoteGet</ja>(<js>"/mymethod"</js>)
149    *       String myProxyMethod1(<ja>@Query</ja> Map&lt;String,Object&gt; <jv>allQueryParameters</jv>);
150    *    }
151    *       </p>
152    *       <p class='bjava'>
153    *    <jc>// When used on a request bean method</jc>
154    *    <jk>public interface</jk> MyRequest {
155    *
156    *       <jc>// Equivalent to @Query("*")</jc>
157    *       <ja>@Query</ja>
158    *       Map&lt;String,Object&gt; getFoo();
159    *    }
160    *       </p>
161    *    </li>
162    *    <li>
163    *       If used on a request bean method, uses the bean property name.
164    *
165    *       <h4 class='figure'>Example:</h4>
166    *       <p class='bjava'>
167    *    <jk>public interface</jk> MyRequest {
168    *
169    *       <jc>// Equivalent to @Query("foo")</jc>
170    *       <ja>@Query</ja>
171    *       String getFoo();
172    *    }
173    *       </p>
174    *    </li>
175    * </ul>
176    * <h4 class='section'>Notes:</h4><ul>
177    *    <li class='note'>
178    *       The format is plain-text.
179    * </ul>
180    *
181    * @return The annotation value.
182    */
183   String name() default "";
184
185   /**
186    * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>.
187    *
188    * <p>
189    * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type.
190    * Values specified on this field override values specified on the type, and values specified on child types override values
191    * specified on parent types.
192    *
193    * <p>
194    * The schema defining the type used for parameter.
195    *
196    * <h4 class='section'>Used for:</h4>
197    * <ul class='spaced-list'>
198    *    <li>
199    *       Server-side schema-based parsing and parsing validation.
200    *    <li>
201    *       Server-side generated Swagger documentation.
202    *    <li>
203    *       Client-side schema-based serializing and serializing validation.
204    * </ul>
205    *
206    * @return The annotation value.
207    */
208   Schema schema() default @Schema;
209
210   /**
211    * A synonym for {@link #name()}.
212    *
213    * <p>
214    * Allows you to use shortened notation if you're only specifying the name.
215    *
216    * <p>
217    * The following are completely equivalent ways of defining the existence of a query entry:
218    * <p class='bjava'>
219    *    <jk>public</jk> Order placeOrder(<ja>@Query</ja>(name=<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...}
220    * </p>
221    * <p class='bjava'>
222    *    <jk>public</jk> Order placeOrder(<ja>@Query</ja>(<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...}
223    * </p>
224    *
225    * @return The annotation value.
226    */
227   String value() default "";
228}