Package org.apache.cayenne

# Interface Persistent

All Superinterfaces:
  `Serializable`

All Known Subinterfaces:
  `DataObject`

All Known Implementing Classes:
  `BaseDataObject`, `GenericPersistentObject`, `HybridPersistentObject`, `PersistentObject`

public interface Persistent extends Serializable
Defines minimal API of an object that can be persisted via Cayenne.

Since:
  1.2

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `DEFAULT_VERSION`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addToManyTarget(String relationshipName, Persistent target, boolean setReverse)`
  Adds an object to a to-many relationship.
  `ObjectContext`
  `getObjectContext()`
  `ObjectId`
  `getObjectId()`
  `int`
  `getPersistenceState()`
  `long`
  `getSnapshotVersion()`
  Returns a version of a DataRow snapshot that was used to create this object.
  `Object`
  `readNestedProperty(String path)`
  Returns a value of the property identified by a property path.
  `Object`
  `readNestedProperty(CayennePath path)`
  Returns a value of the property identified by a property path.
  `Object`
  `readProperty(String propName)`
  Returns a value of the property identified by propName.
  `Object`
  `readPropertyDirectly(String propertyName)`
  Returns mapped property value as currently stored in the Persistent object.
  `void`
  `removeToManyTarget(String relationshipName, Persistent target, boolean unsetReverse)`
  Removes an object from a to-many relationship.
  `void`
  `setObjectContext(ObjectContext objectContext)`
  `void`
  `setObjectId(ObjectId id)`
  `void`
  `setPersistenceState(int state)`
  `void`
  `setSnapshotVersion(long snapshotVersion)`
  `void`
  `setToOneTarget(String relationshipName, Persistent value, boolean setReverse)`
  Sets to-one relationship to a new value.
  `void`
  `writeProperty(String propertyName, Object value)`
  Sets the property to the new value.
  `void`
  `writePropertyDirectly(String propertyName, Object val)`
  Modifies a value of a named property without altering the object state in any way, and without triggering any database operations.

- ## Field Details

  - ### DEFAULT_VERSION

    static final long DEFAULT_VERSION
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getObjectId

    ObjectId getObjectId()

  - ### setObjectId

    void setObjectId(ObjectId id)

  - ### getPersistenceState

    int getPersistenceState()

  - ### setPersistenceState

    void setPersistenceState(int state)

  - ### getObjectContext

    ObjectContext getObjectContext()

  - ### setObjectContext

    void setObjectContext(ObjectContext objectContext)

  - ### writePropertyDirectly

    void writePropertyDirectly(String propertyName, Object val)
    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.

  - ### readPropertyDirectly

    Object readPropertyDirectly(String propertyName)
    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.

  - ### readNestedProperty

    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");`
    Since:
      1.0.5
    See Also:
      - `readNestedProperty(CayennePath)`

  - ### readNestedProperty

    Object readNestedProperty(CayennePath 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");`
    Parameters:
      `path` - a dot-separated path
    Returns:
      a value of the property identified by a property path
    Since:
      5.0
    See Also:
      - `readNestedProperty(String)`

  - ### readProperty

    Object readProperty(String propName)
    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.

  - ### writeProperty

    void writeProperty(String propertyName, Object value)
    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 `setToOneTarget(String, Persistent, boolean)`.
    Parameters:
      `propertyName` - a name of the bean property being modified.
      `value` - a new value of the property.

  - ### addToManyTarget

    void addToManyTarget(String relationshipName, Persistent target, boolean setReverse)
    Adds an object to a to-many relationship.

  - ### removeToManyTarget

    void removeToManyTarget(String relationshipName, Persistent target, boolean unsetReverse)
    Removes an object from a to-many relationship.

  - ### setToOneTarget

    void setToOneTarget(String relationshipName, Persistent value, boolean setReverse)
    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.
    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.

  - ### getSnapshotVersion

    long getSnapshotVersion()
    Returns a version of a DataRow snapshot that was used to create this object.
    Since:
      1.1

  - ### setSnapshotVersion

    void setSnapshotVersion(long snapshotVersion)
    Since:
      1.1