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 * <h5 class='topic'>Arguments and argument-types of server-side @RestOp-annotated methods</h5>
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 * <h5 class='section'>Example:</h5>
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 * <h5 class='section'>See Also:</h5><ul>
062 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Path">@Path</a>
063 * </ul>
064 *
065 * <h5 class='topic'>Arguments and argument-types of client-side @RemoteResource-annotated interfaces</h5>
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 * <h5 class='section'>See Also:</h5><ul>
070 * </ul>
071 *
072 * <h5 class='topic'>Methods and return types of server-side and client-side @Request-annotated interfaces</h5>
073 * <p>
074 * <h5 class='section'>See Also:</h5><ul>
075 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Request">@Request</a>
076 * </ul>
077 *
078 * <h5 class='section'>See Also:</h5><ul>
079 *    <li class='ja'>{@link Path}
080 * </ul>
081 *
082 * @since 9.2.0
083 */
084@Documented
085@Target({ PARAMETER, METHOD, TYPE, FIELD })
086@Retention(RUNTIME)
087@Inherited
088public @interface PathRemainder {
089
090   /**
091    * Default value for this parameter.
092    *
093    * @return The annotation value.
094    */
095   String def() default "";
096
097   /**
098    * Optional description for the exposed API.
099    *
100    * @return The annotation value.
101    */
102   String[] description() default {};
103
104   /**
105    * <mk>schema</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>.
106    *
107    * <p>
108    * The schema defining the type used for parameter.
109    *
110    * <p>
111    * The {@link Schema @Schema} annotation can also be used standalone on the parameter or type.
112    * Values specified on this field override values specified on the type, and values specified on child types override values
113    * specified on parent types.
114    *
115    * <h5 class='section'>Used for:</h5>
116    * <ul class='spaced-list'>
117    *    <li>
118    *       Server-side schema-based parsing and parsing validation.
119    *    <li>
120    *       Server-side generated Swagger documentation.
121    *    <li>
122    *       Client-side schema-based serializing and serializing validation.
123    * </ul>
124    *
125    * @return The annotation value.
126    */
127   Schema schema() default @Schema;
128
129}