Merge branch 'issue-134-Add-SessionProfile-scaffolding-for-consuming-applications' into merge-fix-1

Author: devondragon

gradle.properties

@@ -1 +1 @@
-version=3.0.2-SNAPSHOT
+version=3.1.0-SNAPSHOT

src/main/java/com/digitalsanctuary/spring/user/UserAutoConfigurationRegistrar.java

@@ -0,0 +1,42 @@
+package com.digitalsanctuary.spring.user;
+
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.boot.autoconfigure.AutoConfigurationPackages;
+import org.springframework.context.annotation.ImportBeanDefinitionRegistrar;
+import org.springframework.core.type.AnnotationMetadata;
+
+/**
+ * {@code UserAutoConfigurationRegistrar} dynamically registers the base package of this library with Spring Boot to ensure that its entities,
+ * repositories, and other Spring-managed components are properly detected and included in the application context.
+ *
+ * <p>
+ * This class is designed to simplify the integration of the library into Spring Boot applications by automatically registering the library's base
+ * package (<i>com.digitalsanctuary.spring.user</i>) for component scanning. It ensures that:
+ * <ul>
+ * <li>The library's repositories and entities are discovered and configured correctly.</li>
+ * <li>The consuming application retains its ability to automatically detect its own repositories and entities.</li>
+ * </ul>
+ *
+ * <p>
+ * This approach avoids the need for the consuming application to manually specify the library's base package or manage complex configuration,
+ * reducing setup effort and minimizing potential errors.
+ *
+ * <p>
+ * <b>Note:</b> This solution leverages {@link AutoConfigurationPackages#register} to dynamically register the library's package during the
+ * auto-configuration phase, ensuring compatibility with Spring Boot's component scanning and auto-configuration mechanisms.
+ */
+public class UserAutoConfigurationRegistrar implements ImportBeanDefinitionRegistrar {
+
+    /**
+     * Registers the library's base package (<i>com.digitalsanctuary.spring.user</i>) with the Spring application context to enable automatic
+     * detection of entities, repositories, and other components provided by the library.
+     *
+     * @param importingClassMetadata metadata of the class that imports this registrar
+     * @param registry the bean definition registry used to register the base package
+     */
+    @Override
+    public void registerBeanDefinitions(AnnotationMetadata importingClassMetadata, BeanDefinitionRegistry registry) {
+        // Register the top-level package for the library
+        AutoConfigurationPackages.register(registry, "com.digitalsanctuary.spring.user");
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/UserConfiguration.java

@@ -1,9 +1,8 @@
 package com.digitalsanctuary.spring.user;
 
-import org.springframework.boot.autoconfigure.domain.EntityScan;
 import org.springframework.context.annotation.ComponentScan;
 import org.springframework.context.annotation.Configuration;
-import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
+import org.springframework.context.annotation.Import;
 import org.springframework.scheduling.annotation.EnableAsync;
 import org.springframework.scheduling.annotation.EnableScheduling;
 import jakarta.annotation.PostConstruct;
@@ -19,18 +18,17 @@
 @EnableAsync
 @EnableScheduling
 @ComponentScan(basePackages = "com.digitalsanctuary.spring.user")
-@EnableJpaRepositories(basePackages = "com.digitalsanctuary.spring.user.persistence.repository")
-@EntityScan(basePackages = "com.digitalsanctuary.spring.user.persistence.model")
+@Import(UserAutoConfigurationRegistrar.class)
 public class UserConfiguration {
 
+
     /**
-     * Method executed after the bean initialization.
-     * <p>
-     * This method logs a message indicating that the DigitalSanctuary Spring Boot User Framework LIbrary has been loaded.
-     * </p>
+     * Logs a message when the UserConfiguration class is loaded to indicate that the DigitalSanctuary Spring Boot User Framework Library has been
+     * loaded.
      */
     @PostConstruct
     public void onStartup() {
-        log.info("DigitalSanctuary SpringBoot User Framework Library loaded");
+        log.info("DigitalSanctuary SpringBoot User Framework Library loaded.");
     }
+
 }

src/main/java/com/digitalsanctuary/spring/user/profile/BaseUserProfile.java

@@ -0,0 +1,68 @@
+package com.digitalsanctuary.spring.user.profile;
+
+import java.time.LocalDateTime;
+import com.digitalsanctuary.spring.user.persistence.model.User;
+import jakarta.persistence.Column;
+import jakarta.persistence.Id;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.MappedSuperclass;
+import jakarta.persistence.MapsId;
+import jakarta.persistence.OneToOne;
+import lombok.Data;
+
+/**
+ * Base class for user profile entities that extend the core {@link User} functionality. This class provides the foundation for creating
+ * application-specific user profiles with shared common attributes.
+ *
+ * <p>
+ * This class uses {@code @MappedSuperclass} to allow inheritance of JPA mappings, enabling extending classes to add additional fields while
+ * maintaining a consistent database structure. The profile shares its primary key with the associated {@link User} entity through the {@code @MapsId}
+ * annotation.
+ * </p>
+ *
+ * Example implementation: {@code @Entity
+ *
+ * @Table(name = "customer_profile") public class CustomerProfile extends BaseUserProfile { private String customerType; private String
+ * shippingPreference; private List<Order> orders; } }
+ *
+ * Database Structure: - id/user_id (PK/FK to user_account table) - last_accessed (timestamp) - preferred_locale (varchar)
+ *
+ * @see User
+ * @see MappedSuperclass
+ */
+@Data
+@MappedSuperclass
+public abstract class BaseUserProfile {
+
+    /**
+     * The primary key for the profile, shared with the associated User entity. This is automatically populated through the {@code @MapsId} annotation
+     * when the profile is persisted.
+     */
+    @Id
+    private Long id;
+
+    /**
+     * The associated User entity. This establishes a one-to-one relationship with shared primary key through the {@code @MapsId} annotation. The
+     * foreign key column will be named "user_id".
+     */
+    @OneToOne
+    @MapsId
+    @JoinColumn(name = "user_id")
+    private User user;
+
+    /**
+     * Timestamp of the last time this profile was accessed. This can be used for tracking user activity, session management, or implementing timeout
+     * functionality.
+     */
+    @Column(name = "last_accessed")
+    private LocalDateTime lastAccessed;
+
+    /**
+     * The user's preferred locale for internationalization purposes. This should contain a valid locale code (e.g., "en_US", "fr_FR"). Applications
+     * can use this to provide localized content and formatting.
+     */
+    @Column(name = "preferred_locale")
+    private String locale;
+
+    // Note: Getters and setters are provided by Lombok @Data annotation
+}

src/main/java/com/digitalsanctuary/spring/user/profile/UserProfileService.java

@@ -0,0 +1,67 @@
+package com.digitalsanctuary.spring.user.profile;
+
+import com.digitalsanctuary.spring.user.persistence.model.User;
+
+/**
+ * Service interface for managing user profiles. This interface defines the core operations for retrieving, creating, and updating user profiles that
+ * extend the base profile functionality.
+ *
+ * <p>
+ * Implementations of this interface handle the persistence and business logic for user profiles, providing a standardized way to manage extended user
+ * data beyond the core {@link User} entity.
+ * </p>
+ *
+ * Example implementation: {@code @Service public class CustomUserProfileService implements UserProfileService<CustomUserProfile> { private final
+ * CustomUserProfileRepository profileRepository;
+ *
+ * @Override public CustomUserProfile getOrCreateProfile(User user) { return profileRepository.findByUserId(user.getId()) .orElseGet(() -> {
+ * CustomUserProfile profile = new CustomUserProfile(); profile.setUser(user); return profileRepository.save(profile); }); }
+ *
+ * @Override public CustomUserProfile updateProfile(CustomUserProfile profile) { return profileRepository.save(profile); } } }
+ *
+ * @param <T> the type of user profile to manage, must extend BaseUserProfile
+ * @see BaseUserProfile
+ * @see User
+ */
+public interface UserProfileService<T extends BaseUserProfile> {
+
+    /**
+     * Retrieves an existing profile for the given user or creates a new one if none exists. This method ensures that every user has an associated
+     * profile.
+     *
+     * <p>
+     * Implementations should:
+     * </p>
+     * <ul>
+     * <li>Check if a profile exists for the user</li>
+     * <li>Create a new profile if none exists</li>
+     * <li>Initialize any required default values for new profiles</li>
+     * <li>Persist the profile if newly created</li>
+     * </ul>
+     *
+     * @param user the user to get or create a profile for
+     * @return the existing or newly created profile
+     * @throws IllegalArgumentException if user is null
+     * @throws RuntimeException if profile creation or retrieval fails
+     */
+    T getOrCreateProfile(User user);
+
+    /**
+     * Updates an existing user profile with new information.
+     *
+     * <p>
+     * Implementations should:
+     * </p>
+     * <ul>
+     * <li>Validate the profile data before updating</li>
+     * <li>Persist the changes to the data store</li>
+     * <li>Return the updated profile instance</li>
+     * </ul>
+     *
+     * @param profile the profile to update
+     * @return the updated profile
+     * @throws IllegalArgumentException if profile is null or invalid
+     * @throws RuntimeException if profile update fails
+     */
+    T updateProfile(T profile);
+}

src/main/java/com/digitalsanctuary/spring/user/profile/session/BaseAuthenticationListener.java

@@ -0,0 +1,83 @@
+package com.digitalsanctuary.spring.user.profile.session;
+
+import org.springframework.context.ApplicationListener;
+import org.springframework.security.authentication.event.InteractiveAuthenticationSuccessEvent;
+import org.springframework.stereotype.Component;
+import com.digitalsanctuary.spring.user.profile.BaseUserProfile;
+import com.digitalsanctuary.spring.user.profile.UserProfileService;
+import com.digitalsanctuary.spring.user.service.DSUserDetails;
+
+/**
+ * Base authentication listener that handles successful user authentication events by loading or creating the appropriate user profile and storing it
+ * in the session. This class provides the core functionality for maintaining user profile state across the application session.
+ *
+ * <p>
+ * This listener automatically responds to successful interactive authentication events (like form login) by retrieving or creating a user profile via
+ * the {@link UserProfileService} and storing it in the session-scoped {@link BaseSessionProfile}.
+ * </p>
+ *
+ * <p>
+ * Example implementation:
+ * </p>
+ *
+ * <pre>
+* {@code
+ * @Component
+ * public class CustomAuthenticationListener extends BaseAuthenticationListener<CustomUserProfile> {
+ *     public CustomAuthenticationListener(CustomSessionProfile sessionProfile, CustomUserProfileService profileService) {
+ *         super(sessionProfile, profileService);
+ *     }
+ * }
+ * }</pre>
+ *
+ * @param <T> the type of user profile, must extend BaseUserProfile
+ *
+ * @see BaseSessionProfile
+ * @see UserProfileService
+ * @see InteractiveAuthenticationSuccessEvent
+ * @see DSUserDetails
+ */
+@Component
+public abstract class BaseAuthenticationListener<T extends BaseUserProfile> implements ApplicationListener<InteractiveAuthenticationSuccessEvent> {
+
+    /** The session profile manager for storing user profile data. */
+    private final BaseSessionProfile<T> sessionProfile;
+
+    /** The service for retrieving or creating user profiles. */
+    private final UserProfileService<T> profileService;
+
+    /**
+     * Constructs a new BaseAuthenticationListener with the specified session profile and profile service.
+     *
+     * @param sessionProfile the session-scoped profile manager
+     * @param profileService the service for managing user profiles
+     * @throws IllegalArgumentException if either parameter is null
+     */
+    protected BaseAuthenticationListener(BaseSessionProfile<T> sessionProfile, UserProfileService<T> profileService) {
+        if (sessionProfile == null || profileService == null) {
+            throw new IllegalArgumentException("Session profile and profile service must not be null");
+        }
+        this.sessionProfile = sessionProfile;
+        this.profileService = profileService;
+    }
+
+    /**
+     * Handles successful authentication events by loading or creating the user's profile and storing it in the session.
+     *
+     * <p>
+     * This method is automatically called by Spring's event system when a user successfully authenticates. It checks if the authentication principal
+     * is a {@link DSUserDetails} instance, and if so, retrieves or creates the associated profile and stores it in the session.
+     * </p>
+     *
+     * @param event the authentication success event
+     * @throws IllegalStateException if the authentication details are invalid or missing
+     */
+    @Override
+    public void onApplicationEvent(InteractiveAuthenticationSuccessEvent event) {
+        if (event.getAuthentication().getPrincipal() instanceof DSUserDetails) {
+            DSUserDetails userDetails = (DSUserDetails) event.getAuthentication().getPrincipal();
+            T profile = profileService.getOrCreateProfile(userDetails.getUser());
+            sessionProfile.setUserProfile(profile);
+        }
+    }
+}

src/main/java/com/digitalsanctuary/spring/user/profile/session/BaseSessionProfile.java

@@ -0,0 +1,86 @@
+package com.digitalsanctuary.spring.user.profile.session;
+
+import java.io.Serializable;
+import java.time.LocalDateTime;
+import org.springframework.context.annotation.Scope;
+import org.springframework.context.annotation.ScopedProxyMode;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.WebApplicationContext;
+import com.digitalsanctuary.spring.user.persistence.model.User;
+import com.digitalsanctuary.spring.user.profile.BaseUserProfile;
+import lombok.Data;
+
+/**
+ * Base class for session-scoped user profile management. This class provides the foundation for maintaining user profile data within the session
+ * context of a web application. It is designed to be extended by applications to add custom profile management functionality.
+ *
+ * <p>
+ * This class is session-scoped and uses proxy mode TARGET_CLASS to ensure proper session management in a web environment. It maintains a reference to
+ * the user's profile and tracks when it was last updated.
+ * </p>
+ *
+ * <p>
+ * Example usage:
+ * </p>
+ *
+ * <pre>
+ * {@code
+ * @Component
+ * public class CustomSessionProfile extends BaseSessionProfile<CustomUserProfile> {
+ *     // Add custom methods for your application
+ *     public boolean hasSpecificPermission() {
+ *         return getUserProfile().getPermissions().contains("SPECIFIC_PERMISSION");
+ *     }
+ * }
+ * }</pre>
+ *
+ * @param <T> the type of user profile, must extend BaseUserProfile
+ *
+ * @see BaseUserProfile
+ * @see WebApplicationContext
+ * @see Serializable
+ */
+@Data
+@Component
+@Scope(value = WebApplicationContext.SCOPE_SESSION, proxyMode = ScopedProxyMode.TARGET_CLASS)
+public abstract class BaseSessionProfile<T extends BaseUserProfile> implements Serializable {
+
+    /** Serialization version ID. */
+    private static final long serialVersionUID = 1L;
+
+    /** The current user's profile. */
+    private T userProfile;
+
+    /** Timestamp of when the profile was last updated. */
+    private LocalDateTime lastUpdated;
+
+    /**
+     * Retrieves the current user's profile.
+     *
+     * @return the user profile of type T, or null if no profile is set
+     */
+    public T getUserProfile() {
+        return userProfile;
+    }
+
+    /**
+     * Sets the user's profile and updates the lastUpdated timestamp. This method is typically called during authentication or when the profile data
+     * is modified.
+     *
+     * @param userProfile the user profile to set
+     */
+    public void setUserProfile(T userProfile) {
+        this.userProfile = userProfile;
+        this.lastUpdated = LocalDateTime.now();
+    }
+
+    /**
+     * Convenience method to get the core User entity associated with the profile.
+     *
+     * @return the User entity if a profile is set, null otherwise
+     * @see User
+     */
+    public User getUser() {
+        return userProfile != null ? userProfile.getUser() : null;
+    }
+}