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