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 RemotePut {
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>@RemotePut</ja>
054    *    <jk>public void</jk> putPet(...);
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    * The value the remote method returns.
072    *
073    * <ul class='values'>
074    *    <li>
075    *       {@link RemoteReturn#BODY} (default) - The body of the HTTP response converted to a POJO.
076    *       <br>The return type on the Java method can be any of the following:
077    *       <ul class='spaced-list'>
078    *          <li>
079    *             <jk>void</jk> - Don't parse any response.  Note that the method will still throw an exception if an
080    *             error HTTP status is returned.
081    *          <li>
082    *             Any parsable POJO - The body of the response will be converted to the POJO using the parser defined
083    *             on the <c>RestClient</c>.
084    *          <li>
085    *             Any POJO annotated with the {@link Response @Response} annotation.
086    *             This allows for response beans to be used which also allows for OpenAPI-based parsing and validation.
087    *          <li>
088    *             <c>HttpResponse</c> - Returns the raw <c>HttpResponse</c> returned by the inner
089    *             <c>HttpClient</c>.
090    *          <li>
091    *             {@link Reader} - Returns access to the raw reader of the response.
092    *          <li>
093    *             {@link InputStream} - Returns access to the raw input stream of the response.
094    *       </ul>
095    *    <li>
096    *       {@link RemoteReturn#STATUS} - The HTTP status code on the response.
097    *       <br>The return type on the Java method can be any of the following:
098    *       <ul>
099    *          <li><jk>int</jk>/<c>Integer</c> - The HTTP response code.
100    *          <li><jk>boolean</jk>/<c>Boolean</c> - <jk>true</jk> if the response code is <c>&lt;400</c>
101    *       </ul>
102    * </ul>
103    *
104    * @return The annotation value.
105    */
106   RemoteReturn returns() default RemoteReturn.BODY;
107
108   /**
109    * REST path.
110    *
111    * <p>
112    * Can be used to provide a shortened form for the {@link #path()} value.
113    *
114    * <p>
115    * The following examples are considered equivalent.
116    * <p class='bjava'>
117    *    <jc>// Normal form</jc>
118    *    <ja>@RemotePut</ja>(path=<js>"/{propertyName}"</js>)
119    *
120    *    <jc>// Shortened form</jc>
121    *    <ja>@RemotePut</ja>(<js>"/{propertyName}"</js>)
122    * </p>
123    *
124    * @return The annotation value.
125    */
126   String value() default "";
127}