The {@link oaj.http.remote.RemoteOp @RemoteOp} annotation is applied to methods
of @Remote-annotated interfaces to identify REST endpoints.
- {@link oaj.http.remote.RemoteOp}
- {@link oaj.http.remote.RemoteOp#method method}
- {@link oaj.http.remote.RemoteOp#path path}
- {@link oaj.http.remote.RemoteOp#returns returns}
Specialized sub-annotations are provided for common HTTP methods:
- {@link oaj.http.remote.RemoteGet}
- {@link oaj.http.remote.RemotePost}
- {@link oaj.http.remote.RemotePut}
- {@link oaj.http.remote.RemotePatch}
- {@link oaj.http.remote.RemoteDelete}
@RemoteOp(method/path)
The HTTP method and path are mapped to a Java method using the method and path annotations.
| @Remote
| public interface PetStore {
|
| // GET /pets/{petId}
| @RemoteGet("/pets/{petId}")
| Pet getPet(@Path("petId") int id);
| }
The Java method name can be anything.
Inferred method/path
In such cases, method and path annotations are optional if you follow certain naming
conventions on your method that identify the method and path.
For example, the getPet method below defaults to GET /pet:
| @Remote
| public interface PetStore {
|
| // GET /pet
| @RemoteOp
| Pet getPet(...);
| }
In such cases, the @RemoteOp annotation is optional.
Method names matching the following pattern are assumed to be implying the HTTP method name:
| (get|put|post|delete|options|head|connect|trace|patch).*
| do(?i)(get|put|post|delete|options|head|connect|trace|patch)
Java method name |
Inferred HTTP method |
Inferred HTTP path |
getPet() |
GET |
/pet |
get() |
GET |
/ |
postPet() |
POST |
/pet |
fooPet() |
[default] |
/fooPet |
doGet() |
GET |
/ |
doGET() |
GET |
/ |
doFoo() |
[default] |
/doFoo |
@RemoteOp(returns)
The return type of the Java methods of can be any of the following:
-
void/{@link java.lang.Void}
- Don't parse any response.
Note that the method will still throw a runtime exception if an error HTTP status is returned.
-
Any parseable POJO
- The body of the response will be converted to the POJO using the parser defined on the
RestClient based on the Content-Type of the response.
-
Any {@link oaj.http.annotation.Response @Response}-annotated type. (described later)
-
HttpResponse
- Returns the raw HttpResponse returned by the inner HttpClient.
-
{@link java.io.Reader}
- Returns access to the raw reader of the response.
-
{@link java.io.InputStream}
- Returns access to the raw input stream of the response.
-
A {@link java.util.concurrent.Future} or {@link java.util.concurrent.CompletableFuture} of anything on this list.
If you're only interested in the HTTP status code of the response, you can use the {@link oaj.http.remote.RemoteOp#returns() returns}
annotation with a value of {@link oaj.http.remote.RemoteReturn#STATUS STATUS}:
| @Remote
| public interface PetStore {
|
| // POST /pets
| // Returns HTTP status code.
| @RemotePost(returns=STATUS)
| int pets(...);
| }
If your RestClient does not have a parser associated with it, then the value is converted directly from a String using
the rules defined in POJO Categories.