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