Home

Structure

• Domain is the business model and handles business related validation
• Controller defines the API contract and enforces it with validation
• ControllerImpl translates the HTTP requests to service calls and handles simple parameter transformations prior to service calls
• Service is the interface that maps out accessibility to business features
• ServiceImpl is the business logic, the bulk of logic in the request and gathering data happens here
• Repository is the DAL (data access layer) and handles communication with the database
• Entity is the database contract definition and validation enforcement of that contract

Conventions

Resource

This is a consumable offered via API interaction. The naming for an example resource:

• user/v1/users/{ID} - the API endpoint (plural)
• User - the DTO (domain model)
• UserController - the API contract
• UserControllerImpl - the API contract implementation
• UserService - the interface to handle access control
• UserServiceImpl - the business logic
• UserRepository - the data access
• UserEntity - the database contract
• UserValidation - the persistence level validation

Exceptions

Any business logic exceptions throw ServiceLayerException in the service class, though this should be rare. Validation and Resource exceptions are handled by the framework if utilizing provided APIs. All exceptions are caught and handled by the framework to provide feedback to the user and log to the system. ExceptionParsers are used to translate exceptions to HTTP responses.

Validations

Domain Level (Business Validations)

Domain level validations are done on the domain models via implementing the Validatable interface. This is for business validations such as required fields and field checks.

Persistence Level (Database Data)

Persistence level validations are done via validation classes that extend the AbstractPersistenceValidation class and are used for validation checks against the DB, such as unique column value checks.

Entity Validations (Database Contracts)

Validations on the entities are only to protect the integrity of the database and enforce the DB contracts. No business logic validations are done here (meaning no messages back to the user).

API Validations (API Contracts)

These validations are done on the API (Controller) interfaces, and are used as basic API contract enforcements, done via the constraint annotations on the API interfaces. API implementations (ControllerImpl) contain no validation checks.

CRUD Operations

Basic crud requirements are fulfilled (with preset mechanics) by utilizing the CrudOperations class:

• getAll() gets all avalaible entities
• getById() gets by a specific id
  • Throws ResourceNotFoundException, resulting in 404, if not found
• createEntities() saves entities to the database
  • Throws Exception if already exists by id, performs validation checks (domain and persistence level)
• updateEntities() updates entities in the database
  • Throws ResourceNotFoundException, resulting in 404, if not found, performs validation checks (domain and persistence level)
• deleteEntities() deletes entities from the database
  • Throws ResourceNotFoundException, resulting in 404, if not found