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.oapi.*;
022
023/**
024 * REST request attribute annotation.
025 *
026 * <p>
027 * Identifies a POJO retrieved from the request attributes map.
028 *
029 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as a value
030 * retrieved from the request attributes.
031 *
032 * <h5 class='section'>Example:</h5>
033 * <p class='bjava'>
034 *    <ja>@RestGet</ja>
035 *    <jk>public</jk> Person getPerson(<ja>@Attr</ja>(<js>"ETag"</js>) UUID <jv>etag</jv>) {...}
036 * </p>
037 *
038 * <p>
039 * This is functionally equivalent to the following code...
040 * <p class='bjava'>
041 *    <ja>@RestPost</ja>
042 *    <jk>public void</jk> postPerson(RestRequest <jv>req</jv>, RestResponse <jv>res</jv>) {
043 *       UUID <jv>etag</jv> = <jv>req</jv>.getAttributes().get(UUID.<jk>class</jk>, <js>"ETag"</js>);
044 *       ...
045 *    }
046 * </p>
047  *
048 * <h5 class='section'>See Also:</h5><ul>
049 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.JavaMethodParameters">Java Method Parameters</a>
050
051 * </ul>
052 */
053@Target({PARAMETER,TYPE})
054@Retention(RUNTIME)
055@Inherited
056public @interface Attr {
057
058   /**
059    * Specifies the {@link HttpPartParser} class used for parsing strings to values.
060    *
061    * <p>
062    * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}.
063    *
064    * @return The annotation value.
065    */
066   Class<? extends HttpPartParser> parser() default HttpPartParser.Void.class;
067
068   //=================================================================================================================
069   // Attributes common to all Swagger Parameter objects
070   //=================================================================================================================
071
072   /**
073    * Request attribute name.
074    *
075    * <p>
076    * The value should be either a valid attribute name, or <js>"*"</js> to represent multiple name/value pairs
077    *
078    * <p>
079    * A blank value (the default) has the following behavior:
080    * <ul class='spaced-list'>
081    *    <li>
082    *       If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean,
083    *       then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs.
084    *
085    *       <h5 class='figure'>Examples:</h5>
086    *       <p class='bjava'>
087    *    <ja>@RestPost</ja>(<js>"/addPet"</js>)
088    *    <jk>public void</jk> addPet(<ja>@Attr</ja> JsonMap <jv>allAttributes</jv>) {...}
089    *       </p>
090    *    </li>
091    * </ul>
092    *
093    * @return The annotation value.
094    */
095   String name() default "";
096
097   /**
098    * A synonym for {@link #name()}.
099    *
100    * <p>
101    * Allows you to use shortened notation if you're only specifying the name.
102    *
103    * <p>
104    * The following are completely equivalent ways of defining a header entry:
105    * <p class='bjava'>
106    *    <jk>public</jk> Order placeOrder(<ja>@Attr</ja>(name=<js>"api_key"</js>) String <jv>apiKey</jv>) {...}
107    * </p>
108    * <p class='bjava'>
109    *    <jk>public</jk> Order placeOrder(<ja>@Attr</ja>(<js>"api_key"</js>) String <jv>apiKey</jv>) {...}
110    * </p>
111    *
112    * @return The annotation value.
113    */
114   String value() default "";
115}