Package org.dellroad.stuff.pobj

Interface PersistentObjectDelegate<T>

Type Parameters:
T - type of the root persistent object
All Known Implementing Classes:
AbstractDelegate, FilterDelegate, PersistentObjectSchemaUpdater, SpringDelegate, SpringPersistentObjectSchemaUpdater
public interface PersistentObjectDelegate<T>
Delegate interface required for PersistentObjects. Instances provide methods for converting to/from XML, validation, etc.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    copy(T original)
    Make a deep copy of the given object.
    T
    deserialize(Source source)
    Deserialize a root object graph from XML.
    T
    getDefaultValue()
    Get the default value for the root object graph.
    void
    handleWritebackException(PersistentObject<T> pobj, Throwable t)
    Handle an exception thrown during an asynchronous write-back attempt.
    boolean
    isSameGraph(T root1, T root2)
    Attempt to determine whether two object graphs are identical.
    void
    serialize(T obj, Result result)
    Serialize a root object graph into XML.
    Set<jakarta.validation.ConstraintViolation<T>>
    validate(T obj)
    Validate the given object.

  • Method Details

    • serialize

      void serialize(T obj, Result result) throws IOException
      Serialize a root object graph into XML.

      Note that this method effectively defines what is contained in the object graph rooted at obj.

      This method must not modify obj or any other object in its object graph.

      Parameters:
      obj - object to serialize; must not be modified
      result - XML destination
      Throws:
      IOException - if an I/O error occurs
      PersistentObjectException - if an error occurs

    • deserialize

      T deserialize(Source source) throws IOException
      Deserialize a root object graph from XML.

      This method also presents an opportunity to (re)construct any indexes used for optimizing queries into the root object graph.

      Parameters:
      source - XML source
      Returns:
      deserialized object
      Throws:
      IOException - if an I/O error occurs
      PersistentObjectException - if an error occurs

    • copy

      T copy(T original)
      Make a deep copy of the given object.

      For correct behavior, this behavior of this method should be equivalent to a serialization followed by a deserialization.

      This method must not modify original or any other object in its object graph.

      Parameters:
      original - original object
      Returns:
      deep copy of the object graph rooted at original
      Throws:
      IllegalArgumentException - if original is null
      PersistentObjectException - if an error occurs

    • isSameGraph

      boolean isSameGraph(T root1, T root2)
      Attempt to determine whether two object graphs are identical.

      This optional method is an optimization to detect invocations to PersistentObject.setRoot() where the new object graph and the old object graph are identical. In such cases, no change is applied, the version number does not increase, and no notifications are sent.

      It is always safe and correct for this method to return false. If it returns true, then it must be the case that the two object graphs are identical.

      This method must not modify oldRoot or newRoot or any other object in their object respective graphs.

      Parameters:
      root1 - root of first object graph
      root2 - root of second object graph
      Returns:
      true if root1 and root2 represent equal object graphs
      Throws:
      IllegalArgumentException - if oldRoot or newRoot is null
      PersistentObjectException - if an error occurs

    • validate

      Set<jakarta.validation.ConstraintViolation<T>> validate(T obj)
      Validate the given object.

      This method must not modify obj or any other object in its object graph.

      Parameters:
      obj - root object
      Returns:
      set of zero or more constraint violations
      Throws:
      IllegalArgumentException - if obj is null

    • handleWritebackException

      void handleWritebackException(PersistentObject<T> pobj, Throwable t)
      Handle an exception thrown during an asynchronous write-back attempt. ThreadDeath exceptions are not passed to this method, but all others are.

      When PersistentObject is configured for synchronous write-back, this method is not used.

      Parameters:
      pobj - the instance that encountered the exception
      t - the exception thrown

    • getDefaultValue

      T getDefaultValue()
      Get the default value for the root object graph. This method is invoked at startup when the persistent file does not exist. If this method returns null, then an empty start occurs unless the PersistentObject object is configured to disallow them, in which case an exception is thrown.
      Returns:
      root object initial value, or null if there is no default value