Module litebridge.tracking
Package org.litebridgedb.tracking

Class TrackedDto<DTO>

java.lang.Object
org.litebridgedb.tracking.TrackedDto<DTO>
Type Parameters:
DTO - the type of the DTO object being tracked
public final class TrackedDto<DTO> extends Object
Wrapper that tracks changes made to an external DTO.

TrackedDto allows tracking changes in the fields of a given DTO (Data Transfer Object) over time. It maintains snapshots of field states and can identify changes by comparing the current state of the DTO's fields with previous snapshots.

This class is immutable and thread-safe. A typical usage involves taking snapshots of the DTO's fields, detecting changes, and optionally tracking nested DTOs or collections/maps of nested DTOs.

  • Constructor Details

    • TrackedDto

      public TrackedDto(DTO dto, ClassFieldAccessorCache classFieldAccessorCache, Consumer<Object> trackDtoCallback)
      Construct a TrackedDto instance that tracks all fields of the given DTO object.
      Parameters:
      dto - the data transfer object (DTO) to be wrapped and tracked; must not be null
      trackDtoCallback - the callback function to be triggered when tracking changes

    • TrackedDto

      public TrackedDto(DTO dto, Collection<FieldAccessor> fields, ClassFieldAccessorCache classFieldAccessorCache, Consumer<Object> trackDtoCallback)
      Construct a TrackedDto instance that wraps and tracks a given data transfer object (DTO).
      Parameters:
      dto - the data transfer object (DTO) to be wrapped and tracked; must not be null
      fields - the collection of FieldAccessor objects representing the fields to be tracked; must not be null
      trackDtoCallback - the callback function to be triggered when tracking changes; must not be null
      Throws:
      IllegalArgumentException - if any of the parameters are null

  • Method Details

    • dto

      public DTO dto()
      Retrieve the underlying DTO that is being tracked.

      Ensures that the DTO has not been garbage collected. If the DTO has been garbage collected, an exception is thrown.

      Returns:
      the non-null tracked DTO instance
      Throws:
      IllegalStateException - if the DTO object has been garbage collected

    • snapshot

      public void snapshot(boolean overwrite)
      Captures the current state of the tracked fields, creating a snapshot for later comparison.
      Parameters:
      overwrite - if true, any existing snapshots are cleared, and a new snapshot is taken; if false, an exception is thrown if a snapshot already exists
      Throws:
      IllegalStateException - if a previous snapshot has already been taken and overwrite is false.

    • snapshotEmpty

      public void snapshotEmpty()
      Initializes an empty snapshot of the tracked fields for the current object.

      This method captures the initial state of all fields as null, with a hash value of 0.

      Throws:
      IllegalStateException - if a previous snapshot has already been taken.

    • changedFields

      public ChangedFields changedFields()
      Retrieves the collection of modified fields in the tracked DTO since the last snapshot.

      On first invocation after a snapshot, the DTO is evaluated against the existing snapshot and a ChangedFields result is generated. This ChangedFields instance is cached, so subsequent calls to this method will return the same instance and is safe to use repeatedly.

      Returns:
      a ChangedFields instance representing the modified fields
      See Also:

    • changedFields

      public ChangedFields changedFields(boolean refresh)
      Retrieves the collection of modified fields in the tracked DTO since the last snapshot.

      If refresh is true, the method updates the internal snapshots based on the current modifications before returning the changed fields; effectively refreshing the tracking state. This means that the next call to changedFields() will no longer return the same result

      If refresh is false, the method behaves exactly as changedFields().

      Parameters:
      refresh - a boolean flag indicating whether to refresh the state of tracked fields before determining the changed fields. If true, the method updates the internal snapshots to reflect the latest state of the tracked fields. If false, the method uses the previously cached snapshots to determine changed fields.
      Returns:
      a ChangedFields instance representing the modified fields in the tracked DTO. If no changes have occurred, this instance will represent an empty set of changed fields.
      Throws:
      IllegalStateException - if field snapshots have not been previously taken.
      See Also: