V2.0.0 (#2)

* added factory getters

* pool config changes

* pool changes to suite new config

* fixed activate object call and added log format

* config tests

* udpated retry logic, and handle and error case

* added most used option and handled better eviction logic

* fixed some issue with object pool eviction and return

* tests passing state

* updated version

* updated version and fixed flaky tests

* updated parent pom version

Author: venkata-kishore

pom.xml

@@ -7,11 +7,11 @@
     <parent>
         <groupId>today.bonfire.oss</groupId>
         <artifactId>bonfire-oss-parent</artifactId>
-        <version>1.1.3</version>
+        <version>1.1.4</version>
     </parent>
 
     <artifactId>simple-object-pool</artifactId>
-    <version>1.3.0</version>
+    <version>2.0.0</version>
     <packaging>jar</packaging>
 
     <properties>

src/main/java/today/bonfire/oss/sop/PoolEntity.java renamed to src/main/java/today/bonfire/oss/sop/PoolObject.java

@@ -3,7 +3,7 @@
 /**
  * Represents an entity that can be managed by a {@link SimpleObjectPool}.  Each implementing class must provide a unique identifier.
  */
-public interface PoolEntity {
+public interface PoolObject {
 
   /**
    * Retrieves the unique identifier for this entity.
@@ -17,7 +17,8 @@ public interface PoolEntity {
   /**
    * Sets the unique identifier for this entity.
    * This method should only be called by the {@link SimpleObjectPool} implementation.
-   * Directly setting this value may lead to unexpected behavior.
+   * Directly setting this value may lead to unexpected behavior. 
+   * Implementations should throw an {@link IllegalStateException} if the entity ID is already set as it is not allowed to change.
    * <p>
    * Example:
    * <pre>{@code
@@ -31,6 +32,9 @@ public interface PoolEntity {
    *
    *   @Override
    *   public void setEntityId(Long entityIdValue) {
+   *     if (this.entityId != null) {
+   *       throw new IllegalStateException("Entity ID already set");
+   *     }
    *     this.entityId = entityIdValue;
    *   }
    * }

src/main/java/today/bonfire/oss/sop/PoolResourceException.java

@@ -0,0 +1,158 @@
+package today.bonfire.oss.sop;
+
+import java.util.Objects;
+
+/**
+ * Represents a wrapper for pooled objects that maintains state information about the object's usage.
+ * This class tracks whether an object is borrowed, broken, or idle, and manages its usage timestamps.
+ *
+ * @param <T> The type of the pooled object, must implement PoolObject for proper identification
+ */
+public class PooledObject<T extends PoolObject> {
+  private final    T       object;
+  private final    long creationTime;
+  private volatile long lastBorrowedTime;
+  private volatile long idleFromTime;
+  private volatile boolean broken;
+  private volatile boolean borrowed;
+  private          long timesBorrowed;
+
+  /**
+   * Creates a new PooledEntity wrapping the given object with a specified ID.
+   * Initializes the object in an idle, non-broken state with current timestamp.
+   *
+   * @param object The object to be pooled
+   * @param id     The unique identifier to assign to this pooled entity
+   */
+  PooledObject(T object, Long id) {
+    Objects.requireNonNull(object, "Pool object cannot be null");
+    this.object = object;
+    object.setEntityId(id);
+    this.creationTime = System.currentTimeMillis();
+    this.borrowed     = false;
+    this.broken       = false;  // Initialize broken state
+  }
+
+  /**
+   * Returns the number of times this object has been borrowed from the pool.
+   *
+   * @return The number of times this object has been borrowed.
+   */
+  public long timesBorrowed() {
+    return timesBorrowed;
+  }
+
+  /**
+   * Returns the timestamp when this object was created.
+   *
+   * @return The creation timestamp in milliseconds.
+   */
+  public long creationTime() {
+    return creationTime;
+  }
+
+  /**
+   * Returns the timestamp when this object was last borrowed from the pool.
+   *
+   * @return The last borrowed timestamp in milliseconds.
+   */
+  public long lastBorrowedTime() {
+    return lastBorrowedTime;
+  }
+
+  /**
+   * Checks if this object is marked as broken.
+   *
+   * @return {@code true} if the object is broken, {@code false} otherwise.
+   */
+  public boolean isBroken() {
+    return broken;
+  }
+
+  /**
+   * Sets the broken state of this object.
+   *
+   * @param broken {@code true} if the object should be marked as broken, {@code false} otherwise.
+   */
+  public void broken(boolean broken) {
+    this.broken = broken;
+  }
+
+  /**
+   * Returns the underlying pooled object.
+   *
+   * @return The pooled object.
+   */
+  public T object() {
+    return object;
+  }
+
+  /**
+   * Retrieves the entity ID of the wrapped object.
+   *
+   * @return The unique identifier of the wrapped object.
+   */
+  Long id() {
+    return object.getEntityId();
+  }
+
+  /**
+   * Marks this object as borrowed and updates its last borrowed timestamp.
+   * This method should be called when the object is taken from the pool.
+   */
+  void borrow() {
+    borrowed = true;
+    lastBorrowedTime = System.currentTimeMillis();
+    timesBorrowed++;
+  }
+
+  /**
+   * Marks this object as idle and updates its idle timestamp.
+   * This method should be called when the object is returned to the pool.
+   */
+  void markIdle() {
+    borrowed     = false;
+    idleFromTime = System.currentTimeMillis();
+  }
+
+  /**
+   * Checks if this object has been abandoned by comparing its last borrowed time
+   * against the specified abandonment timeout.
+   *
+   * @param abandonmentTimeoutMillis The maximum allowed duration in milliseconds since the object was last borrowed.
+   * @return {@code true} if the object is considered abandoned, {@code false} otherwise.
+   */
+  boolean isAbandoned(long now, long abandonmentTimeoutMillis) {
+    return borrowed && ((now - lastBorrowedTime) >= abandonmentTimeoutMillis);
+  }
+
+  /**
+   * Returns the duration in milliseconds that this object has been idle.
+   *
+   * @return The duration in milliseconds that this object has been idle.
+   */
+  public long idlingTime() {
+    return System.currentTimeMillis() - idleFromTime;
+  }
+
+  @Override
+  public int hashCode() {
+    return Long.hashCode(id());
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof PooledObject<?> that)) return false;
+    return Objects.equals(id(), that.id());
+  }
+
+  /**
+   * Returns the number of times this object has been borrowed
+   *
+   * @return borrow count
+   */
+  public long borrowCount() {
+    return timesBorrowed;
+  }
+}

src/main/java/today/bonfire/oss/sop/PooledEntity.java

@@ -3,22 +3,32 @@
 /**
  * Provides a factory for creating pooled objects.
  * Implementations should provide a concrete type of T that implements the
- * {@link PoolEntity} interface.
+ * {@link PoolObject} interface.
  *
- * @param <T> the type of object to be pooled, must implement {@link PoolEntity}
+ * @param <T> the type of object to be pooled, must implement {@link PoolObject}
  */
-public interface PooledObjectFactory<T extends PoolEntity> {
+public interface PooledObjectFactory<T extends PoolObject> {
 
   /**
    * Creates an instance of the pooled object.
    * This method is responsible for instantiating and initializing
-   * a new object of type T that implements the {@link PoolEntity} interface.
+   * a new object of type T that implements the {@link PoolObject} interface.
    * Implementations should handle any exceptions gracefully.
    *
    * @return a newly created object of type T, never null.
    */
   T createObject();
 
+
+  /**
+   * Activates the pooled object.
+   * This method is called when the object is taken from the pool,
+   * and is responsible for any necessary activation or initialization setting before borrow.
+   *
+   * @param obj the object to activate, must not be null.
+   */
+  void activateObject(T obj);
+
   /**
    * Validates the pooled object to determine if it can be safely borrowed.
    * This method should return true if the object is in a valid state for