org.apache.cayenne

Class BaseDataObject

java.lang.Object

org.apache.cayenne.PersistentObject

org.apache.cayenne.BaseDataObject

All Implemented Interfaces:

Serializable, DataObject, Persistent, Validating

Direct Known Subclasses:

CayenneDataObject, HybridDataObject

public abstract class BaseDataObject
extends PersistentObject
implements DataObject, Validating

Base implementation of DataObject, have no assumption about how data is actually stored.

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 (CayenneDataObject)
• mixed fields and generic Map to store runtime attributes (HybridDataObject)

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

To create own implementation of DataObject 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).

Since:

4.1

See Also:

CayenneDataObject, HybridDataObject, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected long	snapshotVersion

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
BaseDataObject()

Method Summary

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)
protected void	beforePropertyRead(String propName)
protected void	beforePropertyWrite(String propName, Object oldValue, Object newValue)
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	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.
protected void	readSerialized(ObjectInputStream in)
protected void	readState(ObjectInputStream in)
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)
List<? extends DataObject>	setToManyTarget(String relName, Collection<? extends DataObject> values, boolean setReverse) Sets the relationships to the specified DataObject objects.
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.
protected void	writeSerialized(ObjectOutputStream out)
protected void	writeState(ObjectOutputStream out)

Methods inherited from class org.apache.cayenne.PersistentObject

getMapKey, getObjectContext, getObjectId, 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

Constructor Detail

BaseDataObject

public BaseDataObject()

Method Detail

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

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

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: 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

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 DataObject

Since:

1.0.5

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.

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

setToManyTarget

public List<? extends DataObject> setToManyTarget(String relName,
                                                  Collection<? extends DataObject> values,
                                                  boolean setReverse)

Sets the relationships to the specified DataObject objects.

New relationships will be created with addToManyTarget(String, org.apache.cayenne.DataObject, boolean), already established relationships stay untouched. Missing relationships will be removed with removeToManyTarget(String, org.apache.cayenne.DataObject, boolean) and returnd 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.DataObject, boolean)

Parameters:

relName - name of the relation

values - DataObject 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 DataObject> of unrelated DataObjects. 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,
                           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.

setPersistenceState

public void setPersistenceState(int persistenceState)

Specified by:

setPersistenceState in interface Persistent

Overrides:

setPersistenceState in class PersistentObject

getSnapshotVersion

public long getSnapshotVersion()

Description copied from interface: DataObject

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

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

setObjectContext

public void setObjectContext(ObjectContext objectContext)

Specified by:

setObjectContext in interface Persistent

Overrides:

setObjectContext in class PersistentObject

Since:

1.2

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 PersistentObject