chore: merge release-1.x into dev-1.x [skip ci]

Author: github-actions[bot]

README.md

@@ -44,8 +44,8 @@ pom.xml:
 
 | **Branches** | **Purpose**                                      | **Latest Version** |
 |--------------|--------------------------------------------------|--------------------|
-| **0.2.x**    | Compatible with Spring Cloud 2022.0.x - 2025.0.x | 0.2.0              |
-| **0.1.x**    | Compatible with Spring Cloud Hoxton - 2021.0.x   | 0.1.0              |
+| **main**     | Compatible with Spring Cloud 2022.0.x - 2025.0.x | 0.2.1              |
+| **1.x**      | Compatible with Spring Cloud Hoxton - 2021.0.x   | 0.1.1              |
 
 ### Compatibility
 

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/DelegatingInterceptor.java

@@ -32,6 +32,23 @@
 /**
  * Delegating {@link Interceptor}
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Wrap a custom Interceptor to extend it
+ *   Interceptor myInterceptor = new EmptyInterceptor() {
+ *       @Override
+ *       public boolean onLoad(Object entity, Object id, Object[] state,
+ *                             String[] propertyNames, Type[] types) {
+ *           System.out.println("Loading entity: " + entity);
+ *           return false;
+ *       }
+ *   };
+ *   DelegatingInterceptor interceptor = new DelegatingInterceptor(myInterceptor);
+ *
+ *   // Pass null to fall back to EmptyInterceptor.INSTANCE
+ *   DelegatingInterceptor defaultInterceptor = new DelegatingInterceptor(null);
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy<a/>
  * @see Interceptor
  * @since 1.0.0
@@ -40,6 +57,12 @@ public class DelegatingInterceptor implements Interceptor, DelegatingWrapper {
 
     protected final Interceptor delegate;
 
+    /**
+     * Creates a new {@link DelegatingInterceptor} wrapping the given delegate.
+     * If {@code delegate} is {@code null}, {@link org.hibernate.internal.EmptyInterceptor#INSTANCE} is used.
+     *
+     * @param delegate the {@link Interceptor} to delegate to, or {@code null} for the empty interceptor
+     */
     public DelegatingInterceptor(@Nullable Interceptor delegate) {
         this.delegate = delegate == null ? INSTANCE : delegate;
     }

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/constants/PropertyConstants.java

@@ -28,6 +28,20 @@
 /**
  * The interface to declare the property constants of Microsphere Hibernate
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Enable Microsphere Hibernate via system property
+ *   System.setProperty(MICROSPHERE_HIBERNATE_ENABLED_PROPERTY_NAME, "true");
+ *
+ *   // Read the enabled flag
+ *   boolean enabled = Boolean.parseBoolean(
+ *       System.getProperty(MICROSPHERE_HIBERNATE_ENABLED_PROPERTY_NAME,
+ *                          DEFAULT_MICROSPHERE_HIBERNATE_ENABLED_PROPERTY_VALUE));
+ *
+ *   // Use the property name prefix to build custom property names
+ *   String customProperty = MICROSPHERE_HIBERNATE_PROPERTY_NAME_PREFIX + "myFeature.enabled";
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @since 1.0.0
  */

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/entity/CompositeEntityCallback.java

@@ -29,6 +29,19 @@
 /**
  * Composite {@link EntityCallback}
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   EntityCallback loggingCallback = new LoggingEntityCallback();
+ *   EntityCallback auditCallback = new AuditEntityCallback();
+ *   List<EntityCallback> callbacks = Arrays.asList(loggingCallback, auditCallback);
+ *   CompositeEntityCallback composite = new CompositeEntityCallback(callbacks);
+ *
+ *   // The composite will invoke both callbacks in order
+ *   composite.onPersist(myEntity, "MyEntity");
+ *   composite.onLoad(entityId, "MyEntity", myEntity, LockMode.NONE,
+ *                    false, null, null, LoadType.GET);
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see EntityCallback
  * @since 1.0.0
@@ -37,6 +50,12 @@ public class CompositeEntityCallback implements EntityCallback {
 
     private final List<EntityCallback> callbacks;
 
+    /**
+     * Creates a new {@link CompositeEntityCallback} backed by the given list of callbacks.
+     * Each callback will be invoked in the order it appears in the list.
+     *
+     * @param callbacks the ordered list of {@link EntityCallback} instances to delegate to
+     */
     public CompositeEntityCallback(List<EntityCallback> callbacks) {
         this.callbacks = callbacks;
     }

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/entity/EntittyCallbackIntegrator.java

@@ -51,6 +51,25 @@
 /**
  * Hibernate {@link Integrator} for {@link EntityCallback}
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Register via META-INF/services/org.hibernate.integrator.spi.Integrator
+ *   // (file content: io.microsphere.hibernate.entity.EntittyCallbackIntegrator)
+ *
+ *   // Or register programmatically when building the SessionFactory:
+ *   Configuration configuration = new Configuration()
+ *       .addAnnotatedClass(User.class);
+ *   SessionFactory sessionFactory = configuration
+ *       .buildSessionFactory(
+ *           new StandardServiceRegistryBuilder()
+ *               .applySettings(configuration.getProperties())
+ *               .build()
+ *       );
+ *
+ *   // Once active, all EntityCallback implementations loaded via ServiceLoader
+ *   // are notified for Hibernate events (load, persist, delete, merge, etc.)
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see Integrator
  * @see DuplicationStrategy
@@ -59,6 +78,14 @@
  */
 public class EntittyCallbackIntegrator implements Integrator {
 
+    /**
+     * Registers the {@link EntityCallbackListener} for all supported Hibernate event types
+     * on the given {@link SessionFactoryImplementor}.
+     *
+     * @param metadata           the Hibernate metadata
+     * @param sessionFactory     the session factory being built
+     * @param serviceRegistry    the session factory service registry
+     */
     public void integrate(Metadata metadata, SessionFactoryImplementor sessionFactory, SessionFactoryServiceRegistry serviceRegistry) {
         EventListenerRegistry eventListenerRegistry = serviceRegistry.getService(EventListenerRegistry.class);
 

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/entity/EntityCallback.java

@@ -57,6 +57,32 @@
  * The lifecycle callback interface for entity.
  * The implementation class will be loaded by {@link ServiceLoader Java Services Loader}.
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Implement a custom EntityCallback registered via
+ *   // META-INF/services/io.microsphere.hibernate.entity.EntityCallback
+ *   public class LoggingEntityCallback implements EntityCallback {
+ *
+ *       @Override
+ *       public void onPersist(Object entity, String entityName) {
+ *           System.out.println("Persisting: " + entityName + " -> " + entity);
+ *       }
+ *
+ *       @Override
+ *       public void onLoad(Object id, String entityClassName, Object entity,
+ *                          LockMode lockMode, boolean isAssociationFetch,
+ *                          Object result, Boolean readOnly, LoadType loadType) {
+ *           System.out.println("Loading: " + entityClassName + " id=" + id);
+ *       }
+ *
+ *       @Override
+ *       public void onPreDelete(Object entity, Object id, Object[] state,
+ *                               String[] propertyNames, Type[] types) {
+ *           System.out.println("About to delete: " + entity);
+ *       }
+ *   }
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see LoadEventListener
  * @see PersistEventListener

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/entity/EntityCallbackListener.java

@@ -82,6 +82,19 @@
 /**
  * The listener class for {@link EntityCallback}
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Default constructor loads EntityCallback implementations via ServiceLoader
+ *   EntityCallbackListener listener = new EntityCallbackListener();
+ *
+ *   // Or supply callbacks directly (useful in tests)
+ *   List<EntityCallback> callbacks = Arrays.asList(new LoggingEntityCallback());
+ *   EntityCallbackListener listener = new EntityCallbackListener(callbacks);
+ *
+ *   // The listener is registered by {@link EntittyCallbackIntegrator} on SessionFactory startup;
+ *   // it translates Hibernate events into EntityCallback invocations automatically.
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see LoadEventListener
  * @see PersistEventListener
@@ -123,10 +136,20 @@ class EntityCallbackListener implements LoadEventListener, PersistEventListener,
 
     private final EntityCallback callback;
 
+    /**
+     * Creates a new {@link EntityCallbackListener} that loads {@link EntityCallback} implementations
+     * from the classpath using {@link java.util.ServiceLoader}.
+     */
     EntityCallbackListener() {
         this(load(EntityCallback.class));
     }
 
+    /**
+     * Creates a new {@link EntityCallbackListener} backed by the given {@link EntityCallback} instances.
+     * Callbacks are sorted by priority using {@link io.microsphere.lang.Prioritized#COMPARATOR}.
+     *
+     * @param callbacks the iterable of {@link EntityCallback} instances to use
+     */
     EntityCallbackListener(Iterable<EntityCallback> callbacks) {
         List<EntityCallback> entityCallbacks = newLinkedList(callbacks);
         entityCallbacks.sort(COMPARATOR);
@@ -342,6 +365,12 @@ public boolean requiresPostCommitHandling(EntityPersister persister) {
         return PostDeleteEventListener.super.requiresPostCommitHandling(persister);
     }
 
+    /**
+     * Extracts the {@link LockMode} from the given {@link LockOptions}.
+     *
+     * @param lockOptions the lock options to extract the lock mode from
+     * @return the {@link LockMode} from the given {@link LockOptions}
+     */
     protected LockMode getLockMode(LockOptions lockOptions) {
         return lockOptions.getLockMode();
     }

microsphere-hibernate-core/src/main/java/io/microsphere/hibernate/entity/EntityCallbackListenerDuplicationStrategy.java

@@ -26,19 +26,45 @@
 /**
  * {@link DuplicationStrategy} class for {@link EntityCallbackListener}
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Used internally by EntittyCallbackIntegrator to prevent duplicate listener registration
+ *   EntityCallbackListenerDuplicationStrategy strategy = new EntityCallbackListenerDuplicationStrategy();
+ *
+ *   EntityCallbackListener listener1 = new EntityCallbackListener();
+ *   EntityCallbackListener listener2 = new EntityCallbackListener();
+ *   boolean match = strategy.areMatch(listener1, listener2); // true — same class
+ *
+ *   DuplicationStrategy.Action action = strategy.getAction(); // KEEP_ORIGINAL
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see EntityCallbackListener
  * @since 1.0.0
  */
 class EntityCallbackListenerDuplicationStrategy implements DuplicationStrategy {
 
+    /**
+     * Returns {@code true} if both {@code listener} and {@code original} are instances of
+     * {@link EntityCallbackListener}, preventing duplicate registrations.
+     *
+     * @param listener the candidate listener
+     * @param original the already-registered listener
+     * @return {@code true} if both are instances of {@link EntityCallbackListener}
+     */
     @Override
     public boolean areMatch(Object listener, Object original) {
         Class<?> listenerClass = listener.getClass();
         return Objects.equals(listenerClass, original.getClass())
                 && EntityCallbackListener.class.equals(listenerClass);
     }
 
+    /**
+     * Returns {@link org.hibernate.event.service.spi.DuplicationStrategy.Action#KEEP_ORIGINAL},
+     * meaning the first registered {@link EntityCallbackListener} is retained when a duplicate is detected.
+     *
+     * @return {@link org.hibernate.event.service.spi.DuplicationStrategy.Action#KEEP_ORIGINAL}
+     */
     @Override
     public Action getAction() {
         return KEEP_ORIGINAL;

microsphere-hibernate-parent/pom.xml

@@ -19,7 +19,7 @@
     <description>Microsphere Hibernate Parent</description>
 
     <properties>
-        <microsphere-spring-cloud.version>0.1.11</microsphere-spring-cloud.version>
+        <microsphere-spring-cloud.version>0.1.12</microsphere-spring-cloud.version>
     </properties>
 
     <dependencyManagement>

microsphere-hibernate-test/src/main/java/io/microsphere/hibernate/test/AbstractHibernateH2Test.java

@@ -40,6 +40,30 @@
 /**
  * Abstract Hibernate Test for H2 Database
  *
+ * <h3>Example Usage</h3>
+ * <pre>{@code
+ *   // Extend to write Hibernate integration tests backed by an in-memory H2 database
+ *   class MyEntityTest extends AbstractHibernateH2Test {
+ *
+ *       @Test
+ *       void testPersistAndGet() {
+ *           doInTransaction(() -> {
+ *               session.persist(user);
+ *               User found = session.get(User.class, user.getId());
+ *               assertEquals(user, found);
+ *           });
+ *       }
+ *
+ *       // Override createUser() to provide a custom User graph for tests
+ *       @Override
+ *       protected User createUser() {
+ *           User user = new User();
+ *           user.setName("Alice");
+ *           return user;
+ *       }
+ *   }
+ * }</pre>
+ *
  * @author <a href="mailto:mercyblitz@gmail.com">Mercy</a>
  * @see AbstractHibernateTest
  * @since 1.0.0
@@ -54,6 +78,12 @@ protected void init() {
         user = createUser();
     }
 
+    /**
+     * Creates a default {@link User} entity graph (with {@link UserProfile}, {@link Order}, and
+     * {@link Product}) used as test fixture data. Override to supply a custom graph.
+     *
+     * @return a new {@link User} instance with associated entities
+     */
     protected User createUser() {
         User user = new User();
         user.setName("Tom");
@@ -92,6 +122,11 @@ protected Configuration buildConfiguration() {
         return configuration;
     }
 
+    /**
+     * Executes the given action, asserting that it completes without throwing any exception.
+     *
+     * @param action the action to run
+     */
     protected void doInAction(Runnable action) {
         assertDoesNotThrow(action::run);
     }