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 serialized as an HTTP 025 * header value. 026 * 027 * <h5 class='section'>Example:</h5> 028 * <p class='bcode'> 029 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 030 * <jk>public interface</jk> MyProxy { 031 * 032 * <jc>// Explicit names specified for HTTP headers.</jc> 033 * <jc>// pojo will be converted to UON notation (unless plain-text parts enabled).</jc> 034 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod1"</js>) 035 * String myProxyMethod1(<ja>@Header</ja>(<js>"Foo"</js>)</ja> String foo, 036 * <ja>@Header</ja>(<js>"Bar"</js>)</ja> MyPojo pojo); 037 * 038 * <jc>// Multiple values pulled from a NameValuePairs object.</jc> 039 * <jc>// Same as @Header("*").</jc> 040 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod2"</js>) 041 * String myProxyMethod2(<ja>@Header</ja> NameValuePairs nameValuePairs); 042 * 043 * <jc>// Multiple values pulled from a Map.</jc> 044 * <jc>// Same as @Header("*").</jc> 045 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod3"</js>) 046 * String myProxyMethod3(<ja>@Header</ja> Map<String,Object> map); 047 * 048 * <jc>// Multiple values pulled from a bean.</jc> 049 * <jc>// Same as @Header("*").</jc> 050 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod4"</js>) 051 * String myProxyMethod4(<ja>@Header</ja> MyBean myBean); 052 * } 053 * </p> 054 * 055 * <p> 056 * The annotation can also be applied to a bean property field or getter when the argument is annotated with 057 * {@link RequestBean @RequestBean}: 058 * 059 * <h5 class='section'>Example:</h5> 060 * <p class='bcode'> 061 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 062 * <jk>public interface</jk> MyProxy { 063 * 064 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>) 065 * String myProxyMethod(<ja>@RequestBean</ja> MyRequestBean bean); 066 * } 067 * 068 * <jk>public interface</jk> MyRequestBean { 069 * 070 * <jc>// Name explicitly specified.</jc> 071 * <ja>@Header</ja>(<js>"Foo"</js>) 072 * String getX(); 073 * 074 * <jc>// Name inherited from bean property.</jc> 075 * <jc>// Same as @Header("bar")</jc> 076 * <ja>@Header</ja> 077 * String getBar(); 078 * 079 * <jc>// Name inherited from bean property.</jc> 080 * <jc>// Same as @Header("Baz")</jc> 081 * <ja>@Header</ja> 082 * <ja>@BeanProperty</ja>(<js>"Baz"</js>) 083 * String getY(); 084 * 085 * <jc>// Multiple values pulled from NameValuePairs object.</jc> 086 * <jc>// Same as @Header("*")</jc> 087 * <ja>@Header</ja> 088 * NameValuePairs getNameValuePairs(); 089 * 090 * <jc>// Multiple values pulled from Map.</jc> 091 * <jc>// Same as @Header("*")</jc> 092 * <ja>@Header</ja> 093 * Map<String,Object> getMap(); 094 * 095 * <jc>// Multiple values pulled from bean.</jc> 096 * <jc>// Same as @Header("*")</jc> 097 * <ja>@Header</ja> 098 * MyBean getBean(); 099 * } 100 * </p> 101 * 102 * <p> 103 * The {@link #name()} and {@link #value()} elements are synonyms for specifying the header name. 104 * Only one should be used. 105 * <br>The following annotations are fully equivalent: 106 * <p class='bcode'> 107 * <ja>@Header</ja>(name=<js>"Foo"</js>) 108 * 109 * <ja>@Header</ja>(<js>"Foo"</js>) 110 * </p> 111 * 112 * <h5 class='section'>See Also:</h5> 113 * <ul class='doctree'> 114 * <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> 115 * </ul> 116 */ 117@Documented 118@Target({PARAMETER,FIELD,METHOD}) 119@Retention(RUNTIME) 120@Inherited 121public @interface Header { 122 123 /** 124 * The HTTP header name. 125 * 126 * <p> 127 * A blank value (the default) indicates to reuse the bean property name when used on a request bean property. 128 * 129 * <p> 130 * The value should be either <js>"*"</js> to represent multiple name/value pairs, or a label that defines the 131 * header name. 132 * 133 * <p> 134 * A blank value (the default) has the following behavior: 135 * <ul class='spaced-list'> 136 * <li> 137 * If the data type is <code>NameValuePairs</code>, <code>Map</code>, or a bean, 138 * then it's the equivalent to <js>"*"</js> which will cause the value to be serialized as name/value pairs. 139 * 140 * <h5 class='figure'>Example:</h5> 141 * <p class='bcode'> 142 * <jc>// When used on a remote method parameter</jc> 143 * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>) 144 * <jk>public interface</jk> MyProxy { 145 * 146 * <jc>// Equivalent to @Header("*")</jc> 147 * <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>) 148 * String myProxyMethod1(<ja>@Header</ja> Map<String,Object> headers); 149 * } 150 * 151 * <jc>// When used on a request bean method</jc> 152 * <jk>public interface</jk> MyRequestBean { 153 * 154 * <jc>// Equivalent to @Header("*")</jc> 155 * <ja>@Header</ja> 156 * Map<String,Object> getFoo(); 157 * } 158 * </p> 159 * </li> 160 * <li> 161 * If used on a request bean method, uses the bean property name. 162 * 163 * <h5 class='figure'>Example:</h5> 164 * <p class='bcode'> 165 * <jk>public interface</jk> MyRequestBean { 166 * 167 * <jc>// Equivalent to @Header("Foo")</jc> 168 * <ja>@Header</ja> 169 * <ja>@BeanProperty</ja>(<js>"Foo"</js>) 170 * String getFoo(); 171 * } 172 * </p> 173 * </li> 174 * </ul> 175 */ 176 String name() default ""; 177 178 /** 179 * A synonym for {@link #name()}. 180 * 181 * <p> 182 * Allows you to use shortened notation if you're only specifying the name. 183 */ 184 String value() default ""; 185 186 /** 187 * Skips this value if it's an empty string or empty collection/array. 188 * 189 * <p> 190 * Note that <jk>null</jk> values are already ignored. 191 */ 192 boolean skipIfEmpty() default false; 193 194 /** 195 * Specifies the {@link HttpPartSerializer} class used for serializing values to strings. 196 * 197 * <p> 198 * The default value defaults to the using the part serializer defined on the {@link RequestBean @RequestBean} annotation, 199 * then on the client which by default is {@link UrlEncodingSerializer}. 200 * 201 * <p> 202 * This annotation is provided to allow values to be custom serialized. 203 */ 204 Class<? extends HttpPartSerializer> serializer() default HttpPartSerializer.Null.class; 205}