| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| @Request |
| |
| <p> |
| The {@link oaj.http.annotation.Request @Request} annotation can be applied to a type of a <ja>@RemoteMethod</ja>-annotated method |
| to identify it as a bean for setting HTTP parts through a bean-like interface. |
| </p> |
| |
| <ul class='javatree'> |
| <li class='ja'>{@link oaj.http.annotation.Request} |
| <ul> |
| <li class='jf'>{@link oaj.http.annotation.Request#partSerializer() partSerializer} - Override the part serializer. |
| </ul> |
| </ul> |
| |
| |
| <h5 class='figure'>Example:</h5> |
| <p class='bpcode w800'> |
| <ja>@Remote</ja>(path=<js>"/petstore"</js>) |
| <jk>public interface</jk> PetStore { |
| |
| <ja>@RemoteMethod</ja> |
| String postPet(CreatePetRequest bean); |
| } |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Request</ja> |
| <jk>public class</jk> CreatePetRequest { |
| |
| <jk>private</jk> CreatePet <jf>pet</jf>; |
| |
| <jk>public</jk> CreatePetRequest(String name, <jk>float</jk> price) { |
| <jk>this</jk>.<jf>pet</jf> = <jk>new</jk> CreatePet(name, price); |
| } |
| |
| <ja>@Body</ja> |
| <jk>public</jk> CreatePet getBody() { |
| <jk>return</jk> <jk>this</jk>.<jf>pet</jf>; |
| } |
| |
| <ja>@Query</ja> |
| <jk>public</jk> Map<String,Object> getQueryParams() { |
| <jk>return new</jk> ObjectMap().append(<js>"debug"</js>, <jk>true</jk>); |
| } |
| |
| <ja>@Header</ja>(<js>"E-Tag"</js>) |
| <jk>public static</jk> UUID <jsm>getUUID</jsm>() { |
| <jk>return</jk> UUID.<jsm>generatedUUID</jsm>(); |
| } |
| } |
| </p> |
| <p class='bpcode w800'> |
| PetStore store = restClient.getRemote(PetStore.<jk>class</jk>, <js>"http://localhost:10000"</js>); |
| CreatePetRequest requestBean = <jk>new</jk> CreatePetRequest(<js>"Fluffy"</js>, 9.99); |
| String response = store.postPet(requestBean); |
| </p> |
| <p> |
| The <ja>@Request</ja> annotation can be applied to either the class or argument. |
| </p> |
| <p> |
| The annotated methods must be no-arg and public. |
| They can be named anything. |
| </p> |
| <p> |
| Any of the following annotations can be used on the methods: |
| </p> |
| <ul class='javatree'> |
| <li class='ja'>{@link oaj.http.annotation.Body} |
| <li class='ja'>{@link oaj.http.annotation.Header} |
| <li class='ja'>{@link oaj.http.annotation.FormData} |
| <li class='ja'>{@link oaj.http.annotation.Query} |
| <li class='ja'>{@link oaj.http.annotation.Path} |
| </ul> |
| <p> |
| The behavior and functionality of all of the annotations are the same as if they were used on method arguments directly. |
| This means full support for OpenAPI serialization and validation. |
| </p> |
| <p> |
| Annotations on methods are inherited from parent classes and interfaces. |
| For example, the request bean above could have defined annotations in an interface to keep them clear from the implementation: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Request</ja> |
| <jk>public interface</jk> CreatePetRequest { |
| |
| <ja>@Body</ja> |
| CreatePet getBody(); |
| |
| <ja>@Query</ja> |
| Map<String,Object> getQueryParams(); |
| |
| <ja>@Header</ja>(<js>"E-Tag"</js>) |
| UUID getUUID(); |
| } |
| </p> |
| <p class='bpcode w800'> |
| <jk>public class</jk> CreatePetRequestImpl <jk>implements</jk> CreatePetRequest { |
| |
| <jk>public</jk> CreatePetRequestImpl(String name, <jk>float</jk> price) {...} |
| |
| <ja>@Override</ja> |
| <jk>public</jk> CreatePet getBody() { |
| <jk>return</jk> <jk>this</jk>.<jf>pet</jf>; |
| } |
| |
| <ja>@Override</ja> |
| <jk>public</jk> Map<String,Object> getQueryParams() { |
| <jk>return new</jk> ObjectMap().append(<js>"debug"</js>, <jk>true</jk>); |
| } |
| |
| <ja>@Override</ja> |
| <jk>public</jk> UUID getUUID() { |
| <jk>return</jk> UUID.<jsm>generateUUID</jsm>(); |
| } |
| } |
| </p> |
| |