Service Layer Design

Relevant source files

The following files were used as context for generating this wiki page:

• Part1/API/src/main/java/com/example/api/service/EmployeeService.java
• Part1/API/src/main/java/com/example/api/service/DepartmentService.java
• Part1/API/src/main/java/com/example/api/service/AssignmentService.java
• Part1/API/src/main/java/com/example/api/controller/EmployeeController.java
• Part1/API/src/main/java/com/example/api/controller/DepartmentController.java
• Part1/API/src/main/java/com/example/api/controller/AssignmentController.java
• Part1/API/src/main/resources/api-spec.yaml

The Service Layer in the SafeDispatch HQ Administration API acts as an intermediary between the REST controllers and the data persistence layer. Its primary purpose is to encapsulate complex business logic, perform data validation, and manage interactions between different domain entities. By isolating this logic, the architecture ensures that controllers remain focused on handling HTTP requests and responses, while services maintain the integrity of business rules.

Sources: Part1/API/src/main/java/com/example/api/service/EmployeeService.java, Part1/API/src/main/java/com/example/api/service/DepartmentService.java, Part1/API/src/main/java/com/example/api/service/AssignmentService.java

Core Service Components

The system is organized into three specialized service classes, each corresponding to a primary domain model. These services utilize Spring's @Service annotation for component scanning and dependency injection.

Service Overview Table

Service	Responsibility	Primary Dependencies
EmployeeService	Managing employee lifecycles, updates, and promotions.	EmployeeRepository
DepartmentService	Managing department creation and employee listings.	DepartmentRepository
AssignmentService	Linking employees to departments with roles and access levels.	AssignmentRepository, EmployeeRepository, DepartmentRepository

Sources: EmployeeService.java:13-15, DepartmentService.java:14-16, AssignmentService.java:15-18

Business Logic Implementation

Employee Promotion Logic

The EmployeeService implements a specific business rule for employee promotions. An employee is only eligible if they have been with the company for more than 6 months. The promotion process increases the salary by 10% and updates the job title to include a "Senior" prefix.

The diagram shows the conditional flow for promoting an employee, including eligibility checks and data transformations.
Sources: EmployeeService.java:49-70

Department Validation Logic

The DepartmentService ensures financial integrity by enforcing that a department cannot be created with a non-positive budget.

public Department createDepartment(Department department) {
    if (department.getBudget() == null || department.getBudget() <= 0) {
        throw new IllegalArgumentException("Budget must be positive");
    }
    return departmentRepository.save(department);
}

Sources: DepartmentService.java:24-29

Cross-Entity Coordination

The AssignmentService demonstrates how the service layer coordinates between multiple repositories to establish relationships. It creates an Assignment by first verifying the existence of both the Employee and the Department.

This sequence illustrates the dependency on multiple repositories to create a valid link between domain entities.
Sources: AssignmentService.java:26-40, AssignmentController.java:30-46

Data Flow Architecture

The architecture follows a strict linear flow from the API specification to the database.

Layer	Component	Function
API	api-spec.yaml	Defines endpoints, request bodies, and security roles (e.g., HR only).
Controller	EmployeeController	Orchestrates HTTP verbs and handles ResponseStatusException.
Service	EmployeeService	Executes business rules (e.g., promotion eligibility).
Repository	EmployeeRepository	Interfaces with the database via JpaRepository.

Sources: api-spec.yaml:124-142, EmployeeController.java:16-24, EmployeeService.java:13-23

Exception Handling in Services

Services utilize both standard Java exceptions and Spring-specific exceptions to communicate failures to the controller layer, which are then caught by a GlobalExceptionHandler.

• 404 Not Found: Thrown via ResponseStatusException when entities are missing.
• 400 Bad Request: Thrown for business rule violations (e.g., ineligible for promotion).
• IllegalArgumentException: Thrown for invalid input data (e.g., negative budget).

Sources: EmployeeService.java:27, DepartmentService.java:34, DepartmentController.java:31

Conclusion

The Service Layer in this project effectively decouples business logic from HTTP handling. By centralizing operations like the 6-month promotion rule and department budget validation, the system ensures consistent application of rules across different API endpoints and facilitates easier unit testing of core business functionality.

Sources: EmployeeService.java:49-70, DepartmentService.java:24-29