org.apache.cayenne

## Class CayenneDataObject

- java.lang.Object
- - org.apache.cayenne.PersistentObject
  - - org.apache.cayenne.CayenneDataObject

- All Implemented Interfaces:
    Serializable, DataObject, Persistent, Validating, XMLSerializable

      public class CayenneDataObject
      extends PersistentObject
      implements DataObject, Validating, XMLSerializable

  A default implementation of DataObject interface. It is normally used as a superclass of Cayenne persistent objects.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected long` | `snapshotVersion`
    `protected Map<String,Object>` | `values`

    - ### Fields inherited from class org.apache.cayenne.PersistentObject

      `objectContext, objectId, persistenceState`

    - ### Fields inherited from interface org.apache.cayenne.DataObject

      `DEFAULT_VERSION`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CayenneDataObject()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addToManyTarget(String relName, DataObject value, boolean setReverse)` Adds an object to a to-many relationship.
    `protected void` | `appendProperties(StringBuffer buffer)`
    `void` | `decodeFromXML(XMLDecoder decoder)` Deprecated. since 3.1 XML serialization package is deprecated and will be removed in the following releases. It has a number of functional and performance limitations that make it impossible to evolve further. A replacement may be provided in an undefined future. For now we recommend the users to implement XML serialization of persistent objects based JAXB, XStream or other similar frameworks.
    `void` | `encodeAsXML(XMLEncoder encoder)` Deprecated. since 3.1 XML serialization package is deprecated and will be removed in the following releases. It has a number of functional and performance limitations that make it impossible to evolve further. A replacement may be provided in an undefined future. For now we recommend the users to implement XML serialization of persistent objects based JAXB, XStream or other similar frameworks.
    `long` | `getSnapshotVersion()` Returns a version of a DataRow snapshot that was used to create this object.
    `static String` | `makePath(String... pathParts)` Convenience method to invoke `Cayenne.makePath(String...)` from within a DataObject subclass to create a dotted path using the generated string constants for attributes and relationships.
    `Object` | `readNestedProperty(String path)` Returns a value of the property identified by a property path.
    `Object` | `readProperty(String propertyName)` Returns a value of the property identified by propName.
    `Object` | `readPropertyDirectly(String propName)` Returns mapped property value as curently stored in the DataObject.
    `void` | `removeToManyTarget(String relName, DataObject value, boolean setReverse)` Removes an object from a to-many relationship.
    `void` | `setObjectContext(ObjectContext objectContext)`
    `void` | `setPersistenceState(int persistenceState)`
    `protected void` | `setReverseRelationship(String relName, DataObject val)` Initializes reverse relationship from object `val` to this object.
    `void` | `setSnapshotVersion(long snapshotVersion)`
    `void` | `setToOneTarget(String relationshipName, DataObject value, boolean setReverse)` Sets to-one relationship to a new value.
    `String` | `toString()`
    `StringBuffer` | `toStringBuffer(StringBuffer buffer, boolean fullDesc)` A variation of "toString" method, that may be more efficient in some cases.
    `protected void` | `unsetReverseRelationship(String relName, DataObject val)` Removes current object from reverse relationship of object `val` to this object.
    `void` | `validateForDelete(ValidationResult validationResult)` This implementation does nothing.
    `void` | `validateForInsert(ValidationResult validationResult)` Calls `validateForSave(ValidationResult)`.
    `protected void` | `validateForSave(ValidationResult validationResult)` Performs property validation of the object, appending any validation failures to the provided validationResult object.
    `void` | `validateForUpdate(ValidationResult validationResult)` Calls `validateForSave(ValidationResult)`.
    `protected void` | `willConnect(String relationshipName, Persistent object)` Called before establishing a relationship with another object.
    `void` | `writeProperty(String propName, Object val)` Sets the property to the new value.
    `void` | `writePropertyDirectly(String propName, Object val)` Modifies a value of a named property without altering the object state in any way, and without triggering any database operations.

    - ### Methods inherited from class org.apache.cayenne.PersistentObject

      `getMapKey, getObjectContext, getObjectId, getObjEntity, getPersistenceState, setObjectId`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.apache.cayenne.Persistent

      `getObjectContext, getObjectId, getPersistenceState, setObjectId`

- - ### Field Detail

    - #### snapshotVersion

          protected long snapshotVersion

    - #### values

          protected Map<String,Object> values

  - ### Constructor Detail

    - #### CayenneDataObject

          public CayenneDataObject()

  - ### Method Detail

    - #### setPersistenceState

          public void setPersistenceState(int persistenceState)

      Specified by:
        `setPersistenceState` in interface `Persistent`
      Overrides:
        `setPersistenceState` in class `PersistentObject`

    - #### 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 names = (List)artist.readNestedProperty("paintingArray.paintingName");`
      Specified by:
        `readNestedProperty` in interface `DataObject`
      Since:
        1.0.5

    - #### readProperty

          public Object readProperty(String propertyName)

      Description copied from interface: `DataObject`
      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 CayenneDataObject.
      Specified by:
        `readProperty` in interface `DataObject`

    - #### readPropertyDirectly

          public Object readPropertyDirectly(String propName)

      Description copied from interface: `DataObject`
      Returns mapped property value as curently stored in the DataObject. 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 `DataObject`

    - #### writeProperty

          public void writeProperty(String propName,
                           Object val)

      Description copied from interface: `DataObject`
      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 `DataObject.setToOneTarget(String, DataObject, boolean)`.
      Specified by:
        `writeProperty` in interface `DataObject`
      Parameters:
        `propName` - a name of the bean property being modified.
        `val` - a new value of the property.

    - #### writePropertyDirectly

          public void writePropertyDirectly(String propName,
                                   Object val)

      Description copied from interface: `DataObject`
      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 `DataObject`

    - #### removeToManyTarget

          public void removeToManyTarget(String relName,
                                DataObject value,
                                boolean setReverse)

      Description copied from interface: `DataObject`
      Removes an object from a to-many relationship.
      Specified by:
        `removeToManyTarget` in interface `DataObject`

    - #### addToManyTarget

          public void addToManyTarget(String relName,
                             DataObject value,
                             boolean setReverse)

      Description copied from interface: `DataObject`
      Adds an object to a to-many relationship.
      Specified by:
        `addToManyTarget` in interface `DataObject`

    - #### setToOneTarget

          public void setToOneTarget(String relationshipName,
                            DataObject value,
                            boolean setReverse)

      Description copied from interface: `DataObject`
      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 `DataObject`
      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,
                                    DataObject 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,
                                      DataObject val)

      Removes current object from reverse relationship of object `val` to this object.

    - #### 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 `PersistentObject`

    - #### getSnapshotVersion

          public long getSnapshotVersion()

      Returns a version of a DataRow snapshot that was used to create this object.
      Specified by:
        `getSnapshotVersion` in interface `DataObject`
      Since:
        1.1

    - #### setSnapshotVersion

          public void setSnapshotVersion(long snapshotVersion)

      Specified by:
        `setSnapshotVersion` in interface `DataObject`
      Since:
        1.1

    - #### makePath

          public static String makePath(String... pathParts)

      Convenience method to invoke `Cayenne.makePath(String...)` from within a DataObject subclass to create a dotted path using the generated string constants for attributes and relationships.
      Since:
        3.1
      See Also:
        `Cayenne.makePath(String...)`

    - #### 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. CayenneDataObject subclasses may override this method, calling super.
      Since:
        1.1

    - #### validateForInsert

          public void validateForInsert(ValidationResult validationResult)

      Calls `validateForSave(ValidationResult)`. CayenneDataObject 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)`. CayenneDataObject 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. CayenneDataObject 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

    - #### encodeAsXML

          @Deprecated
          public void encodeAsXML(XMLEncoder encoder)

      Deprecated. since 3.1 XML serialization package is deprecated and will be removed in the following releases. It has a number of functional and performance limitations that make it impossible to evolve further. A replacement may be provided in an undefined future. For now we recommend the users to implement XML serialization of persistent objects based JAXB, XStream or other similar frameworks.
      Encodes object to XML using provided encoder.
      Specified by:
        `encodeAsXML` in interface `XMLSerializable`
      Parameters:
        `encoder` - The encoder object.
      Since:
        1.2

    - #### decodeFromXML

          @Deprecated
          public void decodeFromXML(XMLDecoder decoder)

      Deprecated. since 3.1 XML serialization package is deprecated and will be removed in the following releases. It has a number of functional and performance limitations that make it impossible to evolve further. A replacement may be provided in an undefined future. For now we recommend the users to implement XML serialization of persistent objects based JAXB, XStream or other similar frameworks.
      Description copied from interface: `XMLSerializable`
      Decodes itself from XML using the provided XMLDecoder.
      Specified by:
        `decodeFromXML` in interface `XMLSerializable`
      Parameters:
        `decoder` - The decoder object.

    - #### setObjectContext

          public void setObjectContext(ObjectContext objectContext)

      Specified by:
        `setObjectContext` in interface `Persistent`
      Overrides:
        `setObjectContext` in class `PersistentObject`
      Since:
        1.2

Copyright © 2001–2014 Apache Cayenne. All rights reserved.