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.*; 021 022import java.lang.annotation.*; 023 024import org.apache.juneau.commons.*; 025 026/** 027 * REST request path remainder annotation. 028 * 029 * <p> 030 * Identifies a POJO to be used as the path remainder (the part after the path match) on an HTTP request. 031 * 032 * <p> 033 * This is a specialized shortcut for <c><ja>@Path</ja>(<js>"/*"</js>)</c>. 034 * 035 * <p> 036 * Can be used in the following locations: 037 * <ul> 038 * <li>Arguments and argument-types of server-side <ja>@RestOp</ja>-annotated methods. 039 * <li>Arguments and argument-types of client-side <ja>@RemoteResource</ja>-annotated interfaces. 040 * <li>Methods and return types of server-side and client-side <ja>@Request</ja>-annotated interfaces. 041 * </ul> 042 * 043 * <h2 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h2> 044 * <p> 045 * Annotation that can be applied to a parameter of a <ja>@RestOp</ja>-annotated method to identify it as the 046 * path remainder after the path pattern match. 047 * 048 * <h2 class='section'>Example:</h2> 049 * <p class='bjava'> 050 * <ja>@RestGet</ja>(<js>"/myurl/{foo}/{bar}/*"</js>) 051 * <jk>public void</jk> doGet( 052 * <ja>@Path</ja>(<js>"foo"</js>) String <jv>foo</jv>, 053 * <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> <jv>bar</jv>, 054 * <ja>@PathRemainder</ja> String <jv>remainder</jv>, <jc>// Equivalent to @Path("/*")</jc> 055 * ) {...} 056 * </p> 057 * 058 * <p> 059 * This is functionally equivalent to using <c><ja>@Path</ja>(<js>"/*"</js>)</c>, but provides a more intuitive name. 060 * 061 * <h2 class='section'>See Also:</h2><ul> 062 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Path">@Path</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 represent the path remainder on the request. 068 * 069 * <h2 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h2> 070 * <h2 class='section'>See Also:</h2><ul> 071 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a> 072 * </ul> 073 * 074 * <h2 class='section'>See Also:</h2><ul> 075 * <li class='ja'>{@link Path} 076 * </ul> 077 * 078 * @since 9.2.0 079 */ 080@Documented 081@Target({ PARAMETER, METHOD, TYPE, FIELD }) 082@Retention(RUNTIME) 083@Inherited 084public @interface PathRemainder { 085 086 /** 087 * Default value for this parameter. 088 * 089 * @return The annotation value. 090 */ 091 String def() default ""; 092 093 /** 094 * Optional description for the exposed API. 095 * 096 * @return The annotation value. 097 */ 098 String[] description() default {}; 099 100 /** 101 * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>. 102 * 103 * <p> 104 * The schema defining the type used for parameter. 105 * 106 * <p> 107 * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type. 108 * Values specified on this field override values specified on the type, and values specified on child types override values 109 * specified on parent types. 110 * 111 * <h4 class='section'>Used for:</h4> 112 * <ul class='spaced-list'> 113 * <li> 114 * Server-side schema-based parsing and parsing validation. 115 * <li> 116 * Server-side generated Swagger documentation. 117 * <li> 118 * Client-side schema-based serializing and serializing validation. 119 * </ul> 120 * 121 * @return The annotation value. 122 */ 123 Schema schema() default @Schema; 124 125}