Helper

Helper Utilities Layer

📝 Note: This guide uses generic placeholder names to be reusable across any Spring Boot microservice. Replace with your actual implementation:

• {YourService} → Your service name (e.g., OrderService, PaymentService)
• BusinessService → Your core service (e.g., OrderService, UserService)
• DataService → Your data processing service (e.g., PaymentService, InventoryService)
• IntegrationService → Your external integration (e.g., PaymentGatewayService)
• {RequestType} → Your request DTO (e.g., CreateOrderRequest)
• {ResponseType} → Your response DTO (e.g., OrderResponse)

Purpose

The helper layer provides reusable utility methods for common operations in authentication services, including token manipulation, parameter extraction, collection operations, and data transformation. These pure, stateless functions promote code reuse and maintain consistency across the application.

Architecture

• Utility Class Pattern: Static methods with no instance state
• Generic Programming: Type-safe generic methods
• Functional Programming: Stream-based operations
• Pure Functions: No side effects, deterministic outputs

Package Structure

helper/
└── ServiceHelpers.java    # Authentication service utility methods

Quick Reference

Basic Utility Pattern

public class ServiceHelpers {
    private ServiceHelpers() {
        throw new AssertionError("Cannot instantiate utility class");
    }
    
    public static String stripBearerPartFromToken(String bearerToken) {
        // Pure function - no side effects
    }
    
    public static <T> T getMandatoryParam(Map<String, Object> params, String paramName) {
        // Type-safe generic extraction
    }
}

Service Integration

@Service
public class ProcessingServiceImpl implements ProcessingService {
    public AuthenticatedTokens refreshAccessToken(String authorization) {
        // Token manipulation
        String refreshToken = stripBearerPartFromToken(authorization);
        
        // Type-safe parameter extraction
        List<String> roles = getMandatoryParam(tokenData, "roles");
        
        // Collection operations
        List<String> authRoles = filterAuthRoles(roles);
        List<String> merged = mergeRolesWithEntitlement(authRoles, resource accesss);
        
        return buildTokenResponse(merged);
    }
}

Core Operations

Token Manipulation

• stripBearerPartFromToken() - Remove "Bearer " prefix (case-insensitive, idempotent)

Parameter Extraction

• getMandatoryParam() - Type-safe generic extraction with validation

Collection Operations

• extractServiceIds() - Stream-based service ID extraction
• getDefaultProfiles() - Filter and map profiles
• removeDuplicates() - Dedup while preserving order (LinkedHashSet)
• filterAuthRoles() - Filter to authentication roles only
• mergeRolesWithEntitlement() - Merge with null safety and dedup

Key Principles

1. Pure Functions: No side effects, same input → same output
2. Immutability: Always return new collections, never modify inputs
3. Type Safety: Generic methods prevent ClassCastException
4. Null Safety: Return empty collections instead of null
5. Idempotent: Safe to call multiple times with same result
6. Static Import Friendly: Clean, readable code in services

Example Package

com.example.microserviceorch.helper.example

See guides/ for detailed patterns and best practices. See examples/ for complete working code samples.