Package de.esoco.history

Klasse HistoryManager

java.lang.Object
de.esoco.history.HistoryManager
@RelationTypeNamespace("de.esoco.history") public class HistoryManager extends Object
This class contains static methods to query, create, and manipulate history records. The manipulation methods like begin(Entity, Entity, String) are thread-based, i.e. they record history entries based on the invoking thread.

  • Felddetails

    • DEFAULT_HISTORY_NOTE_TEMPLATES

      public static final String DEFAULT_HISTORY_NOTE_TEMPLATES
      The key for the default templates in HISTORY_NOTE_TEMPLATES.
      Siehe auch:

    • HISTORIZED

      public static final org.obrel.core.RelationType<Boolean> HISTORIZED
      A flag relation type that marks objects which create history records. This can be used as a hint to wrap it in a history group if necessary.

    • HISTORY_NOTE_TEMPLATES

      public static final org.obrel.core.RelationType<Map<String,String>> HISTORY_NOTE_TEMPLATES
      A configuration extra attribute that contains mapping from process names to templates for history notes. The map values must be in the form "[Template]\n[Template]\n..." where each template must have the format "[Title]|[Text]". [Title] must not contain linefeeds or other control characters and preferably only text to prevent parsing errors of the extra attribute. If the [Text] part needs to contain linefeeds they must be escaped as '$n'.

      The map key is either the name of the process in which the templates should be applied or the string DEFAULT_HISTORY_NOTE_TEMPLATES for which the value contains the default templates that are always available.

  • Methodendetails

    • begin

      public static void begin(Entity origin, Entity target, String value)
      Begins a new group of history records for the current thread. The topmost group and all it's children will be made persistent when a matching call to commit(boolean) is made. A call to the rollback() method will cancel the complete history group hierarchy.
      Parameter:
      origin - The entity from which the record originates (may be NULL)
      target - The target entity referenced by the record (may be NULL)
      value - The value of this record

    • commit

      public static void commit(boolean keepIfEmpty) throws de.esoco.lib.manage.TransactionException
      Commits a group of history records. The group must previously have been started with a call to begin(Entity, Entity, String).
      Parameter:
      keepIfEmpty - TRUE to keep empty groups, FALSE to discard them
      Löst aus:
      de.esoco.lib.manage.TransactionException - If storing the group fails

    • getHistoryFor

      public static List<HistoryRecord> getHistoryFor(Entity target, HistoryRecord.HistoryType type) throws de.esoco.storage.StorageException
      Returns the history entries for a target object that have a certain type.
      Parameter:
      target - The target entity to search records for
      type - The type of the history records to query or NULL
      Gibt zurück:
      A list of history records that match the given criteria (may be empty but will never be NULL)
      Löst aus:
      de.esoco.storage.StorageException - If querying the history storage fails
      IllegalArgumentException - If the target entity is NULL
      Siehe auch:

    • getHistoryFor

      public static List<HistoryRecord> getHistoryFor(Entity target, HistoryRecord.HistoryType type, Date fromDate, Date toDate, Entity origin) throws de.esoco.storage.StorageException
      Returns the history entries for a target object. The returned records can optionally be constrained to certain criteria. Criteria that are NULL will be ignored.
      Parameter:
      target - The target entity to search records for
      type - The type of the history records to query or NULL
      fromDate - The start date for the queried records or NULL
      toDate - The end date for the queried records or NULL
      origin - The origin entity to search records for or NULL
      Gibt zurück:
      A list of history records that match the given criteria (may be empty but will never be NULL)
      Löst aus:
      de.esoco.storage.StorageException - If querying the history storage fails
      IllegalArgumentException - If the target entity is NULL

    • getHistoryStorage

      public static de.esoco.storage.Storage getHistoryStorage() throws de.esoco.storage.StorageException
      Returns the storage instance that will be used by history operations from the current (= invoking) thread to access history records. When the returned storage instance is no longer needed, the calling code must invoke the method Storage.release() to free the storage resources. See the method StorageManager.getStorage(Object) for details.

      This method is intended mainly for internal use by the history implementation but it may also be used by special application code which needs to access the history storage and is therefore public. Applications should be careful when manipulating the history storage, especially when invoking Storage.commit() or Storage.rollback(). Furthermore, if no history operations have been performed by the current thread before, the invocation may create a new storage instance and thus acquire system resources.

      Gibt zurück:
      The history storage instance for the current thread
      Löst aus:
      de.esoco.storage.StorageException - If acquiring a new storage instance fails

    • init

      public static void init()
      This method should be invoked at application startup to initialize the history functionality.

    • isRecording

      public static boolean isRecording()
      Allows to check whether a history is recorded for the current thread.
      Gibt zurück:
      The recording

    • record

      public static void record(HistoryRecord.HistoryType type, Entity origin, Entity target, String value) throws de.esoco.lib.manage.TransactionException
      Records a history entry. If a history group has been started before by means of begin(Entity, Entity, String) the new entry will be added as a detail record to that group. If no group is active a single history record will be created and stored immediately.
      Parameter:
      type - The type of the new history record
      origin - The entity from which the record originates (may be NULL)
      target - The target entity referenced by the record (may be NULL)
      value - The value of this record
      Löst aus:
      de.esoco.lib.manage.TransactionException - If storing the new record fails

    • record

      public static void record(HistoryRecord.HistoryType type, Entity origin, Entity target, Entity rootTarget, String value, HistoryRecord.ReferenceType referenceType, String referenceValue) throws de.esoco.lib.manage.TransactionException
      Records a history entry with a reference value. If a history group has been started before by means of begin(Entity, Entity, String) the new entry will be added as a detail record to that group. If no group is active a single history record will be created and stored immediately.
      Parameter:
      type - The type of the new history record
      origin - The entity from which the record originates (may be NULL)
      target - The target entity referenced by the record (may be NULL)
      rootTarget - The root target entity of the record (may be NULL, will be ignored if a group is active)
      value - The value of this record
      referenceType - The type of the reference value
      referenceValue - The reference value
      Löst aus:
      de.esoco.lib.manage.TransactionException - If storing the new record fails

    • rollback

      public static void rollback()
      Cancels any currently active hierarchy of history records and discards it. This method must be invoked when an exception occurs after a history group has been started with begin(Entity, Entity, String) to remove any remaining history group for the current thread. Additional invocations of this method will be ignored.

    • shutdown

      public static void shutdown()
      Performs a shutdown of the history manager and frees all allocated resources.