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.http.remote; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.http.*; 021 022/** 023 * Identifies a proxy against a REST interface. 024 * 025 * <ul class='seealso'> 026 * <li class='link'>{@doc RestcProxies} 027 * </ul> 028 */ 029@Documented 030@Target({TYPE}) 031@Retention(RUNTIME) 032@Inherited 033public @interface Remote { 034 035 /** 036 * REST service path. 037 * 038 * <p> 039 * The possible values are: 040 * <ul class='spaced-list'> 041 * <li>An absolute URL. 042 * <li>A relative URL interpreted as relative to the root URL defined on the <c>RestClient</c> 043 * <li>No path interpreted as the class name (e.g. <js>"http://localhost/root-url/org.foo.MyInterface"</js>) 044 * </ul> 045 * 046 * <ul class='notes'> 047 * <li> 048 * Supports {@doc DefaultVarResolver} 049 * (e.g. <js>"$P{mySystemProperty}"</js>). 050 * </ul> 051 */ 052 String path() default ""; 053 054 /** 055 * Default request headers. 056 * 057 * <p> 058 * Specifies headers to set on all requests. 059 * 060 * <ul class='notes'> 061 * <li> 062 * Supports {@doc DefaultVarResolver} 063 * (e.g. <js>"$P{mySystemProperty}"</js>). 064 * </ul> 065 */ 066 String[] headers() default {}; 067 068 /** 069 * Default request header supplier. 070 * 071 * <p> 072 * Specifies a dynamic supplier of headers to set on all requests. 073 * 074 * <ul class='notes'> 075 * <li> 076 * Supplier class must provide a public no-arg constructor. 077 * </ul> 078 */ 079 Class<? extends HeaderSupplier> headerSupplier() default HeaderSupplier.Null.class; 080 081 /** 082 * Specifies the client version of this interface. 083 * 084 * <p> 085 * Used to populate the <js>"X-Client-Version"</js> header that identifies what version of client this is 086 * so that the server side can handle older versions accordingly. 087 * 088 * <p> 089 * The format of this is a string of the format <c>#[.#[.#[...]]</c> (e.g. <js>"1.2.3"</js>). 090 * 091 * <p> 092 * The server side then uses an OSGi-version matching pattern to identify which methods to call: 093 * <p class='bcode w800'> 094 * <jc>// Call this method if X-Client-Version is at least 2.0. 095 * // Note that this also matches 2.0.1.</jc> 096 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"2.0"</js>) 097 * <jk>public</jk> Object method1() {...} 098 * 099 * <jc>// Call this method if X-Client-Version is at least 1.1, but less than 2.0.</jc> 100 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[1.1,2.0)"</js>) 101 * <jk>public</jk> Object method2() {...} 102 * 103 * <jc>// Call this method if X-Client-Version is less than 1.1.</jc> 104 * <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/foobar"</js>, clientVersion=<js>"[0,1.1)"</js>) 105 * <jk>public</jk> Object method3() {...} 106 * </p> 107 * 108 * <ul class='notes'> 109 * <li> 110 * Supports {@doc DefaultVarResolver} 111 * (e.g. <js>"$P{mySystemProperty}"</js>). 112 * </ul> 113 */ 114 String version() default ""; 115 116 /** 117 * Specifies the client version header name. 118 * 119 * <p> 120 * The default value is <js>"X-Client-Version"</js>. 121 * 122 * <ul class='notes'> 123 * <li> 124 * Supports {@doc DefaultVarResolver} 125 * (e.g. <js>"$P{mySystemProperty}"</js>). 126 * </ul> 127 */ 128 String versionHeader() default ""; 129}