The {@link oaj.http.annotation.Response} annotation can be used to define beans that return HTTP response
parts via annotations and methods. They are used in combination with the following annotations:
- {@link oaj.http.annotation.StatusCode}
- {@link oaj.http.annotation.Header}
- {@link oaj.http.annotation.Content}
- {@link oaj.annotation.Schema}
Response beans can either be returned or thrown from {@link oajr.annotation.RestOp @RestOp}-annotated methods.
-
As a general convention, response beans with return codes <400 should be defined as regular classes and
>=400 should be defined as exceptions.
The following example shows the @Response annotation used to define an exception for an invalid login attempt:
| // Our annotated normal response.
| @Response
| @StatusCode(200)
| @Schema(
| description="User was good." // Description show in Swagger
| )
| public class ValidLogin {
| public ValidLogin() {
| ...
| }
|
| // Response bean converted to output based on Accept header.
| @Content
| public WelcomeMessageBean getContent() {
| return new WelcomeMessageBean();
| }
| }
| // Our annotated exception.
| @Response
| @StatusCode(401)
| @Schema(
| description="Invalid username or password provided" // Description show in Swagger
| )
| public class InvalidLogin extends Exception {
| public InvalidLogin() {
| super("Invalid username or password."); // Message sent in response
| }
|
| @Header("My-Message")
| public String getMyMessage() {
| return "Nope!";
| }
| }
| // Our REST method that throws an annotated exception.
| @RestGet("/user/login")
| public ValidLogin login(
| @FormData("username") String username,
| @FormData("password") String password
| ) throws InvalidLogin
| {
| if (isValid(username, password)) {
| return new ValidLogin();
| }
| throw new InvalidLogin();
| }
Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@link oaj.http.response.Unauthorized} exception:
| // Our annotated exception.
| @Response
| @Schema(
| description="Invalid username or password provided" // Overridden from parent class
| )
| public class InvalidLogin extends Unauthorized {
| public InvalidLogin() {
| super("Invalid username or password.");
| }
| }
|
| // Parent predefined exception class.
| @Response
| @StatusCode(401)
| @Schema(
| description="Unauthorized"
| )
| public class Unauthorized extends RestException {...}