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<String,Object> <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<String,Object> 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}