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.rest.client.remote; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.io.*; 019import java.lang.annotation.*; 020 021import org.apache.juneau.http.annotation.*; 022 023/** 024 * Annotation applied to Java methods on REST proxy. 025 * 026 * <h5 class='section'>See Also:</h5> 027 * <ul class='doctree'> 028 * <li class='link'>{@doc juneau-rest-client.RestProxies} 029 * </ul> 030 */ 031@Documented 032@Target(METHOD) 033@Retention(RUNTIME) 034@Inherited 035public @interface RemoteMethod { 036 037 /** 038 * REST service path. 039 * 040 * <p> 041 * The possible values are: 042 * <ul class='spaced-list'> 043 * <li>An absolute URL. 044 * <li>A relative URL interpreted as relative to the root URL defined on the <code>RestClient</code> and/or {@link RemoteResource#path()}. 045 * <li>No path. 046 * </ul> 047 * 048 * <p> 049 * If you do not specify a path, then the path is inferred from the Java method name. 050 * 051 * <h5 class='figure'>Example:</h5> 052 * <p class='bcode'> 053 * <jc>// POST /pet</jc> 054 * <ja>@RestMethod</ja> 055 * <jk>public void</jk> postPet(...) {...} 056 * </p> 057 */ 058 String path() default ""; 059 060 /** 061 * Defines the HTTP method to use for REST calls. 062 * 063 * <p> 064 * If not specified, then the method is inferred from the Java method name. 065 * 066 * <h5 class='figure'>Example:</h5> 067 * <p class='bcode'> 068 * <jc>// POST /pet</jc> 069 * <ja>@RestMethod</ja> 070 * <jk>public void</jk> postPet(...) {...} 071 * </p> 072 * 073 * <br>If the method cannot be inferred, then the default is <js>"GET"</js>. 074 */ 075 String method() default ""; 076 077 /** 078 * The value the remote method returns. 079 * 080 * <p> 081 * Possible values: 082 * <ul class='spaced-list'> 083 * <li> 084 * {@link RemoteReturn#BODY} (default) - The body of the HTTP response converted to a POJO. 085 * <br>The return type on the Java method can be any of the following: 086 * <ul class='spaced-list'> 087 * <li> 088 * <jk>void</jk> - Don't parse any response. Note that the method will still throw an exception if an 089 * error HTTP status is returned. 090 * <li> 091 * Any parsable POJO - The body of the response will be converted to the POJO using the parser defined 092 * on the <code>RestClient</code>. 093 * <li> 094 * Any POJO annotated with the {@link Response @Response} annotation. 095 * This allows for response beans to be used which also allows for OpenAPI-based parsing and validation. 096 * <li> 097 * <code>HttpResponse</code> - Returns the raw <code>HttpResponse</code> returned by the inner 098 * <code>HttpClient</code>. 099 * <li> 100 * {@link Reader} - Returns access to the raw reader of the response. 101 * <li> 102 * {@link InputStream} - Returns access to the raw input stream of the response. 103 * </ul> 104 * <li> 105 * {@link RemoteReturn#STATUS} - The HTTP status code on the response. 106 * <br>The return type on the Java method can be any of the following: 107 * <ul> 108 * <li><jk>int</jk>/<code>Integer</code> - The HTTP response code. 109 * <li><jk>boolean</jk>/<code>Boolean</code> - <jk>true</jk> if the response code is <code><400</code> 110 * </ul> 111 * </ul> 112 */ 113 RemoteReturn returns() default RemoteReturn.BODY; 114}