Runtime Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
- Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java
- README.md
- Part1/API/src/main/java/com/example/api/controller/EmployeeController.java
- Part1/API/src/main/java/com/example/api/service/EmployeeService.java
- Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
- Part1/API/src/main/resources/api-spec.yaml
- Part1/API/gradlew.bat
The Runtime Troubleshooting framework within the SafeDispatch HQ Administration API is designed to identify, intercept, and resolve issues occurring during application execution. It primarily addresses environment setup, security authentication failures, business logic validation errors, and unhandled exceptions. This ensures that the system provides clear feedback to administrators and developers rather than exposing raw stack traces.
The system utilizes a centralized GlobalExceptionHandler to catch various exception types and convert them into standardized ErrorResponse objects as defined in the API specification. This troubleshooting infrastructure spans from the initial bootstrap (Gradle/JVM) to granular business rules such as employee promotion eligibility.
Sources: GlobalExceptionHandler.java:13-15, api-spec.yaml:104-108, gradlew.bat:42-53
Environment and Bootstrap Troubleshooting
Troubleshooting starts at the execution of the application environment. The Windows startup script manages common Java environment issues.
Java Environment Validation
The gradlew.bat script performs checks for the JAVA_HOME environment variable. If the variable is unset or points to an invalid directory, the script terminates with specific error messages.
| Error Condition | Message / Outcome | Source |
|---|---|---|
JAVA_HOME not set | "ERROR: JAVA_HOME is not set and no 'java' command could be found" | gradlew.bat:47-49 |
Invalid JAVA_HOME | "ERROR: JAVA_HOME is set to an invalid directory" | gradlew.bat:61-63 |
| JVM Startup failure | Returns EXIT_CODE derived from %ERRORLEVEL% | gradlew.bat:76-85 |
Exception Handling Architecture
The application uses a centralized exception handling strategy to manage runtime errors across all REST controllers.
The diagram shows how various exceptions are funneled through the GlobalExceptionHandler to produce a consistent JSON response.
Sources: GlobalExceptionHandler.java:17-48
Standardized Error Responses
The API specification defines an ErrorResponse schema used for troubleshooting HTTP 400, 401, 403, 404, and 500 errors.
| HTTP Status | Triggering Condition | Source File |
|---|---|---|
| 400 | Validation failures (e.g., non-positive budget, ineligible promotion) | GlobalExceptionHandler.java:34, EmployeeService.java:51 |
| 401 | Missing or invalid Basic Auth credentials | SecurityConfig.java:54, api-spec.yaml:122 |
| 403 | Authenticated user lacks sufficient role (HR vs MANAGER) | SecurityConfig.java:49-52, api-spec.yaml:156 |
| 404 | Resource not found (Employee, Department, or Assignment) | EmployeeController.java:35, AssignmentService.java:31 |
| 500 | Unhandled runtime exceptions | GlobalExceptionHandler.java:43-48 |
Sources: GlobalExceptionHandler.java:17-48, api-spec.yaml:104-108
Security and Access Troubleshooting
Authentication and Authorization issues are handled via Spring Security configurations. The system defaults to returning a 401 Unauthorized status for authentication failures rather than a redirect.
Role-Based Access Control (RBAC) Flow
Access issues are common when a user with the MANAGER role attempts to perform POST, PUT, or DELETE operations restricted to HR.
The sequence shows the troubleshooting path for authentication and authorization failures.
Sources: SecurityConfig.java:44-55, CustomUserDetailsService.java:27-36
Business Logic Validation
Troubleshooting "logical" failures occurs within the Service and Controller layers, specifically regarding data integrity and business rules.
Employee Promotion Eligibility
The system enforces a 6-month minimum tenure for promotions. Failures here return a 400 Bad Request.
// Logic within EmployeeService.java
public Employee promoteEmployee(Long id) {
Employee employee = getEmployeeById(id);
if (employee.getStartDate() == null || employee.getStartDate().isAfter(LocalDate.now().minusMonths(6))) {
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Employee not eligible for promotion");
}
// ...
}
Sources: EmployeeService.java:47-53, EmployeeController.java:82-84
Data Integrity Constraints
- Budget Validation: In
DepartmentControllerandDepartmentService, the budget must be a positive integer. Attempts to create a department withbudget <= 0trigger anIllegalArgumentException. Sources: DepartmentController.java:33-35, DepartmentService.java:28-30 - Entity Relationships: When creating an
Assignment, the system verifies if both theEmployeeandDepartmentexist. Failure results in a404 Not Found. Sources: AssignmentService.java:30-34
Summary
Runtime Troubleshooting in the Part1_API project is a multi-layered system. It begins with environment checks in the startup scripts, moves into security filtering for access control, and concludes with a centralized exception handler that catches both manual validation failures and unexpected runtime errors. This architecture ensures that all errors are surfaced as descriptive JSON responses, facilitating faster debugging and a better administrative experience.
Sources: GlobalExceptionHandler.java, SecurityConfig.java, gradlew.bat, EmployeeService.java