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