tessl/maven-org-apereo-cas--cas-server-core-configuration-api

Apereo CAS Core Configuration API providing configuration management and property source location capabilities for the Central Authentication Service

—

Pending

Overview

Eval results

Files

Configuration Watching

Name: tessl/maven-org-apereo-cas--cas-server-core-configuration-api
Author: tessl

File system monitoring service that watches configuration files and directories for changes, automatically publishing configuration events when modifications are detected. The watching service integrates with CAS event system and supports both file and directory monitoring.

Capabilities

Configuration Watch Service

Primary service for monitoring configuration files and directories with automatic event publishing on changes.

public class CasConfigurationWatchService implements Closeable, InitializingBean {
    /**
     * Constructor with application context for event publishing.
     *
     * @param applicationContext the configurable application context
     */
    public CasConfigurationWatchService(ConfigurableApplicationContext applicationContext);
    
    /**
     * Initialize file and directory watchers based on environment configuration.
     */
    public void initialize();
    
    /**
     * Close and cleanup all watch services.
     */
    @Override
    public void close();
    
    /**
     * InitializingBean callback method that calls initialize().
     */
    @Override
    public void afterPropertiesSet();
}

Usage Examples

Basic Watch Service Setup

import org.apereo.cas.configuration.CasConfigurationWatchService;
import org.springframework.context.ConfigurableApplicationContext;

// Create watch service with application context
CasConfigurationWatchService watchService = 
    new CasConfigurationWatchService(applicationContext);

// Initialize watchers (automatically called by afterPropertiesSet)
watchService.initialize();

// The service will now monitor:
// - Standalone configuration file (if specified)
// - Standalone configuration directory (if exists)

// Later, cleanup when shutting down
watchService.close();

Spring Bean Configuration

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class WatchServiceConfiguration {
    
    @Bean
    public CasConfigurationWatchService casConfigurationWatchService(
            ConfigurableApplicationContext applicationContext) {
        // Spring will automatically call afterPropertiesSet() after bean creation
        return new CasConfigurationWatchService(applicationContext);
    }
}

Manual Watch Service Management

// Create and configure watch service
CasConfigurationWatchService watchService = 
    new CasConfigurationWatchService(applicationContext);

// Manually initialize (normally done automatically)
watchService.initialize();

// Service is now monitoring for configuration changes

// At application shutdown
try {
    watchService.close();
} catch (Exception e) {
    logger.warn("Error closing configuration watch service", e);
}

Monitoring Behavior

File Monitoring

The watch service monitors the standalone configuration file when:

cas.standalone.configuration-file property is set
The specified file exists and is readable

// Set standalone configuration file
System.setProperty("cas.standalone.configuration-file", "/etc/cas/config/cas.properties");

// Watch service will monitor this specific file for:
// - Creation (if file is created after service starts)
// - Modification (content changes)
// - Deletion (if file is removed)

Directory Monitoring

The watch service monitors the configuration directory when:

A configuration directory is found (via cas.standalone.configuration-directory or defaults)
The directory exists and is readable

// Set configuration directory
System.setProperty("cas.standalone.configuration-directory", "/etc/cas/config");

// Watch service will monitor the entire directory for:
// - New configuration files created
// - Existing configuration files modified
// - Configuration files deleted

Default Directory Monitoring

If no specific directory is configured, the service checks default locations:

/etc/cas/config
/opt/cas/config
/var/cas/config

The first existing directory will be monitored.

Configuration Events

The watch service publishes different event types based on file system changes:

Event Types

// Event types published by the watch service
CasConfigurationCreatedEvent  // When configuration files are created
CasConfigurationModifiedEvent // When configuration files are modified  
CasConfigurationDeletedEvent  // When configuration files are deleted

Event Handling

import org.apereo.cas.config.CasConfigurationModifiedEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
public class ConfigurationChangeHandler {
    
    @EventListener
    public void handleConfigurationCreated(CasConfigurationCreatedEvent event) {
        Path configPath = event.getFile();
        System.out.println("Configuration file created: " + configPath);
        // Handle new configuration file
    }
    
    @EventListener  
    public void handleConfigurationModified(CasConfigurationModifiedEvent event) {
        Path configPath = event.getFile();
        System.out.println("Configuration file modified: " + configPath);
        // Reload configuration, restart services, etc.
    }
    
    @EventListener
    public void handleConfigurationDeleted(CasConfigurationDeletedEvent event) {
        Path configPath = event.getFile();
        System.out.println("Configuration file deleted: " + configPath);
        // Handle missing configuration
    }
}

Event Information

Each configuration event includes:

Source: The CasConfigurationWatchService instance
File Path: Path to the affected configuration file
Client Info: Client information from ClientInfoHolder (if available)
Timestamp: When the event occurred

Watch Service Implementation Details

File Watcher Integration

The service uses CAS utility classes for file system monitoring:

// File watching for specific files
FileWatcherService configurationFileWatch = new FileWatcherService(
    configFile,
    createConfigurationCreatedEvent.andNext(applicationContext::publishEvent),
    createConfigurationModifiedEvent.andNext(applicationContext::publishEvent), 
    createConfigurationDeletedEvent.andNext(applicationContext::publishEvent)
);

// Directory watching for configuration directories
PathWatcherService configurationDirectoryWatch = new PathWatcherService(
    configDirectory.toPath(),
    createConfigurationCreatedEvent.andNext(applicationContext::publishEvent),
    createConfigurationModifiedEvent.andNext(applicationContext::publishEvent),
    createConfigurationDeletedEvent.andNext(applicationContext::publishEvent)
);

Event Creation Functions

The service uses composable functions to create events:

// Function composition for event creation and publishing
ComposableFunction<File, AbstractCasEvent> createConfigurationCreatedEvent = file ->
        new CasConfigurationCreatedEvent(this, file.toPath(), ClientInfoHolder.getClientInfo());

ComposableFunction<File, AbstractCasEvent> createConfigurationModifiedEvent = file ->
        new CasConfigurationModifiedEvent(this, file.toPath(), ClientInfoHolder.getClientInfo());

ComposableFunction<File, AbstractCasEvent> createConfigurationDeletedEvent = file ->
        new CasConfigurationDeletedEvent(this, file.toPath(), ClientInfoHolder.getClientInfo());

Configuration Properties

Watch Service Configuration

The watch service behavior is controlled by these configuration properties:

# Standalone configuration file path
cas.standalone.configuration-file=/path/to/cas.properties

# Standalone configuration directory path  
cas.standalone.configuration-directory=/etc/cas/config

# Profile settings that affect watching
spring.profiles.active=standalone

Profile-Based Behavior

The watch service respects CAS profiles:

none profile: Skips directory watching entirely
Other profiles: Normal watching behavior
Multiple profiles: Uses profile precedence rules

// Profile "none" disables directory watching
System.setProperty("spring.profiles.active", "none");
// Directory watching will be skipped

// Standalone profile enables normal watching
System.setProperty("spring.profiles.active", "standalone");
// Normal file and directory watching

Lifecycle Management

Initialization Lifecycle

Service Creation: Constructor receives application context
afterPropertiesSet(): Spring calls this method after bean initialization
initialize(): Sets up file and directory watchers based on environment
Watch Services Start: Background threads begin monitoring file system
Event Publishing: Changes trigger event publication to application context

Shutdown Lifecycle

close(): Called during application shutdown or manual cleanup
Stop Watchers: Background monitoring threads are stopped
Resource Cleanup: File handles and system resources are released

Error Handling

The watch service handles various error conditions:

Missing Files: Gracefully handles non-existent configuration files
Permission Errors: Logs warnings for unreadable files or directories
I/O Errors: Continues operation when individual file operations fail
Shutdown Errors: Ensures cleanup even if watchers fail to stop cleanly

Performance Considerations

Resource Usage

File Handles: One file handle per monitored file/directory
Background Threads: Minimal thread usage for file system monitoring
Memory Usage: Low memory footprint for event handling

Monitoring Scope

File Monitoring: Watches specific files only
Directory Monitoring: Watches entire directories (not recursive)
Event Frequency: Events published only on actual changes (not periodic checks)

Scalability

Multiple Files: Can monitor both file and directory simultaneously
Event Processing: Asynchronous event publishing doesn't block file operations
Resource Limits: Bounded by system file watching capabilities

Install with Tessl CLI

npx tessl i tessl/maven-org-apereo-cas--cas-server-core-configuration-api

docs

configuration-encryption.md

configuration-loading.md

configuration-management.md

configuration-watching.md

index.md

property-source-location.md

tile.json

tessl/maven-org-apereo-cas--cas-server-core-configuration-api