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 020/** 021 * REST has-form-data annotation. 022 * 023 * Identifies whether or not an HTTP request has the specified multipart form POST parameter. 024 * 025 * <p> 026 * Can be used in the following locations: 027 * <ul> 028 * <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods. 029 * </ul> 030 * <p> 031 * This annotation can be used to detect the existence of a parameter when it's not set to a particular value. 032 * </p> 033 * 034 * <h5 class='figure'>Example:</h5> 035 * <p class='bjava'> 036 * <ja>@RestPost</ja> 037 * <jk>public void</jk> doPost(<ja>@HasFormData</ja>(<js>"p1"</js>) <jk>boolean</jk> <jv>p1</jv>) {...} 038 * </p> 039 * <p> 040 * This is functionally equivalent to the following code: 041 * </p> 042 * <p class='bjava'> 043 * <ja>@RestPost</ja> 044 * <jk>public void</jk> doPost(RestRequest <jv>req</jv>) { 045 * <jk>boolean</jk> <jv>p1</jv> = <jv>req</jv>.getFormParam(<js>"p1"</js>).isPresent(); 046 * ... 047 * } 048 * </p> 049 * <p> 050 * The parameter type must be either <jk>boolean</jk> or {@link java.lang.Boolean}. 051 * </p> 052 * <p> 053 * The following table shows the behavioral differences between <ja>@HasFormData</ja> and <ja>@FormData</ja>: 054 * </p> 055 * <table class='styled w400'> 056 * <tr> 057 * <th><c>Body content</c></th> 058 * <th><c><ja>@HasFormData</ja>(<js>"a"</js>)</c></th> 059 * <th><c><ja>@FormData</ja>(<js>"a"</js>)</c></th> 060 * </tr> 061 * <tr> 062 * <td><c>a=foo</c></td> 063 * <td><jk>true</jk></td> 064 * <td><js>"foo"</js></td> 065 * </tr> 066 * <tr> 067 * <td><c>a=</c></td> 068 * <td><jk>true</jk></td> 069 * <td><js>""</js></td> 070 * </tr> 071 * <tr> 072 * <td><c>a</c></td> 073 * <td><jk>true</jk></td> 074 * <td><jk>null</jk></td> 075 * </tr> 076 * <tr> 077 * <td><c>b=foo</c></td> 078 * <td><jk>false</jk></td> 079 * <td><jk>null</jk></td> 080 * </tr> 081 * </table> 082 * 083 * <h5 class='topic'>Important note concerning FORM posts</h5> 084 * <p> 085 * This annotation should not be combined with the {@link Content @Content} annotation or {@code RestRequest.getContent()} method 086 * for <c>application/x-www-form-urlencoded POST</c> posts, since it will trigger the underlying servlet API to 087 * parse the body content as key-value pairs, resulting in empty content. 088 * </p> 089 * <p> 090 * The {@link HasQuery @HasQuery} annotation can be used to check for the existing of a URL parameter in the URL string 091 * without triggering the servlet to drain the body content. 092 * </p> 093 * 094 * <p> 095 * <h5 class='section'>See Also:</h5><ul> 096 097 * </ul> 098 */ 099@Documented 100@Target({PARAMETER}) 101@Retention(RUNTIME) 102@Inherited 103public @interface HasFormData { 104 105 /** 106 * FORM parameter name. 107 * 108 * Required. The name of the parameter. Parameter names are case sensitive. 109 * 110 * <h5 class='section'>Notes:</h5><ul> 111 * <li class='note'> 112 * The format is plain-text. 113 * </ul> 114 * 115 * @return The annotation value. 116 */ 117 String name() default ""; 118 119 /** 120 * A synonym for {@link #name()}. 121 * 122 * <p> 123 * Allows you to use shortened notation if you're only specifying the name. 124 * 125 * <p> 126 * The following are completely equivalent ways of defining the existence of a form post entry: 127 * <p class='bjava'> 128 * <jk>public</jk> Order placeOrder(<ja>@HasFormData</ja>(name=<js>"petId"</js>) <jk>boolean</jk> <jv>hasPetId</jv>) {...} 129 * </p> 130 * <p class='bjava'> 131 * <jk>public</jk> Order placeOrder(<ja>@HasFormData</ja>(<js>"petId"</js>) <jk>boolean</jk> <jv>hasPetId</jv>) {...} 132 * </p> 133 * 134 * @return The annotation value. 135 */ 136 String value() default ""; 137}