juneau-doc/docs/Topics/09.juneau-rest-client/01.RestProxies/02.RemoteMethod.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

@RemoteMethod

<p>
	The {@link oaj.http.remote.RemoteMethod @RemoteMethod} annotation is applied to methods
	of <ja>@Remote</ja>-annotated interfaces to identify REST endpoints.
</p>
<ul class='javatree'>
	<li class='ja'>{@link oaj.http.remote.RemoteMethod}
	<ul>
		<li class='jf'>{@link oaj.http.remote.RemoteMethod#method method}
		<li class='jf'>{@link oaj.http.remote.RemoteMethod#path path}
		<li class='jf'>{@link oaj.http.remote.RemoteMethod#returns returns}
	</ul>
</ul>
<h5 class='topic'>@RemoteMethod(method/path)</h5>
<p>
	The HTTP method and path are mapped to a Java method using the <c>method</c> and <c>path</c> annotations.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>	
	<ja>@Remote</ja>
	<jk>public interface</jk> PetStore {
		
		<jc>// GET /pets/{petId}</jc>
		<ja>@RemoteMethod</ja>(method=<js>"GET"</js>, path=<js>"/pets/{petId}"</js>)
		Pet getPet(<ja>@Path</ja>(<js>"petId"</js>) <jk>int</jk> id);
	}
</p>
<p>
	The Java method name can be anything.  
</p>

<h5 class='topic'>Inferred method/path</h5>
<p>
	In such cases, <c>method</c> and <c>path</c> annotations are optional if you follow certain naming
	conventions on your method that identify the method and path.
</p>
<p>
	For example, the <c>getPet</c> method below defaults to <c>GET /pet</c>:
</p>
<p class='bpcode w800'>	
	<ja>@Remote</ja>
	<jk>public interface</jk> PetStore {
		
		<jc>// GET /pet</jc>
		<ja>@RemoteMethod</ja>
		Pet getPet(...);
	}
</p>
<p>
	In such cases, the <ja>@RemoteMethod</ja> annotation is optional.
</p>
<p>
	Method names matching the following pattern are assumed to be implying the HTTP method name:
</p>
<p class='bpcode w800'>
	(get|put|post|delete|options|head|connect|trace|patch).*
</p>
<p class='bpcode w800'>
	do(?i)(get|put|post|delete|options|head|connect|trace|patch)
</p>

<h5 class='figure'>Examples:</h5>
<table class='styled w500'>
	<tr>
		<th>Java method name</th>
		<th>Inferred HTTP method</th>
		<th>Inferred HTTP path</th>
	</tr>
	<tr>
		<td class='code'>getPet()</td>
		<td class='code'>GET</td>
		<td class='code'>/pet</td>
	</tr>
	<tr>
		<td class='code'>get()</td>
		<td class='code'>GET</td>
		<td class='code'>/</td>
	</tr>
	<tr>
		<td class='code'>postPet()</td>
		<td class='code'>POST</td>
		<td class='code'>/pet</td>
	</tr>
	<tr>
		<td class='code'>fooPet()</td>
		<td class='code'>[default]</td>
		<td class='code'>/fooPet</td>
	</tr>
	<tr>
		<td class='code'>doGet()</td>
		<td class='code'>GET</td>
		<td class='code'>/</td>
	</tr>
	<tr>
		<td class='code'>doGET()</td>
		<td class='code'>GET</td>
		<td class='code'>/</td>
	</tr>
	<tr>
		<td class='code'>doFoo()</td>
		<td class='code'>[default]</td>
		<td class='code'>/doFoo</td>
	</tr>
</table>

<h5 class='topic'>@RemoteMethod(returns)</h5>
<p>
	The return type of the Java methods of can be any of the following:
</p>
<ul class='spaced-list'>
	<li>
		<jk>void</jk> 
		- Don't parse any response.  
		<br>Note that the method will still throw a runtime exception if an error HTTP status is returned.
	<li>
		Any {@doc PojoCategories parsable} POJO 
		- The body of the response will be converted to the POJO using the parser defined on the 
		<c>RestClient</c> based on the <c>Content-Type</c> of the response.
	<li>
		Any {@link oaj.http.annotation.Response @Response}-annotated type. (described later)
	<li>
		<c>HttpResponse</c> 
		- Returns the raw <c>HttpResponse</c> returned by the inner <c>HttpClient</c>.
	<li>
		{@link java.io.Reader} 
		- Returns access to the raw reader of the response.
	<li>
		{@link java.io.InputStream} 
		- Returns access to the raw input stream of the response.
</ul>

<p>
	If you're only interested in the HTTP status code of the response, you can use the {@link oaj.http.remote.RemoteMethod#returns() returns}
	annotation with a value of {@link oaj.http.remote.RemoteReturn#STATUS STATUS}:
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>	
	<ja>@Remote</ja>
	<jk>public interface</jk> PetStore {
		
		<jc>// POST /pets</jc>
		<jc>// Returns HTTP status code.</jc>
		<ja>@RemoteMethod</ja>(returns=<jsf>STATUS</jsf>)
		<jk>int</jk> postPets(...);
	}
</p>
<p>
	If your <c>RestClient</c> does not have a parser associated with it, then the value is converted directly from a String using
	the rules defined in {@doc PojosConveribleToStrings}. 
</p>