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 form-data parameter. 043 * 044 * <h2 class='section'>Example:</h2> 045 * <p class='bjava'> 046 * <ja>@RestPost</ja> 047 * <jk>public void</jk> doPost( 048 * <ja>@FormData</ja>(<js>"p1"</js>) <jk>int</jk> <jv>p1</jv>, 049 * <ja>@FormData</ja>(<js>"p2"</js>) String <jv>p2</jv>, 050 * <ja>@FormData</ja>(<js>"p3"</js>) UUID <jv>p3</jv> 051 * ) {...} 052 * </p> 053 * 054 * <p> 055 * This is functionally equivalent to the following code... 056 * <p class='bjava'> 057 * <ja>@RestPost</ja> 058 * <jk>public void</jk> doPost(RestRequest <jv>req</jv>) { 059 * <jk>int</jk> <jv>p1</jv> = <jv>req</jv>.getFormParam(<js>"p1"</js>).as(<jk>int</jk>.<jk>class</jk>).orElse(0); 060 * String <jv>p2</jv> = <jv>req</jv>.getFormParam(<js>"p2"</js>).asString().orElse(<jk>null</jk>); 061 * UUID <jv>p3</jv> = <jv>req</jv>.getFormParam(<js>"p3"</js>).as(UUID.<jk>class</jk>).orElse(<jk>null</jk>); 062 * ... 063 * } 064 * </p> 065 * 066 * <h2 class='section'>See Also:</h2><ul> 067 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> 068 * <li class='extlink'><a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a> 069 * </ul> 070 * 071 * <h2 class='topic'>Important note concerning FORM posts</h2> 072 * <p> 073 * This annotation should not be combined with the {@link Content @Content} annotation or <c>RestRequest.getContent()</c> method 074 * for <c>application/x-www-form-urlencoded POST</c> posts, since it will trigger the underlying servlet 075 * API to parse the body content as key-value pairs resulting in empty content. 076 * 077 * <p> 078 * The {@link Query @Query} annotation can be used to retrieve a URL parameter in the URL string without triggering the 079 * servlet to drain the body content. 080 * 081 * <h2 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h2> 082 * <p> 083 * Annotation applied to Java method arguments of interface proxies to denote that they are FORM post parameters on the 084 * request. 085 * 086 * <h2 class='section'>See Also:</h2><ul> 087 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/FormData">@FormData</a> 088 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a> 089 * </ul> 090 * 091 * <h2 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h2> 092 * <h2 class='section'>See Also:</h2><ul> 093 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a> 094 * </ul> 095 * 096 * <div class='warn'> 097 * This annotation should not be combined with the {@link Content @Content} annotation or <c>RestRequest#getContent()</c> method 098 * for <c>application/x-www-form-urlencoded POST</c> posts, since it will trigger the underlying servlet 099 * API to parse the body content as key-value pairs resulting in empty content. 100 * <br>The {@link Query @Query} annotation can be used to retrieve a URL parameter in the URL string without triggering the 101 * servlet to drain the body content. 102 * </div> 103 * <div class='warn'> 104 * If using this annotation on a Spring bean, note that you are likely to encounter issues when using on parameterized 105 * types such as <code>List<MyBean></code>. This is due to the fact that Spring uses CGLIB to recompile classes 106 * at runtime, and CGLIB was written before generics were introduced into Java and is a virtually-unsupported library. 107 * Therefore, parameterized types will often be stripped from class definitions and replaced with unparameterized types 108 * (e.g. <code>List</code>). Under these circumstances, you are likely to get <code>ClassCastExceptions</code> 109 * when trying to access generalized <code>JsonMaps</code> as beans. The best solution to this issue is to either 110 * specify the parameter as a bean array (e.g. <code>MyBean[]</code>) or declare the method as final so that CGLIB 111 * will not try to recompile it. 112 * </div> 113 * 114 */ 115@Documented 116@Target({ PARAMETER, METHOD, TYPE, FIELD }) 117@Retention(RUNTIME) 118@Inherited 119public @interface FormData { 120 121 /** 122 * Default value for this parameter. 123 * 124 * @return The annotation value. 125 */ 126 String def() default ""; 127 128 /** 129 * Optional description for the exposed API. 130 * 131 * @return The annotation value. 132 * @since 9.2.0 133 */ 134 String[] description() default {}; 135 136 /** 137 * Short, concise summary of the exposed API. 138 * 139 * <p> 140 * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation, 141 * or any context where brevity matters. See {@link Schema#summary()} 142 * for the canonical definition. 143 * 144 * @return The annotation value. 145 * @since 10.0.0 146 */ 147 String summary() default ""; 148 149 /** 150 * FORM parameter name. 151 * 152 * <p> 153 * The name of the parameter (required). 154 * 155 * <p> 156 * The value should be either a valid form parameter name, or <js>"*"</js> to represent multiple name/value pairs 157 * 158 * <p> 159 * A blank value (the default) has the following behavior: 160 * <ul class='spaced-list'> 161 * <li> 162 * If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean, 163 * then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs. 164 * 165 * <h4 class='figure'>Examples:</h4> 166 * <p class='bjava'> 167 * <jc>// When used on a REST method</jc> 168 * <ja>@RestPost</ja>(<js>"/addPet"</js>) 169 * <jk>public void</jk> addPet(<ja>@FormData</ja> JsonMap <jv>allFormDataParameters</jv>) {...} 170 * </p> 171 * <p class='bjava'> 172 * <jc>// When used on a remote method parameter</jc> 173 * <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>) 174 * <jk>public interface</jk> MyProxy { 175 * 176 * <jc>// Equivalent to @FormData("*")</jc> 177 * <ja>@RemotePost</ja>(<js>"/mymethod"</js>) 178 * String myProxyMethod1(<ja>@FormData</ja> Map<String,Object> <jv>allFormDataParameters</jv>); 179 * } 180 * </p> 181 * <p class='bjava'> 182 * <jc>// When used on a request bean method</jc> 183 * <jk>public interface</jk> MyRequest { 184 * 185 * <jc>// Equivalent to @FormData("*")</jc> 186 * <ja>@FormData</ja> 187 * Map<String,Object> getFoo(); 188 * } 189 * </p> 190 * </li> 191 * <li> 192 * If used on a request bean method, uses the bean property name. 193 * 194 * <h4 class='figure'>Example:</h4> 195 * <p class='bjava'> 196 * <jk>public interface</jk> MyRequest { 197 * 198 * <jc>// Equivalent to @FormData("foo")</jc> 199 * <ja>@FormData</ja> 200 * String getFoo(); 201 * } 202 * </p> 203 * </li> 204 * </ul> 205 * 206 * <h4 class='section'>Notes:</h4><ul> 207 * <li class='note'> 208 * The format is plain-text. 209 * </ul> 210 * 211 * @return The annotation value. 212 */ 213 String name() default ""; 214 215 /** 216 * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>. 217 * 218 * <p> 219 * The schema defining the type used for parameter. 220 * 221 * <p> 222 * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type. 223 * Values specified on this field override values specified on the type, and values specified on child types override values 224 * specified on parent types. 225 * 226 * <h4 class='section'>Used for:</h4> 227 * <ul class='spaced-list'> 228 * <li> 229 * Server-side schema-based parsing and parsing validation. 230 * <li> 231 * Server-side generated Swagger documentation. 232 * <li> 233 * Client-side schema-based serializing and serializing validation. 234 * </ul> 235 * 236 * @return The annotation value. 237 */ 238 Schema schema() default @Schema; 239 240 /** 241 * A synonym for {@link #name()}. 242 * 243 * <p> 244 * Allows you to use shortened notation if you're only specifying the name. 245 * 246 * <p> 247 * The following are completely equivalent ways of defining a form post entry: 248 * <p class='bjava'> 249 * <jk>public</jk> Order placeOrder(<ja>@FormData</ja>(name=<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...} 250 * </p> 251 * <p class='bjava'> 252 * <jk>public</jk> Order placeOrder(<ja>@FormData</ja>(<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) {...} 253 * </p> 254 * 255 * @return The annotation value. 256 */ 257 String value() default ""; 258}