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.http.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.annotation.*; 021import org.apache.juneau.httppart.*; 022import org.apache.juneau.oapi.*; 023 024/** 025 * REST request form-data annotation. 026 * 027 * <p> 028 * Identifies a POJO to be used as a form-data entry on an HTTP request. 029 * 030 * <p> 031 * Can be used in the following locations: 032 * <ul> 033 * <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods. 034 * <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces. 035 * <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces. 036 * </ul> 037 * 038 * <h5 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h5> 039 * <p> 040 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as a URL query parameter. 041 * 042 * <p> 043 * Unlike {@link FormData @FormData}, using this annotation does not result in the servlet reading the contents of 044 * URL-encoded form posts. 045 * Therefore, this annotation can be used in conjunction with the {@link Content @Content} annotation or 046 * <c>RestRequest.getContent()</c> method for <c>application/x-www-form-urlencoded POST</c> calls. 047 * 048 * <h5 class='section'>Example:</h5> 049 * <p class='bjava'> 050 * <ja>@RestGet</ja> 051 * <jk>public void</jk> doGet( 052 * <ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>, 053 * <ja>@Query</ja>(<js>"p2"</js>) String <jv>p2</jv>, 054 * <ja>@Query</ja>(<js>"p3"</js>) UUID <jv>p3</jv> 055 * ) {...} 056 * </p> 057 * 058 * <p> 059 * This is functionally equivalent to the following code... 060 * <p class='bjava'> 061 * <ja>@RestGet</ja> 062 * <jk>public void</jk> doGet(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) { 063 * <jk>int</jk> <jv>p1</jv> = <jv>req</jv>.getQueryParam(<js>"p1"</js>).asInteger().orElse(0); 064 * String <jv>p2</jv> = <jv>req</jv>.getQueryParam(<js>"p2"</js>).asString().orElse(<jk>null</jk>); 065 * UUID <jv>p3</jv> = <jv>req</jv>.getQueryParam(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>); 066 * ... 067 * } 068 * </p> 069 * 070 * <h5 class='section'>See Also:</h5><ul> 071 * <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a> 072 * <li class='extlink'><a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a> 073 * </ul> 074 * 075 * <h5 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h5> 076 * <p> 077 * <h5 class='section'>See Also:</h5><ul> 078 * <li class='link'><a class="doclink" href="../../../../../index.html#jrc.Query">@Query</a> 079 * </ul> 080 * 081 * <h5 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h5> 082 * <p> 083 * <h5 class='section'>See Also:</h5><ul> 084 * <li class='link'><a class="doclink" href="../../../../../index.html#jrc.Request">@Request</a> 085 * </ul> 086 * <p> 087 */ 088@Documented 089@Target({PARAMETER,METHOD,TYPE,FIELD}) 090@Retention(RUNTIME) 091@Inherited 092@Repeatable(QueryAnnotation.Array.class) 093@ContextApply(QueryAnnotation.Applier.class) 094public @interface Query { 095 096 /** 097 * Default value for this parameter. 098 * 099 * @return The annotation value. 100 */ 101 String def() default ""; 102 103 /** 104 * URL query parameter name. 105 * 106 * Required. The name of the parameter. Parameter names are case sensitive. 107 * 108 * <p> 109 * The value should be either a valid query parameter name, or <js>"*"</js> to represent multiple name/value pairs 110 * 111 * <p> 112 * A blank value (the default) has the following behavior: 113 * <ul class='spaced-list'> 114 * <li> 115 * If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean, 116 * then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs. 117 * 118 * <h5 class='figure'>Examples:</h5> 119 * <p class='bjava'> 120 * <jc>// When used on a REST method</jc> 121 * <ja>@RestPost</ja> 122 * <jk>public void</jk> addPet(<ja>@Query</ja> JsonMap <jv>allQueryParameters</jv>) {...} 123 * </p> 124 * <p class='bjava'> 125 * <jc>// When used on a remote method parameter</jc> 126 * <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>) 127 * <jk>public interface</jk> MyProxy { 128 * 129 * <jc>// Equivalent to @Query("*")</jc> 130 * <ja>@RemoteGet</ja>(<js>"/mymethod"</js>) 131 * String myProxyMethod1(<ja>@Query</ja> Map<String,Object> <jv>allQueryParameters</jv>); 132 * } 133 * </p> 134 * <p class='bjava'> 135 * <jc>// When used on a request bean method</jc> 136 * <jk>public interface</jk> MyRequest { 137 * 138 * <jc>// Equivalent to @Query("*")</jc> 139 * <ja>@Query</ja> 140 * Map<String,Object> getFoo(); 141 * } 142 * </p> 143 * </li> 144 * <li> 145 * If used on a request bean method, uses the bean property name. 146 * 147 * <h5 class='figure'>Example:</h5> 148 * <p class='bjava'> 149 * <jk>public interface</jk> MyRequest { 150 * 151 * <jc>// Equivalent to @Query("foo")</jc> 152 * <ja>@Query</ja> 153 * String getFoo(); 154 * } 155 * </p> 156 * </li> 157 * </ul> 158 * <h5 class='section'>Notes:</h5><ul> 159 * <li class='note'> 160 * The format is plain-text. 161 * </ul> 162 * 163 * @return The annotation value. 164 */ 165 String name() default ""; 166 167 /** 168 * Dynamically apply this annotation to the specified classes. 169 * 170 * <h5 class='section'>See Also:</h5><ul> 171 * <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 172 * </ul> 173 * 174 * @return The annotation value. 175 */ 176 String[] on() default {}; 177 178 /** 179 * Dynamically apply this annotation to the specified classes. 180 * 181 * <p> 182 * Identical to {@link #on()} except allows you to specify class objects instead of a strings. 183 * 184 * <h5 class='section'>See Also:</h5><ul> 185 * <li class='link'><a class="doclink" href="../../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 186 * </ul> 187 * 188 * @return The annotation value. 189 */ 190 Class<?>[] onClass() default {}; 191 192 /** 193 * Specifies the {@link HttpPartParser} class used for parsing strings to values. 194 * 195 * <p> 196 * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}. 197 * 198 * @return The annotation value. 199 */ 200 Class<? extends HttpPartParser> parser() default HttpPartParser.Void.class; 201 202 /** 203 * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>. 204 * 205 * <p> 206 * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type. 207 * Values specified on this field override values specified on the type, and values specified on child types override values 208 * specified on parent types. 209 * 210 * <p> 211 * The schema defining the type used for parameter. 212 * 213 * <h5 class='section'>Used for:</h5> 214 * <ul class='spaced-list'> 215 * <li> 216 * Server-side schema-based parsing and parsing validation. 217 * <li> 218 * Server-side generated Swagger documentation. 219 * <li> 220 * Client-side schema-based serializing and serializing validation. 221 * </ul> 222 * 223 * @return The annotation value. 224 */ 225 Schema schema() default @Schema; 226 227 /** 228 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 229 * 230 * <p> 231 * Overrides for this part the part serializer defined on the REST client which by default is {@link OpenApiSerializer}. 232 * 233 * @return The annotation value. 234 */ 235 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Void.class; 236 237 /** 238 * A synonym for {@link #name()}. 239 * 240 * <p> 241 * Allows you to use shortened notation if you're only specifying the name. 242 * 243 * <p> 244 * The following are completely equivalent ways of defining the existence of a query entry: 245 * <p class='bjava'> 246 * <jk>public</jk> Order placeOrder(<ja>@Query</ja>(name=<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...} 247 * </p> 248 * <p class='bjava'> 249 * <jk>public</jk> Order placeOrder(<ja>@Query</ja>(<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...} 250 * </p> 251 * 252 * @return The annotation value. 253 */ 254 String value() default ""; 255}