Module litebridge.tracking
Package org.litebridgedb.tracking

Class ChangeTracker

java.lang.Object
org.litebridgedb.tracking.ChangeTracker
public final class ChangeTracker extends Object
This class provides functionality to track field-level changes of data transfer objects (DTOs) by maintaining a snapshot of their specified fields. It allows identifying changes made to the tracked fields during the object's lifecycle.

The ChangeTracker is particularly useful for scenarios involving change tracking or auditing where fields of certain objects need to be monitored for modifications.

This class is thread-safe.

  • Constructor Details

    • ChangeTracker

      public ChangeTracker()

    • ChangeTracker

      public ChangeTracker(MethodHandles.Lookup lookup)

  • Method Details

    • trackDto

      public <DTO> DTO trackDto(DTO dto)
      Tracks the given Data Transfer Object (DTO) for detecting changes.

      This method initializes tracking for the DTO and ensures that its state can be monitored for modifications during its lifecycle.

      Type Parameters:
      DTO - the type of the Data Transfer Object (DTO) to be tracked
      Parameters:
      dto - the Data Transfer Object (DTO) to be tracked; must not be null
      Returns:
      the tracked instance of the provided DTO
      Throws:
      NullPointerException - if the provided dto is null

    • trackDto

      public <DTO> DTO trackDto(DTO dto, Set<String> trackedFieldNames)
      Tracks the specified fields of a given Data Transfer Object (DTO) for detecting changes. This method identifies and stores a snapshot of the fields provided in the trackedFieldNames set, enabling monitoring of modifications during the lifecycle of the DTO.
      Type Parameters:
      DTO - the type of the DTO being tracked
      Parameters:
      dto - the Data Transfer Object (DTO) to be tracked; must not be null
      trackedFieldNames - the set of field names in the DTO to be tracked; each field name must exist in the DTO
      Returns:
      the tracked instance of the provided DTO
      Throws:
      IllegalArgumentException - if dto is null
      IllegalArgumentException - if any field name in trackedFieldNames does not exist in the DTO

    • trackDtoFields

      public <DTO> DTO trackDtoFields(DTO dto, Set<FieldAccessor> trackedFields)
      Tracks the specified fields of a given Data Transfer Object (DTO) for detecting changes.

      This method allows monitoring of specific fields within the DTO by capturing their initial state.

      Type Parameters:
      DTO - the type of the DTO being tracked
      Parameters:
      dto - the Data Transfer Object (DTO) to be tracked; must not be null
      trackedFields - the set of fields in the DTO to be tracked; each field must belong to the DTO
      Returns:
      the tracked instance of the provided DTO
      Throws:
      IllegalArgumentException - if dto is null

    • trackDtoFields

      public <DTO> DTO trackDtoFields(DTO dto, Set<FieldAccessor> trackedFields, boolean snapshotEmpty)
      Tracks the fields of the given Data Transfer Object (DTO) for detecting changes.

      This method allows monitoring specific fields within the DTO by capturing their initial state and optionally creating an empty snapshot.

      Type Parameters:
      DTO - the type of the DTO being tracked
      Parameters:
      dto - the Data Transfer Object (DTO) to be tracked; must not be null
      trackedFields - the set of fields in the DTO to be tracked; each field must belong to the DTO
      snapshotEmpty - if true, an empty snapshot will be created; otherwise, normal snapshot behavior is applied
      Returns:
      the tracked instance of the provided DTO
      Throws:
      NullPointerException - if the provided dto is null

    • getTrackedDto

      public <DTO> TrackedDto<DTO> getTrackedDto(DTO dto)
      Retrieves the tracked version of the specified Data Transfer Object (DTO), if it exists.

      The method looks up the internal storage for the tracked version of the given DTO and returns it.

      Parameters:
      dto - the Data Transfer Object (DTO) whose tracked version is to be retrieved; can be null
      Returns:
      the tracked version of the specified DTO, or null if no tracked version exists
      Throws:
      IllegalArgumentException - if the specified DTO is not tracked

    • getTrackedDtos

      public <DTO> Set<TrackedDto<DTO>> getTrackedDtos(Class<DTO> dtoClass)
      Retrieves a set of tracked Data Transfer Objects (DTOs) of the specified type.
      Type Parameters:
      DTO - the type of the Data Transfer Object (DTO) to be retrieved
      Parameters:
      dtoClass - the Class object representing the type of DTO to retrieve; must not be null
      Returns:
      a set of TrackedDto<DTO> objects that correspond to the specified DTO type; returns an empty set if no tracked DTOs of the specified type exist
      Throws:
      NullPointerException - if dtoClass is null

    • getTrackedDtoOrNull

      public <DTO> @Nullable TrackedDto<DTO> getTrackedDtoOrNull(DTO dto)
      Retrieves the tracked version of the specified Data Transfer Object (DTO), if it exists.

      The method attempts to fetch the associated tracked DTO from the internal storage and returns it. If no tracked version exists for the provided DTO, the method returns null.

      Type Parameters:
      DTO - the type of the Data Transfer Object (DTO)
      Parameters:
      dto - the Data Transfer Object (DTO) whose tracked version is to be retrieved; can be null
      Returns:
      the tracked version of the specified DTO, or null if no tracked version exists

    • classFieldAccessorCache

      public ClassFieldAccessorCache classFieldAccessorCache()
      Retrieves the instance of ClassFieldAccessorCache associated with the ChangeTracker.
      Returns:
      the ClassFieldAccessorCache instance used by this ChangeTracker