Class PersistentObject

java.lang.Object
org.apache.cayenne.PersistentObject
All Implemented Interfaces:
Serializable, Persistent, Validating
Direct Known Subclasses:
BaseDataObject, GenericPersistentObject, HybridPersistentObject

public abstract class PersistentObject extends Object implements Persistent, Validating
Base implementation of Persistent, have no assumption about how data is actually stored. Provides implementation of properties declared in Persistent interface.

Three variants are currently supported:

  • field based storage, e.g. each entity class will directly define fields to store data
  • Map based storage, e.g. values will be stored in general Map (GenericPersistentObject)
  • mixed fields and generic Map to store runtime attributes (HybridPersistentObject)

This class can be used directly as superclass for field-based data objects.

To create own implementation of Persistent with custom field storage logic it is enough to implement readPropertyDirectly(String) and writePropertyDirectly(String, Object) methods and serialization support if needed (helper methods writeState(ObjectOutputStream) and readState(ObjectInputStream) are provided).

POJO Note

If having PersistentObject as a superclass presents a problem in an application, source code of this class can be copied verbatim to a custom class generation template. Desired superclass can be set in CayenneModeler.

Since:
1.2
See Also:
  • Field Details

    • objectId

      protected ObjectId objectId
    • persistenceState

      protected int persistenceState
    • objectContext

      protected transient ObjectContext objectContext
    • snapshotVersion

      protected long snapshotVersion
  • Constructor Details

    • PersistentObject

      public PersistentObject()
      Creates a new transient object.
  • Method Details

    • getPersistenceState

      public int getPersistenceState()
      Specified by:
      getPersistenceState in interface Persistent
    • getObjectContext

      public ObjectContext getObjectContext()
      Specified by:
      getObjectContext in interface Persistent
    • setObjectContext

      public void setObjectContext(ObjectContext objectContext)
      Specified by:
      setObjectContext in interface Persistent
      Since:
      1.2
    • getObjectId

      public ObjectId getObjectId()
      Specified by:
      getObjectId in interface Persistent
    • setObjectId

      public void setObjectId(ObjectId objectId)
      Specified by:
      setObjectId in interface Persistent
    • getMapKey

      protected Object getMapKey(String relationshipName, Object value)
      Returns a map key for a given to-many map relationship and a target object.
      Since:
      3.0
    • readPropertyDirectly

      public Object readPropertyDirectly(String propName)
      Description copied from interface: Persistent
      Returns mapped property value as currently stored in the Persistent object. Returned value maybe a fault or a real value. This method will not attempt to resolve faults, or to read unmapped properties.
      Specified by:
      readPropertyDirectly in interface Persistent
    • writePropertyDirectly

      public void writePropertyDirectly(String propName, Object val)
      Description copied from interface: Persistent
      Modifies a value of a named property without altering the object state in any way, and without triggering any database operations. This method is intended mostly for internal use by Cayenne framework, and shouldn't be called from the application code.
      Specified by:
      writePropertyDirectly in interface Persistent
    • beforePropertyRead

      protected void beforePropertyRead(String propName)
    • beforePropertyWrite

      protected void beforePropertyWrite(String propName, Object oldValue, Object newValue)
    • readProperty

      public Object readProperty(String propertyName)
      Description copied from interface: Persistent
      Returns a value of the property identified by propName. Resolves faults if needed. This method can safely be used instead of or in addition to the auto-generated property accessors in subclasses of the Persistent object.
      Specified by:
      readProperty in interface Persistent
    • readNestedProperty

      public Object readNestedProperty(String path)
      Returns a value of the property identified by a property path. Supports reading both mapped and unmapped properties. Unmapped properties are accessed in a manner consistent with JavaBeans specification.

      Property path (or nested property) is a dot-separated path used to traverse object relationships until the final object is found. If a null object found while traversing path, null is returned. If a list is encountered in the middle of the path, CayenneRuntimeException is thrown. Unlike readPropertyDirectly(String), this method will resolve an object if it is HOLLOW.

      Examples:

      • Read this object property:
        String name = (String)artist.readNestedProperty("name");

      • Read an object related to this object:
        Gallery g = (Gallery)paintingInfo.readNestedProperty("toPainting.toGallery");

      • Read a property of an object related to this object:
        String name = (String)painting.readNestedProperty("toArtist.artistName");

      • Read to-many relationship list:
        List exhibits = (List)painting.readNestedProperty("toGallery.exhibitArray");

      • Read to-many relationship in the middle of the path:
        List<String> names = (List<String>)artist.readNestedProperty("paintingArray.paintingName");

      Specified by:
      readNestedProperty in interface Persistent
      Since:
      1.0.5
      See Also:
    • readNestedProperty

      public Object readNestedProperty(CayennePath path)
      Description copied from interface: Persistent
      Returns a value of the property identified by a property path. Supports reading both mapped and unmapped properties. Unmapped properties are accessed in a manner consistent with JavaBeans specification.

      Property path (or nested property) is a dot-separated path used to traverse object relationships until the final object is found. If a null object found while traversing path, null is returned. If a list is encountered in the middle of the path, CayenneRuntimeException is thrown. Unlike Persistent.readPropertyDirectly(String), this method will resolve an object if it is HOLLOW.

      Examples:

      • Read this object property:
        String name = (String)artist.readNestedProperty("name");

      • Read an object related to this object:
        Gallery g = (Gallery)paintingInfo.readNestedProperty("toPainting.toGallery");

      • Read a property of an object related to this object:
        String name = (String)painting.readNestedProperty("toArtist.artistName");

      • Read to-many relationship list:
        List exhibits = (List)painting.readNestedProperty("toGallery.exhibitArray");

      • Read to-many relationship in the middle of the path:
        List<String> names = (List<String>)artist.readNestedProperty("paintingArray.paintingName");

      Specified by:
      readNestedProperty in interface Persistent
      Parameters:
      path - a dot-separated path
      Returns:
      a value of the property identified by a property path
      See Also:
    • writeProperty

      public void writeProperty(String propName, Object val)
      Description copied from interface: Persistent
      Sets the property to the new value. Resolves faults if needed. This method can be safely used instead of or in addition to the auto-generated property modifiers to set simple properties. Note that to set to-one relationships use Persistent.setToOneTarget(String, Persistent, boolean).
      Specified by:
      writeProperty in interface Persistent
      Parameters:
      propName - a name of the bean property being modified.
      val - a new value of the property.
    • removeToManyTarget

      public void removeToManyTarget(String relName, Persistent value, boolean setReverse)
      Description copied from interface: Persistent
      Removes an object from a to-many relationship.
      Specified by:
      removeToManyTarget in interface Persistent
    • addToManyTarget

      public void addToManyTarget(String relName, Persistent value, boolean setReverse)
      Description copied from interface: Persistent
      Adds an object to a to-many relationship.
      Specified by:
      addToManyTarget in interface Persistent
    • setToManyTarget

      public List<? extends Persistent> setToManyTarget(String relName, Collection<? extends Persistent> values, boolean setReverse)
      Sets the relationships to the specified Persistent objects.

      New relationships will be created with addToManyTarget(String, org.apache.cayenne.Persistent, boolean), already established relationships stay untouched. Missing relationships will be removed with removeToManyTarget(String, org.apache.cayenne.Persistent, boolean) and returned as List. You may delete them manually.

      Notice: Moving an object relationship to another object, is still needing an manually "unregister" from the first object by removeToManyTarget(String, org.apache.cayenne.Persistent, boolean)

      Parameters:
      relName - name of the relation
      values - Persistent objects of this Collection are set to the object. No changes will be made to the the Collection, a copy is used. It is safe to pass a persisted Collection of another object.
      setReverse - update reverse relationships
      Returns:
      List<? extends Persistent> of unrelated Persistent objects. If no relationship was removed an empty List is returned.
      Throws:
      IllegalArgumentException - if no relationship could be read by relName, or if the passed Collection is null. To clear all relationships use an empty Collection
      UnsupportedOperationException - if the relation Collection Type is neither java.util.Collection nor java.util.Map
      Since:
      4.0
    • setToOneTarget

      public void setToOneTarget(String relationshipName, Persistent value, boolean setReverse)
      Description copied from interface: Persistent
      Sets to-one relationship to a new value. Resolves faults if needed. This method can safely be used instead of or in addition to the auto-generated property modifiers to set properties that are to-one relationships.
      Specified by:
      setToOneTarget in interface Persistent
      Parameters:
      relationshipName - a name of the bean property being modified - same as the name of ObjRelationship.
      value - a new value of the property.
      setReverse - whether to update the reverse relationship pointing from the old and new values of the property to this object.
    • willConnect

      protected void willConnect(String relationshipName, Persistent object)
      Called before establishing a relationship with another object. Applies "persistence by reachability" logic, pulling one of the two objects to a DataConext of another object in case one of the objects is transient. If both objects are persistent, and they don't have the same DataContext, CayenneRuntimeException is thrown.
      Since:
      1.2
    • setReverseRelationship

      protected void setReverseRelationship(String relName, Persistent val)
      Initializes reverse relationship from object val to this object.
      Parameters:
      relName - name of relationship from this object to val.
    • unsetReverseRelationship

      protected void unsetReverseRelationship(String relName, Persistent val)
      Removes current object from reverse relationship of object val to this object.
    • setPersistenceState

      public void setPersistenceState(int persistenceState)
      Specified by:
      setPersistenceState in interface Persistent
    • getSnapshotVersion

      public long getSnapshotVersion()
      Description copied from interface: Persistent
      Returns a version of a DataRow snapshot that was used to create this object.
      Specified by:
      getSnapshotVersion in interface Persistent
      Since:
      1.1
    • setSnapshotVersion

      public void setSnapshotVersion(long snapshotVersion)
      Specified by:
      setSnapshotVersion in interface Persistent
      Since:
      1.1
    • validateForSave

      protected void validateForSave(ValidationResult validationResult)
      Performs property validation of the object, appending any validation failures to the provided validationResult object. This method is invoked from "validateFor.." before committing a NEW or MODIFIED object to the database. Validation includes checking for null values and value sizes. PersistentObject subclasses may override this method, calling super.
      Since:
      1.1
    • validateForInsert

      public void validateForInsert(ValidationResult validationResult)
      Calls validateForSave(ValidationResult). PersistentObject subclasses may override it providing validation logic that should be executed for the newly created objects before saving them.
      Specified by:
      validateForInsert in interface Validating
      Since:
      1.1
    • validateForUpdate

      public void validateForUpdate(ValidationResult validationResult)
      Calls validateForSave(ValidationResult). PersistentObject subclasses may override it providing validation logic that should be executed for the modified objects before saving them.
      Specified by:
      validateForUpdate in interface Validating
      Since:
      1.1
    • validateForDelete

      public void validateForDelete(ValidationResult validationResult)
      This implementation does nothing. PersistentObject subclasses may override it providing validation logic that should be executed for the deleted objects before committing them.
      Specified by:
      validateForDelete in interface Validating
      Since:
      1.1
    • writeSerialized

      protected void writeSerialized(ObjectOutputStream out) throws IOException
      Throws:
      IOException
    • readSerialized

      protected void readSerialized(ObjectInputStream in) throws IOException, ClassNotFoundException
      Throws:
      IOException
      ClassNotFoundException
    • writeState

      protected void writeState(ObjectOutputStream out) throws IOException
      Throws:
      IOException
    • readState

      protected void readState(ObjectInputStream in) throws IOException, ClassNotFoundException
      Throws:
      IOException
      ClassNotFoundException
    • toStringBuffer

      public StringBuffer toStringBuffer(StringBuffer buffer, boolean fullDesc)
      A variation of "toString" method, that may be more efficient in some cases. For example when printing a list of objects into the same String.
    • appendProperties

      protected void appendProperties(StringBuffer buffer)
    • toString

      public String toString()
      Overrides:
      toString in class Object