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.remote;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.io.*;
023import java.lang.annotation.*;
024
025import org.apache.juneau.annotation.*;
026import org.apache.juneau.http.annotation.*;
027
028/**
029 * Annotation applied to Java methods on REST proxy interface classes.
030 *
031 * <p>
032 * Note that this annotation is optional if you do not need to override any of the values.
033 *
034 * <h5 class='section'>See Also:</h5><ul>
035 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestProxyBasics">REST Proxy Basics</a>
036 * </ul>
037 */
038@Documented
039@Target(METHOD)
040@Retention(RUNTIME)
041@Inherited
042@AnnotationGroup(RemoteOp.class)
043public @interface RemoteOp {
044
045   /**
046    * REST service path.
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='bjava'>
053    *    <ja>@RemotePost</ja>
054    *    <jk>public void</jk> postPet(...);
055    * </p>
056    *
057    * <p>
058    * Note that you can also use {@link #value()} to specify the method name and path in shortened form.
059    *
060    * <ul class='values'>
061    *    <li>An absolute URL.
062    *    <li>A relative URL interpreted as relative to the root URL defined on the <c>RestClient</c> and/or {@link Remote#path()}.
063    *    <li>No path.
064    * </ul>
065    *
066    * @return The annotation value.
067    */
068   String path() default "";
069
070   /**
071    * Defines the HTTP method to use for REST calls.
072    *
073    * <p>
074    * If not specified, then the method is inferred from the Java method name.
075    *
076    * <h5 class='figure'>Example:</h5>
077    * <p class='bjava'>
078    *    <ja>@RemotePost</ja>
079    *    <jk>public void</jk> postPet(...);
080    * </p>
081    *
082    * <br>If the method cannot be inferred, then the default is <js>"GET"</js>.
083    *
084    * <p>
085    * Note that you can also use {@link #value()} to specify the method name and path in shortened form.
086    *
087    * @return The annotation value.
088    */
089   String method() default "";
090
091   /**
092    * The value the remote method returns.
093    *
094    * <ul class='values'>
095    *    <li>
096    *       {@link RemoteReturn#BODY} (default) - The body of the HTTP response converted to a POJO.
097    *       <br>The return type on the Java method can be any of the following:
098    *       <ul class='spaced-list'>
099    *          <li>
100    *             <jk>void</jk> - Don't parse any response.  Note that the method will still throw an exception if an
101    *             error HTTP status is returned.
102    *          <li>
103    *             Any parsable POJO - The body of the response will be converted to the POJO using the parser defined
104    *             on the <c>RestClient</c>.
105    *          <li>
106    *             Any POJO annotated with the {@link Response @Response} annotation.
107    *             This allows for response beans to be used which also allows for OpenAPI-based parsing and validation.
108    *          <li>
109    *             <c>HttpResponse</c> - Returns the raw <c>HttpResponse</c> returned by the inner
110    *             <c>HttpClient</c>.
111    *          <li>
112    *             {@link Reader} - Returns access to the raw reader of the response.
113    *          <li>
114    *             {@link InputStream} - Returns access to the raw input stream of the response.
115    *       </ul>
116    *    <li>
117    *       {@link RemoteReturn#STATUS} - The HTTP status code on the response.
118    *       <br>The return type on the Java method can be any of the following:
119    *       <ul>
120    *          <li><jk>int</jk>/<c>Integer</c> - The HTTP response code.
121    *          <li><jk>boolean</jk>/<c>Boolean</c> - <jk>true</jk> if the response code is <c>&lt;400</c>
122    *       </ul>
123    * </ul>
124    *
125    * @return The annotation value.
126    */
127   RemoteReturn returns() default RemoteReturn.BODY;
128
129   /**
130    * REST method name and path.
131    *
132    * <p>
133    * Can be used to provide a shortened combined form for the {@link #method()} and {@link #path()} values.
134    *
135    * <p>
136    * The following examples are considered equivalent.
137    * <p class='bjava'>
138    *    <jc>// Normal form</jc>
139    *    <ja>@RemoteOp</ja>(method=<jsf>PUT</jsf>, path=<js>"/{propertyName}"</js>)
140    *
141    *    <jc>// Shortened form</jc>
142    *    <ja>@RemoteOp</ja>(<js>"PUT /{propertyName}"</js>)
143    * </p>
144    *
145    * <h5 class='section'>Notes:</h5><ul>
146    *    <li class='note'>
147    *       The path portion is optional.
148    * </ul>
149    *
150    * @return The annotation value.
151    */
152   String value() default "";
153}