001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.remoteable; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.httppart.*; 021import org.apache.juneau.urlencoding.*; 022 023/** 024 * Annotation applied to Java method arguments of interface proxies to denote that they are path variables on the request. 025 * 026 * <h5 class='section'>Example:</h5> 027 * <p class='bcode'> 028 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 029 * <jk>public interface</jk> MyProxy { 030 * 031 * <jc>// Explicit names specified for path parameters.</jc> 032 * <jc>// pojo will be converted to UON notation (unless plain-text parts enabled).</jc> 033 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod1/{foo}/{bar}"</js>) 034 * String myProxyMethod1(<ja>@Path</ja>(<js>"foo"</js>)</ja> String foo, <ja>@Path</ja>(<js>"bar"</js>)</ja> MyPojo pojo); 035 * 036 * <jc>// Multiple values pulled from a NameValuePairs object.</jc> 037 * <jc>// Same as @Path("*").</jc> 038 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod2/{foo}/{bar}/{baz}"</js>) 039 * String myProxyMethod2(<ja>@Path</ja> NameValuePairs nameValuePairs); 040 * 041 * <jc>// Multiple values pulled from a Map.</jc> 042 * <jc>// Same as @Path("*").</jc> 043 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod3/{foo}/{bar}/{baz}"</js>) 044 * String myProxyMethod3(<ja>@Path</ja> Map<String,Object> map); 045 * 046 * <jc>// Multiple values pulled from a bean.</jc> 047 * <jc>// Same as @Path("*").</jc> 048 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod4/{foo}/{bar}/{baz}"</js>) 049 * String myProxyMethod4(<ja>@Path</ja> MyBean myBean); 050 * } 051 * </p> 052 * 053 * <p> 054 * The annotation can also be applied to a bean property field or getter when the argument is annotated with 055 * {@link RequestBean @RequestBean}: 056 * 057 * <h5 class='section'>Example:</h5> 058 * <p class='bcode'> 059 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 060 * <jk>public interface</jk> MyProxy { 061 * 062 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod/{foo}/{bar}/{baz}"</js>) 063 * String myProxyMethod(<ja>@RequestBean</ja> MyRequestBean bean); 064 * } 065 * 066 * <jk>public interface</jk> MyRequestBean { 067 * 068 * <jc>// Name explicitly specified.</jc> 069 * <ja>@Path</ja>(<js>"foo"</js>) 070 * String getX(); 071 * 072 * <jc>// Name inherited from bean property.</jc> 073 * <jc>// Same as @Path("bar")</jc> 074 * <ja>@Path</ja> 075 * String getBar(); 076 * 077 * <jc>// Name inherited from bean property.</jc> 078 * <jc>// Same as @Path("baz")</jc> 079 * <ja>@Path</ja> 080 * <ja>@BeanProperty</ja>(<js>"baz"</js>) 081 * String getY(); 082 * 083 * <jc>// Multiple values pulled from NameValuePairs object.</jc> 084 * <jc>// Same as @Path("*")</jc> 085 * <ja>@Path</ja> 086 * NameValuePairs getNameValuePairs(); 087 * 088 * <jc>// Multiple values pulled from Map.</jc> 089 * <jc>// Same as @Path("*")</jc> 090 * <ja>@Path</ja> 091 * Map<String,Object> getMap(); 092 * 093 * <jc>// Multiple values pulled from bean.</jc> 094 * <jc>// Same as @Path("*")</jc> 095 * <ja>@Path</ja> 096 * MyBean getMyBean(); 097 * } 098 * </p> 099 * 100 * <p> 101 * The {@link #name()} and {@link #value()} elements are synonyms for specifying the path variable name. 102 * Only one should be used. 103 * <br>The following annotations are fully equivalent: 104 * <p class='bcode'> 105 * <ja>@Path</ja>(name=<js>"foo"</js>) 106 * 107 * <ja>@Path</ja>(<js>"foo"</js>) 108 * </p> 109 * 110 * <h5 class='section'>See Also:</h5> 111 * <ul class='doctree'> 112 * <li class='link'><a class='doclink' href='../../../../overview-summary.html#juneau-rest-client.3rdPartyProxies'>Overview > juneau-rest-client > Interface Proxies Against 3rd-party REST Interfaces</a> 113 * </ul> 114 */ 115@Documented 116@Target({PARAMETER,FIELD,METHOD}) 117@Retention(RUNTIME) 118@Inherited 119public @interface Path { 120 121 /** 122 * The path parameter name. 123 * 124 * <p> 125 * Note that {@link #name()} and {@link #value()} are synonyms. 126 * 127 * <p> 128 * The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the 129 * path variable name. 130 * 131 * <p> 132 * A blank value (the default) has the following behavior: 133 * <ul class='spaced-list'> 134 * <li> 135 * If the data type is <code>NameValuePairs</code>, <code>Map</code>, or a bean, 136 * then it's the equivalent to <js>"*"</js> which will cause the value to be treated as name/value pairs. 137 * 138 * <h5 class='figure'>Example:</h5> 139 * <p class='bcode'> 140 * <jc>// When used on a remote method parameter</jc> 141 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 142 * <jk>public interface</jk> MyProxy { 143 * 144 * <jc>// Equivalent to @Path("*")</jc> 145 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod/{foo}/{bar}"</js>) 146 * String myProxyMethod1(<ja>@FormData</ja> Map<String,Object> pathVars); 147 * } 148 * 149 * <jc>// When used on a request bean method</jc> 150 * <jk>public interface</jk> MyRequestBean { 151 * 152 * <jc>// Equivalent to @Path("*")</jc> 153 * <ja>@Path</ja> 154 * Map<String,Object> getPathVars(); 155 * } 156 * </p> 157 * </li> 158 * <li> 159 * If used on a request bean method, uses the bean property name. 160 * 161 * <h5 class='figure'>Example:</h5> 162 * <p class='bcode'> 163 * <jk>public interface</jk> MyRequestBean { 164 * 165 * <jc>// Equivalent to @Path("foo")</jc> 166 * <ja>@Path</ja> 167 * String getFoo(); 168 * } 169 * </ul> 170 */ 171 String name() default ""; 172 173 /** 174 * A synonym for {@link #name()}. 175 * 176 * <p> 177 * Allows you to use shortened notation if you're only specifying the name. 178 */ 179 String value() default ""; 180 181 /** 182 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 183 * 184 * <p> 185 * The default value defaults to the using the part serializer defined on the {@link RequestBean @RequestBean} annotation, 186 * then on the client which by default is {@link UrlEncodingSerializer}. 187 * 188 * <p> 189 * This annotation is provided to allow values to be custom serialized. 190 */ 191 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Null.class; 192}