Spring and Spring Boot basic concepts

Each service is a Spring Boot project, the main entry point is the [ServiceName]Application.java class. This class is annotated with @SpringBootApplication, which provides multiple Spring annotations. We will focus on one in particular: @ComponentScan.

The job of @ComponentScan is to search for classes that are annotated with @Component (or annotations that extend/are annotated with it, such as @Controller or @Service). By default, @ComponentScan searches the base package of the class in which it is defined and all sub packages. For each class discovered in this way, a Spring bean will be added to the service's Spring application context. See this Baeldung article for further information on @ComponentScan.
To summarize it in a simple way: Beans are singleton instances of a class, and the Spring application context is like a cache which contains all these singleton instances so they can be accessed by any of the service's components.
If you are not familiar with Spring, please refer to the Spring Framework documentation.

Your service is a web application that can be started within an embedded server, it has the spring-boot-starter-tomcat dependency which provides an embedded Tomcat server. The API definition is made easy thanks to Spring Web annotations provided by the spring-boot-starter-web dependency. The endpoints of your web application are defined using the @RequestMapping annotation, which maps your controller methods to a path, an HTTP method type (GET, POST, etc.) and sometimes the produced and consumed content type(s).

Service logic flow

As described before, the endpoints of your service are defined via Spring Web annotations on your controllers. For a good introduction to Spring Boot starters and especially the Web starter, see this Baeldung article. Each of your data models will have a controller interface and its implementation, the methods generated there depend on the types of your data model's attributes. More information on generated content based on data can be found in the Data oriented content documentation.
We will use the TutorialService from the introduction tutorial as an example. The controller package of that service contains the IGroceryApi.java interface and its GroceryApiController.java implementation:

The IGroceryApi.java interface defines the API for the Grocery data model. The logic is first applied within GroceryApiController.java which passes the call on to the service layer. The service instance is autowired within the controller implementation, which means that an attribute of the service type is present in the controller class and annotated with Spring's @Autowire annotation, used to retrieve components from the application context: When the controller component is instantiated, the instance of the service attribute's class will be retrieved from the application context and the component's attribute will be set to that instance.

Now let's take a closer look at this service attribute. The type is IBaseDataModelService.java with type parameter Grocery, which is the class for which this controller is providing an API. Also, note the @Qualifier annotation with value "groceryService". We explained earlier how the @Autowired annotation is used to retrieve a specific component type from the application context - the @Qualifier annotation allows you to define multiple components of the same type in the application context by giving each of them an identifier and retrieving them via said identifier, as we are doing here to retrieve the service for handling Grocery logic.

The IBaseDataModelService is an interface provided by the brewer-base library. It has the implementation BaseDataModelServiceImpl which contains the global logic applied before and after any service-specific logic (e.g. security checks). This implementation has a constructor that takes an IDataModelService parameter. An implementation of the IDataModelService is generated for each of your service's data models, extending an abstract implementation that contains default logic (non-transient, which means that the data is saved in ApiOmat's database).
In the case of TutorialService, the service package contains GroceryApiServiceImpl.java which implements IDataModelService and extends the default implementation AbstractGroceryApiServiceImpl.java:

For each of your IDataModelService implementations, a bean of IBaseDataModelService is created within your service configuration, in the case of TutorialService this is the class TutorialServiceConfiguration.java:

Here's a quick summary of the logic flow:

1. Controllers are calling methods of the qualified autowired instance of IBaseDataModelService.

2. IBaseDataModelService has an implementation of type BaseDataModelServiceImpl.

3. The implementation instance of IDataModelService is provided to BaseDataModelServiceImpl in the bean creation method of the service configuration class.

4. BaseDataModelServiceImpl is calling methods of IDataModelService.

5. IDataModelService logic is either within your specific service implementation (e.g. GroceryApiServiceImpl) or the default abstract implementation (e.g. AbstractGroceryApiServiceImpl).

Service hooks

The IDataModelService provides multiple hooks to be used by the API controllers, and for which specific logic can be implemented in the ApiServiceImpl classes for each of your data models.
Here is the exhaustive list with some explanation:

The next section explains how the Feign framework is used and how to change this persistent behavior to transient.

Transient and persistent logic

tutorialservice:
	# to have a bean of GroceryApiNonTransientServiceImpl in your application context
	state: nontransient
	# to have a bean of GroceryApiTransientServiceImpl in your application context
	# state: transient

Exception handling

Spring Boot provides a smooth way to handle exceptions of a specific type that may be thrown while executing REST logic. Here is how exceptions are handled in your generated service's API:

1. The brewer-base library provides the autoconfigured exception handling class AOMErrorExceptionHandler. This class is annotated with @ControllerAdvice, notifying Spring logic that it provides a method annotated with @ExceptionHandler to be shared by all controller classes within the application context.

2. AOMErrorExceptionHandler extends the default ResponseEntityExceptionHandler of Spring that handles multiple types of exceptions that could be thrown by any REST API. It also contains a method that specifically handles AOMException:

   AOMErrorExceptionHandler.java

   @ExceptionHandler( { AOMException.class } )

   public ResponseEntity<String> handleFeignException( AOMException fe, WebRequest request )

3. AOMException is a simple runtime exception POJO that extends FeignException and provides a message and status code. When an AOMException is thrown by the logic called within your REST API, it's handled by the AOMErrorExceptionHandler#handleFeignException method mentioned above:

   1. Message and status are extracted from the AOMException.
      

   2. A JSONObject is created with fields "message", "status" and "timestamp".

   3. "message" and "status" correspond to the extracted values and "timestamp" is the value of Instant.now() (Java 8 class) at the time of the exception getting handled.

   4. The ResponseEntity contains the previously defined JSONObject value as a String body, the returned HTTP code depends on the status and is compliant to YAMBAS error codes:

      AOMErrorExceptionHandler.java

      if ( statusCode >= 700 && statusCode < 800 )

      {

      httpStatus = HttpStatus.BAD_REQUEST;

      }

      else if ( statusCode >= 800 && statusCode < 820 || statusCode >= 1800 && statusCode < 1820 )

      {

      httpStatus = HttpStatus.NOT_FOUND;

      }

      else if ( statusCode >= 820 && statusCode < 829 || statusCode >= 1820 && statusCode < 1829 )

      {

      httpStatus = HttpStatus.FORBIDDEN;

      }

      else if ( statusCode >= 830 && statusCode < 840 || statusCode >= 1830 && statusCode < 1840 )

      {

      httpStatus = HttpStatus.CONFLICT;

      }

      else if ( statusCode >= 840 && statusCode < 850 || statusCode >= 1840 && statusCode < 1850 )

      {

      httpStatus = HttpStatus.UNAUTHORIZED;

      }

      else if ( statusCode >= 900 )

      {

      httpStatus = HttpStatus.INTERNAL_SERVER_ERROR;

      }

      If the status code is under 700 and above/equal to 599, an "internal server error" code will be returned, otherwise the status's HTTP code value will be directly evaluated:

      HttpStatus.valueOf( statusCode );

4. Additionally, your generated Feign clients are configured so that any thrown FeignExceptions will be wrapped to an AOMException in the AOMErrorDecoder class and handled by the AOMErrorExceptionHandler mechanism:

   AOMFeignClientConfig.java

   @Bean

   public ErrorDecoder feignErrorDecoder( )

   {

   return new AOMErrorDecoder( );

   }

If you want a detailed explanation of the different ways to achieve REST exception handling in Spring, see this Baeldung article.