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.*;
021import static org.apache.juneau.marshall.Constants.*;
022
023import java.lang.annotation.*;
024
025import org.apache.juneau.commons.*;
026
027/**
028 * REST request path annotation.
029 *
030 * <p>
031 * Identifies a POJO to be used as a path entry on an HTTP request.
032 *
033 * <p>
034 * Can be used in the following locations:
035 * <ul>
036 *    <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods.
037 *    <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces.
038 *    <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces.
039 * </ul>
040 *
041 * <h2 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h2>
042 * <p>
043 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as a variable
044 * in a URL path pattern.
045 *
046 * <h2 class='section'>Example:</h2>
047 * <p class='bjava'>
048 *    <ja>@RestGet</ja>(<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
049 *    <jk>public void</jk> doGet(
050 *          <ja>@Path</ja>(<js>"foo"</js>) String <jv>foo</jv>,
051 *          <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> <jv>bar</jv>,
052 *          <ja>@Path</ja>(<js>"baz"</js>) UUID <jv>baz</jv>,
053 *          <ja>@Path</ja>(<js>"/*"</js>) String <jv>remainder</jv>,
054 *       ) {...}
055 * </p>
056 *
057 * <p>
058 * The special name <js>"/*"</js> is used to retrieve the path remainder after the path match (i.e. the part that matches <js>"/*"</js>).
059 *
060 * <h2 class='section'>See Also:</h2><ul>
061 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
062 *    <li class='extlink'><a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>
063 * </ul>
064 *
065 * <h2 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h2>
066 * <p>
067 * Annotation applied to Java method arguments of interface proxies to denote that they are path variables on the request.
068 *
069 * <h2 class='section'>See Also:</h2><ul>
070 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Path">@Path</a>
071 * </ul>
072 *
073 * <h2 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h2>
074 * <h2 class='section'>See Also:</h2><ul>
075 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a>
076 * </ul>
077 *
078 */
079@Documented
080@Target({ PARAMETER, METHOD, TYPE, FIELD })
081@Retention(RUNTIME)
082@Inherited
083public @interface Path {
084
085   /**
086    * Default value for this parameter.
087    *
088    * @return The annotation value.
089    */
090   String def() default NONE;
091
092   /**
093    * Optional description for the exposed API.
094    *
095    * @return The annotation value.
096    * @since 9.2.0
097    */
098   String[] description() default {};
099
100   /**
101    * Short, concise summary of the exposed API.
102    *
103    * <p>
104    * Intended as a brief, single-line description suitable for AI/LLM consumption, compact documentation,
105    * or any context where brevity matters. See {@link Schema#summary()}
106    * for the canonical definition.
107    *
108    * @return The annotation value.
109    * @since 10.0.0
110    */
111   String summary() default "";
112
113   /**
114    * URL path variable name.
115    *
116    * <p>
117    * The path remainder after the path match can be referenced using the name <js>"/*"</js>.
118    * <br>The non-URL-decoded path remainder after the path match can be referenced using the name <js>"/**"</js>.
119    *
120    * <p>
121    * The value should be either a valid path parameter name, or <js>"*"</js> to represent multiple name/value pairs
122    *
123    * <p>
124    * A blank value (the default) has the following behavior:
125    * <ul class='spaced-list'>
126    *    <li>
127    *       If the data type is <c>NameValuePairs</c>, <c>Map</c>, or a bean,
128    *       then it's the equivalent to <js>"*"</js> which will cause the value to be treated as name/value pairs.
129    *
130    *       <h4 class='figure'>Examples:</h4>
131    *       <p class='bjava'>
132    *    <jc>// When used on a REST method</jc>
133    *    <ja>@RestPost</ja>
134    *    <jk>public void</jk> addPet(<ja>@Path</ja> JsonMap <jv>allPathParameters</jv>) {...}
135    *       </p>
136    *       <p class='bjava'>
137    *    <jc>// When used on a remote method parameter</jc>
138    *    <ja>@RemoteResource</ja>(path=<js>"/myproxy"</js>)
139    *    <jk>public interface</jk> MyProxy {
140    *
141    *       <jc>// Equivalent to @Path("*")</jc>
142    *       <ja>@RemoteGet</ja>(<js>"/mymethod/{foo}/{bar}"</js>)
143    *       String myProxyMethod1(<ja>@Path</ja> Map&lt;String,Object&gt; <jv>allPathParameters</jv>);
144    *    }
145    *       </p>
146    *       <p class='bjava'>
147    *    <jc>// When used on a request bean method</jc>
148    *    <jk>public interface</jk> MyRequest {
149    *
150    *       <jc>// Equivalent to @Path("*")</jc>
151    *       <ja>@Path</ja>
152    *       Map&lt;String,Object&gt; getPathVars();
153    *    }
154    *       </p>
155    *    </li>
156    *    <li>
157    *       If used on a request bean method, uses the bean property name.
158    *
159    *       <h4 class='figure'>Example:</h4>
160    *       <p class='bjava'>
161    *    <jk>public interface</jk> MyRequest {
162    *
163    *       <jc>// Equivalent to @Path("foo")</jc>
164    *       <ja>@Path</ja>
165    *       String getFoo();
166    *    }
167    * </ul>
168    *
169    * <p>
170    * The name field MUST correspond to the associated <a class="doclink" href="https://swagger.io/specification/v2#pathsPath">path</a> segment from the path field in the <a class="doclink" href="https://swagger.io/specification/v2#pathsObject">Paths Object</a>.
171    * See <a class="doclink" href="https://swagger.io/specification/v2#pathTemplating">Path Templating</a> for further information.
172    *
173    * <h4 class='section'>Notes:</h4><ul>
174    *    <li class='note'>
175    *       The format is plain-text.
176    * </ul>
177    *
178    * @return The annotation value.
179    */
180   String name() default "";
181
182   /**
183    * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>.
184    *
185    * <p>
186    * The schema defining the type used for parameter.
187    *
188    * <p>
189    * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type.
190    * Values specified on this field override values specified on the type, and values specified on child types override values
191    * specified on parent types.
192    *
193    * <h4 class='section'>Used for:</h4>
194    * <ul class='spaced-list'>
195    *    <li>
196    *       Server-side schema-based parsing and parsing validation.
197    *    <li>
198    *       Server-side generated Swagger documentation.
199    *    <li>
200    *       Client-side schema-based serializing and serializing validation.
201    * </ul>
202    *
203    * @return The annotation value.
204    */
205   Schema schema() default @Schema;
206
207   /**
208    * A synonym for {@link #name()}.
209    *
210    * <p>
211    * Allows you to use shortened notation if you're only specifying the name.
212    *
213    * <p>
214    * The following are completely equivalent ways of defining a path entry:
215    * <p class='bjava'>
216    *    <ja>@RestGet</ja>(<js>"/pet/{petId}"</js>)
217    *    <jk>public</jk> Pet getPet(<ja>@Path</ja>(name=<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) { ... }
218    * </p>
219    * <p class='bjava'>
220    *    <ja>@RestGet</ja>(<js>"/pet/{petId}"</js>)
221    *    <jk>public</jk> Pet getPet(<ja>@Path</ja>(<js>"petId"</js>) <jk>long</jk> <jv>petId</jv>) { ... }
222    * </p>
223    *
224    * @return The annotation value.
225    */
226   String value() default "";
227}