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    * Request attribute name.
064    *
065    * <p>
066    * The value should be either a valid attribute name, or <js>"*"</js> to represent multiple name/value pairs
067    *
068    * <p>
069    * A blank value (the default) has the following behavior:
070    * <ul class='spaced-list'>
071    *    <li>
072    *       If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean,
073    *       then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs.
074    *
075    *       <h5 class='figure'>Examples:</h5>
076    *       <p class='bjava'>
077    *    <ja>@RestPost</ja>(<js>"/addPet"</js>)
078    *    <jk>public void</jk> addPet(<ja>@Attr</ja> JsonMap <jv>allAttributes</jv>) {...}
079    *       </p>
080    *    </li>
081    * </ul>
082    *
083    * @return The annotation value.
084    */
085   String name() default "";
086
087   /**
088    * Specifies the {@link HttpPartParser} class used for parsing strings to values.
089    *
090    * <p>
091    * Overrides for this part the part parser defined on the REST resource which by default is {@link OpenApiParser}.
092    *
093    * @return The annotation value.
094    */
095   Class<? extends HttpPartParser> parser() default HttpPartParser.Void.class;
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}