| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| Predefined Responses |
| |
| <p> |
| Predefined response beans are provided for all standard HTTP responses. |
| These can be used as-is or extended to provide customized HTTP responses. |
| </p> |
| <h5 class='figure'>Examples:</h5> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>) |
| <jk>public</jk> Ok addPet(<ja>@Body</ja> Pet pet) { |
| <jsm>addPet</jsm>(Pet); |
| |
| <jc>// Predefined "200 OK" response bean.</jc> |
| <jk>return new</jk> Ok(); <jc>// Could also use Ok.OK instance</jc> |
| } |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>) |
| <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) { |
| <jsm>addPet</jsm>(Pet); |
| |
| <jc>// Predefined "302 See Other" response bean with redirect to /pets.</jc> |
| <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>); |
| } |
| </p> |
| <ul class='javatree'> |
| <li class='jp'>{@link oaj.http.response} |
| <ul> |
| <li class='jc'>{@link oaj.http.response.Accepted} |
| <li class='jc'>{@link oaj.http.response.AlreadyReported} |
| <li class='jc'>{@link oaj.http.response.Continue} |
| <li class='jc'>{@link oaj.http.response.Created} |
| <li class='jc'>{@link oaj.http.response.EarlyHints} |
| <li class='jc'>{@link oaj.http.response.Found} |
| <li class='jc'>{@link oaj.http.response.IMUsed} |
| <li class='jc'>{@link oaj.http.response.MovedPermanently} |
| <li class='jc'>{@link oaj.http.response.MultipleChoices} |
| <li class='jc'>{@link oaj.http.response.MultiStatus} |
| <li class='jc'>{@link oaj.http.response.NoContent} |
| <li class='jc'>{@link oaj.http.response.NonAuthoritiveInformation} |
| <li class='jc'>{@link oaj.http.response.NotModified} |
| <li class='jc'>{@link oaj.http.response.Ok} |
| <li class='jc'>{@link oaj.http.response.PartialContent} |
| <li class='jc'>{@link oaj.http.response.PermanentRedirect} |
| <li class='jc'>{@link oaj.http.response.Processing} |
| <li class='jc'>{@link oaj.http.response.ResetContent} |
| <li class='jc'>{@link oaj.http.response.SeeOther} |
| <li class='jc'>{@link oaj.http.response.SwitchingProtocols} |
| <li class='jc'>{@link oaj.http.response.TemporaryRedirect} |
| <li class='jc'>{@link oaj.http.response.UseProxy} |
| </ul> |
| </ul> |
| <p> |
| These predefined response beans are an example of {@link oaj.http.annotation.Response @Response}-annotated |
| objects that are describe in detail later. |
| Without going into details, this is how the {@link oaj.http.response.SeeOther} is defined: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Response</ja>( |
| code=303 <jc>// Set automatically on response</jc>, |
| description=<js>"See Other"</js> <jc>// Used in generated Swagger</jc> |
| ) |
| <jk>public class</jk> SeeOther { |
| |
| <jk>private final</jk> String <jf>message</jf>; |
| <jk>private final</jk> URI <jf>location</jf>; |
| |
| <jc>// Constructors omitted.</jc> |
| |
| <jc>// Used to populate Location response header.</jc> |
| <ja>@ResponseHeader</ja>(name=<js>"Location"</js>) |
| <jk>public</jk> URI getLocation() { |
| <jk>return</jk> <jf>location</jf>; |
| } |
| |
| <jc>// Used during serialization.</jc> |
| <ja>@ResponseBody</ja> |
| <jk>public</jk> String toString() { |
| <jk>return</jk> <jf>message</jf>; |
| } |
| } |
| </p> |
| <p> |
| The {@link oajr.helper.SeeOtherRoot} class shows how these predefined beans can be extended. |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Response</ja>( |
| description=<js>"Redirect to servlet root"</js> <jc>// Override description in generated Swagger.</jc> |
| ) |
| <jk>public class</jk> SeeOtherServletRoot <jk>extends</jk> SeeOther { |
| |
| <jk>public</jk> SeeOtherServletRoot() { |
| <jk>super</jk>(URI.create("servlet:/")); |
| } |
| } |
| </p> |
| <p> |
| Note that the runtime behavior of the following code is identical to the example above. |
| However, the important distinction is that in the previous example, the 302 response would show in |
| the generated Swagger (since we can see the response through reflection), whereas it will NOT show up |
| in the following example (since all we see is an Object response). |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>) |
| <jk>public</jk> Object addPet(<ja>@Body</ja> Pet pet) { |
| <jsm>addPet</jsm>(Pet); |
| |
| <jc>// Note the Object return type.</jc> |
| <jk>return new</jk> SeeOther(<js>"servlet:/pets"</js>); |
| } |
| </p> |