com.amazon.carbonado
Interface Storable<S extends Storable<S>>

All Known Subinterfaces:

StoredIndexInfo, StoredLayout, StoredLayoutProperty, StoredSequence, StoredSequence

All Known Implementing Classes:

StoredDatabaseInfo, StoredLob, StoredLob.Block

public interface Storable<S extends Storable<S>>

A data access object in a Repository. User defined storables must either extend or implement this interface via an interface or abstract class. Abstract bean properties defined in the storable are persisted into the repository. At least one property must be annotated as the PrimaryKey. At most one property may be annotated as being the Version property.

Storable instances are mutable, but they must be thread-safe. Although race conditions are possible if multiple threads are mutating the Storable, the Storable instance will not get into a corrupt state.

Author:

Brian S O'Neill, Don Schneider

See Also:

Alias, Indexes, Join, Nullable, PrimaryKey, Version

Method Summary

S	copy() Returns an exact shallow copy of this object, including the state.
void	copyAllProperties(S target) Copies all supported properties, skipping any that are uninitialized.
void	copyDirtyProperties(S target) Copies all supported non-primary key properties which are dirty.
void	copyPrimaryKeyProperties(S target) Copies all supported primary key properties, skipping any that are uninitialized.
void	copyUnequalProperties(S target) Copies all supported non-primary key properties which are unequal, skipping any that are uninitialized.
void	copyVersionProperty(S target) Copies the optional version property, unless it is uninitialized.
void	delete() Deletes this object from the storage layer by its primary key, regardless of whether this object has actually been loaded or not.
boolean	equalPrimaryKeys(Object obj) True if the supported properties which participate in the primary key are equal.
boolean	equalProperties(Object obj) True if all supported properties for this object are equal.
boolean	equals(Object obj) True if all properties and fields are equal, but ignoring the state.
Object	getPropertyValue(String propertyName) Returns a Storable property value by name.
boolean	hasDirtyProperties() Returns true if any non-primary key properties in this object are dirty.
int	hashCode()
void	insert() Inserts a new persistent value for this object.
boolean	isPropertyClean(String propertyName) Returns true if the given property of this Storable is clean.
boolean	isPropertyDirty(String propertyName) Returns true if the given property of this Storable has been set, but no load or store operation has been performed yet.
boolean	isPropertySupported(String propertyName) Returns true if the given property exists and is supported.
boolean	isPropertyUninitialized(String propertyName) Returns true if the given property of this Storable has never been loaded or set.
void	load() Loads or reloads this object from the storage layer by a primary or alternate key.
void	markAllPropertiesClean() Marks all properties as clean, including uninitialized properties.
void	markAllPropertiesDirty() Marks all properties as dirty, including uninitialized properties.
void	markPropertiesClean() Marks all dirty properties as clean.
void	markPropertiesDirty() Marks all clean properties as dirty.
S	prepare() Prepares a new object for loading, inserting, updating, or deleting.
Map<String,Object>	propertyMap() Returns a fixed-size map view of this Storable's properties.
void	readFrom(InputStream in) Restores property values and states as encoded by writeTo(java.io.OutputStream).
void	setPropertyValue(String propertyName, Object value) Sets a Storable property value by name.
Class<S>	storableType() Returns the class or interface from which this storable was generated.
String	toString() Returns a string for debugging purposes that contains all supported property names and values for this object.
String	toStringKeyOnly() Returns a string for debugging purposes that contains supported key property names and values for this object.
boolean	tryDelete() Deletes this object from the storage layer by its primary key, regardless of whether this object has actually been loaded or not.
boolean	tryInsert() Inserts a new persistent value for this object.
boolean	tryLoad() Loads or reloads this object from the storage layer by a primary or alternate key.
boolean	tryUpdate() Updates the persistent value of this object, regardless of whether this object has actually been loaded or not.
void	update() Updates the persistent value of this object, regardless of whether this object has actually been loaded or not.
void	writeTo(OutputStream out) Serializes property values and states for temporary storage or for network transfer.

Method Detail

load

void load()
          throws FetchNoneException,
                 FetchException

Loads or reloads this object from the storage layer by a primary or alternate key. All properties of a key must be initialized for it to be chosen. The primary key is examined first, and if not fully initialized, alternate keys are examined in turn.

If load is successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

Note: This method differs from tryLoad() only in that it throws an exception if no matching record was found, instead of returning false. This may indicate that the underlying record was deleted between a load and reload. When a FetchNoneException is thrown, this object's state will be the same as if the delete method was called on it.

Throws:

FetchNoneException - if no matching record found

FetchException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

tryLoad

boolean tryLoad()
                throws FetchException

Loads or reloads this object from the storage layer by a primary or alternate key. All properties of a key must be initialized for it to be chosen. The primary key is examined first, and if not fully initialized, alternate keys are examined in turn.

If load is successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

Note: This method differs from load() only in that it returns false if no matching record was found, instead of throwing an exception. This may indicate that the underlying record was deleted between a load and reload. When false is returned, this object's state will be the same as if the delete method was called on it.

Returns:

true if found and loaded, false otherwise

Throws:

FetchException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

insert

void insert()
            throws PersistException

Inserts a new persistent value for this object. If successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

Insert requires that all primary key properties be specified. If not, an IllegalStateException is thrown. Also, repository implementations usually require that properties which are not Nullable also be specified. Otherwise, a ConstraintException may be thrown.

Note: This method differs from tryInsert() only in that it may throw a UniqueConstraintException, instead of returning false.

Throws:

UniqueConstraintException - if it is absolutely known that a key of inserted object matches an existing one

ConstraintException - if any required properties are unspecified

PersistException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

tryInsert

boolean tryInsert()
                  throws PersistException

Inserts a new persistent value for this object. If successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

Insert requires that all primary key properties be specified. If not, an IllegalStateException is thrown. Also, repository implementations usually require that properties which are not Nullable also be specified. Otherwise, a ConstraintException may be thrown.

Note: This method differs from insert() only in that it returns false, instead of throwing a UniqueConstraintException.

Returns:

false if it is absolutely known that a key of inserted object matches an existing one

Throws:

ConstraintException - if any required properties are unspecified

PersistException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

update

void update()
            throws PersistException

Updates the persistent value of this object, regardless of whether this object has actually been loaded or not. If successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

If this object has a version property defined, then the update logic is a bit more strict. Updates of any storable require that the primary keys be specified; if a version is present, the version must be specified as well. If any of the primary key or version properties are unspecified, an IllegalStateException will be thrown; if they are fully specified and the version doesn't match the current record, an OptimisticLockException is thrown.

Not all properties need to be set on this object when calling update. Setting a subset results in a partial update. After a successful update, all properties are set to the actual values in the storage layer. Put another way, the object is automatically reloaded after a successful update.

If PersistNoneException is thrown, this indicates that the underlying record was deleted. When this happens, this object's state will be the same as if the delete method was called on it.

Throws:

PersistNoneException - if record is missing and no update occurred

PersistException - if storage layer throws an exception

OptimisticLockException - if a version property exists and the optimistic lock failed

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified, or if a version property is unspecified

tryUpdate

boolean tryUpdate()
                  throws PersistException

Updates the persistent value of this object, regardless of whether this object has actually been loaded or not. If successful, altering the primary key is no longer allowed unless a call to delete succeeds. Attempting to alter the primary key in this state results in an IllegalStateException. Alternate keys may always be modified, however.

If this object has a version property defined, then the update logic is a bit more strict. Updates of any storable require that the primary keys be specified; if a version is present, the version must be specified as well. If any of the primary key or version properties are unspecified, an IllegalStateException will be thrown; if they are fully specified and the version doesn't match the current record, an OptimisticLockException is thrown.

Not all properties need to be set on this object when calling update. Setting a subset results in a partial update. After a successful update, all properties are set to the actual values in the storage layer. Put another way, the object is automatically reloaded after a successful update.

A return value of false indicates that the underlying record was deleted. When this happens, this object's state will be the same as if the delete method was called on it.

Returns:

true if record likely exists and was updated, or false if record absolutely no longer exists and no update occurred

Throws:

PersistException - if storage layer throws an exception

OptimisticLockException - if a version property exists and the optimistic lock failed

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified, or if a version property is unspecified

delete

void delete()
            throws PersistException

Deletes this object from the storage layer by its primary key, regardless of whether this object has actually been loaded or not. Calling delete does not prevent this object from being used again. All property values are still valid, including the primary key. Once deleted, the insert operation is permitted again.

Note: This method differs from tryDelete() only in that it may throw a PersistNoneException, instead of returning false.

Throws:

PersistNoneException - if record is missing and nothing was deleted

PersistException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

tryDelete

boolean tryDelete()
                  throws PersistException

Deletes this object from the storage layer by its primary key, regardless of whether this object has actually been loaded or not. Calling delete does not prevent this object from being used again. All property values are still valid, including the primary key. Once deleted, the insert operation is permitted again.

Note: This method differs from delete() only in that it returns false, instead of throwing a PersistNoneException.

Returns:

true if record likely existed and was deleted, or false if record absolutely no longer exists and no delete was necessary

Throws:

PersistException - if storage layer throws an exception

IllegalStateException - if the state of this instance suggests that any primary keys are unspecified

storableType

Class<S> storableType()

Returns the class or interface from which this storable was generated. This represents the data class for the storable.

Design note: the name "getStorableType" is avoided, so as not to conflict with a user defined property of "storableType"

copyAllProperties

void copyAllProperties(S target)

Copies all supported properties, skipping any that are uninitialized. Specifically, calls "target.set<property>" for all supported properties in this storable, passing the value of the property from this object. Unsupported independent properties in this or the target are not copied.

Parameters:

target - storable on which to call set<property> methods

Throws:

IllegalStateException - if any primary key properties of target cannot be altered

copyPrimaryKeyProperties

void copyPrimaryKeyProperties(S target)

Copies all supported primary key properties, skipping any that are uninitialized. Specifically, calls "target.set<property>" for all supported properties which participate in the primary key, passing the value of the property from this object. Unsupported independent properties in this or the target are not copied.

Parameters:

target - storable on which to call set<property> methods

Throws:

IllegalStateException - if any primary key properties of target cannot be altered

copyVersionProperty

void copyVersionProperty(S target)

Copies the optional version property, unless it is uninitialized. Specifically, calls "target.set<property>" for the version property (if supported), passing the value of the property from this object. If no version property is defined, then this method does nothing. Unsupported independent properties in this or the target are not copied.

Parameters:

target - storable on which to call set<property> method

copyUnequalProperties

void copyUnequalProperties(S target)

Copies all supported non-primary key properties which are unequal, skipping any that are uninitialized. Specifically, calls "target.get<property>", and if the value thus retrieved differs from the local value, "target.set<property>" is called for that property. Unsupported independent properties in this or the target are not copied.

Parameters:

target - storable on which to call set<property> methods

copyDirtyProperties

void copyDirtyProperties(S target)

Copies all supported non-primary key properties which are dirty. Specifically, calls "target.set<property>" for any non-primary key property which is dirty, passing the value of the property from this object. A property is considered dirty when set before a load or persist operation is called. Unsupported independent properties in this or the target are not copied.

Parameters:

target - storable on which to call set<property> methods

hasDirtyProperties

boolean hasDirtyProperties()

Returns true if any non-primary key properties in this object are dirty. A property is considered dirty when set before a load or persist operation is called. A property becomes clean after a successful load, insert, or update operation.

markPropertiesClean

void markPropertiesClean()

Marks all dirty properties as clean. Uninitialized properties remain so. As a side-effect, initialized primary keys may no longer be altered.

markAllPropertiesClean

void markAllPropertiesClean()

Marks all properties as clean, including uninitialized properties. As a side-effect, primary keys may no longer be altered.

markPropertiesDirty

void markPropertiesDirty()

Marks all clean properties as dirty. Uninitialized properties remain so. As a side-effect, primary keys can be altered.

markAllPropertiesDirty

void markAllPropertiesDirty()

Marks all properties as dirty, including uninitialized properties. As a side-effect, primary keys can be altered.

isPropertyUninitialized

boolean isPropertyUninitialized(String propertyName)

Returns true if the given property of this Storable has never been loaded or set.

Parameters:

propertyName - name of property to interrogate

Throws:

IllegalArgumentException - if property is unknown, is a join or is derived

isPropertyDirty

boolean isPropertyDirty(String propertyName)

Returns true if the given property of this Storable has been set, but no load or store operation has been performed yet.

Parameters:

propertyName - name of property to interrogate

Throws:

IllegalArgumentException - if property is unknown, is a join or is derived

isPropertyClean

boolean isPropertyClean(String propertyName)

Returns true if the given property of this Storable is clean. All properties are clean after a successful load or store operation.

Parameters:

propertyName - name of property to interrogate

Throws:

IllegalArgumentException - if property is unknown, is a join or is derived

isPropertySupported

boolean isPropertySupported(String propertyName)

Returns true if the given property exists and is supported. If a Storable has an Independent property which is not supported by the repository, then this method returns false.

Parameters:

propertyName - name of property to check

getPropertyValue

Object getPropertyValue(String propertyName)

Returns a Storable property value by name.

Parameters:

propertyName - name of property to get value of

Returns:

property value, which is boxed if property type is primitive

Throws:

IllegalArgumentException - if property is unknown or if accessor method declares throwing any checked exceptions

UnsupportedOperationException - if property is independent but unsupported

NullPointerException - if property name is null

Since:

1.2

setPropertyValue

void setPropertyValue(String propertyName,
                      Object value)

Sets a Storable property value by name. Call insert or update to persist the change.

Parameters:

propertyName - name of property to set value to

value - new value for property

Throws:

IllegalArgumentException - if property is unknown, or if value is unsupported due to a constraint, or if mutator method declares throwing any checked exceptions

UnsupportedOperationException - if property is independent but unsupported

ClassCastException - if value is of wrong type

NullPointerException - if property name is null or if primitive value is required but value is null

Since:

1.2

propertyMap

Map<String,Object> propertyMap()

Returns a fixed-size map view of this Storable's properties. Properties which declare throwing any checked exceptions are excluded from the map. Removing and adding of map entries is unsupported.

Returns:

map of property name to property value; primitive property values are boxed

Since:

1.2

copy

S copy()

Returns an exact shallow copy of this object, including the state.

prepare

S prepare()

Prepares a new object for loading, inserting, updating, or deleting.

Since:

1.2

See Also:

Storage.prepare()

writeTo

void writeTo(OutputStream out)
             throws IOException,
                    SupportException

Serializes property values and states for temporary storage or for network transfer. Call readFrom(java.io.InputStream) to restore. Derived and join properties are not serialized.

The encoding used by this method is much simpler than what is provided by standard object serialization. It does not encode class info or property names, which is why it is not suitable for long term storage.

Throws:

IOException - if exception from stream

SupportException - if Storable cannot be serialized

Since:

1.2

readFrom

void readFrom(InputStream in)
              throws IOException,
                     SupportException

Restores property values and states as encoded by writeTo(java.io.OutputStream). Derived properties are not directly modified, but all other properties not restored are reset to their initial state.

Throws:

IOException - if exception from stream

SupportException - if Storable cannot be serialized

Since:

1.2

hashCode

int hashCode()

Overrides:

hashCode in class Object

equals

boolean equals(Object obj)

True if all properties and fields are equal, but ignoring the state.

Overrides:

equals in class Object

Parameters:

obj - object to compare to for equality

equalPrimaryKeys

boolean equalPrimaryKeys(Object obj)

True if the supported properties which participate in the primary key are equal. This is useful to cheaply investigate if two storables refer to the same entity, regardless of the state of object (specifically the non-key properties). Unsupported independent properties in this or the target are not compared.

Parameters:

obj - object to compare to for equality

equalProperties

boolean equalProperties(Object obj)

True if all supported properties for this object are equal. Unsupported independent properties in this or the target are not compared.

Parameters:

obj - object to compare to for equality

toString

String toString()

Returns a string for debugging purposes that contains all supported property names and values for this object. Uninitialized and unsupported independent properties are not included.

Overrides:

toString in class Object

toStringKeyOnly

String toStringKeyOnly()

Returns a string for debugging purposes that contains supported key property names and values for this object. Uninitialized and unsupported independent properties are not included.