public interface Storable<S extends Storable<S>>
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.
Modifier and Type | Method and Description |
---|---|
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(java.lang.Object obj)
True if the supported properties which participate in the primary key
are equal.
|
boolean |
equalProperties(java.lang.Object obj)
True if all supported properties for this object are equal.
|
boolean |
equals(java.lang.Object obj)
True if all properties and fields are equal, but ignoring the state.
|
java.lang.Object |
getPropertyValue(java.lang.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(java.lang.String propertyName)
Returns true if the given property of this Storable is clean.
|
boolean |
isPropertyDirty(java.lang.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(java.lang.String propertyName)
Returns true if the given property exists and is supported.
|
boolean |
isPropertyUninitialized(java.lang.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.
|
java.util.Map<java.lang.String,java.lang.Object> |
propertyMap()
Returns a fixed-size map view of this Storable's properties.
|
void |
readFrom(java.io.InputStream in)
Restores property values and states as encoded by
writeTo(java.io.OutputStream) . |
void |
setPropertyValue(java.lang.String propertyName,
java.lang.Object value)
Sets a Storable property value by name.
|
java.lang.Class<S> |
storableType()
Returns the class or interface from which this storable was
generated.
|
java.lang.String |
toString()
Returns a string for debugging purposes that contains all supported
property names and values for this object.
|
java.lang.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(java.io.OutputStream out)
Serializes property values and states for temporary storage or for
network transfer.
|
void load() throws FetchNoneException, FetchException
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.
FetchNoneException
- if no matching record foundFetchException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedboolean tryLoad() throws FetchException
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.
FetchException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedvoid insert() throws PersistException
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.
UniqueConstraintException
- if it is absolutely known that a key
of inserted object matches an existing oneConstraintException
- if any required properties are unspecifiedPersistException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedboolean tryInsert() throws PersistException
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.
ConstraintException
- if any required properties are unspecifiedPersistException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedvoid update() throws PersistException
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.
PersistNoneException
- if record is missing and no update occurredPersistException
- if storage layer throws an exceptionOptimisticLockException
- if a version property exists and the
optimistic lock failedjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecified, or if a version property is unspecifiedboolean tryUpdate() throws PersistException
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.
PersistException
- if storage layer throws an exceptionOptimisticLockException
- if a version property exists and the
optimistic lock failedjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecified, or if a version property is unspecifiedvoid delete() throws PersistException
Note: This method differs from tryDelete()
only in that it may
throw a PersistNoneException, instead of returning false.
PersistNoneException
- if record is missing and nothing was
deletedPersistException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedboolean tryDelete() throws PersistException
Note: This method differs from delete()
only in that it
returns false, instead of throwing a PersistNoneException.
PersistException
- if storage layer throws an exceptionjava.lang.IllegalStateException
- if the state of this instance suggests
that any primary keys are unspecifiedjava.lang.Class<S> storableType()
Design note: the name "getStorableType" is avoided, so as not to conflict with a user defined property of "storableType"
void copyAllProperties(S target)
independent
properties in this
or the target are not copied.target
- storable on which to call set<property> methodsjava.lang.IllegalStateException
- if any primary key properties of target
cannot be alteredvoid copyPrimaryKeyProperties(S target)
independent
properties in this or the target are not copied.target
- storable on which to call set<property> methodsjava.lang.IllegalStateException
- if any primary key properties of target
cannot be alteredvoid copyVersionProperty(S target)
independent
properties in this
or the target are not copied.target
- storable on which to call set<property> methodvoid copyUnequalProperties(S target)
independent
properties in this
or the target are not copied.target
- storable on which to call set<property> methodsvoid copyDirtyProperties(S target)
independent
properties in this or the target are not
copied.target
- storable on which to call set<property> methodsboolean hasDirtyProperties()
void markPropertiesClean()
void markAllPropertiesClean()
void markPropertiesDirty()
void markAllPropertiesDirty()
boolean isPropertyUninitialized(java.lang.String propertyName)
propertyName
- name of property to interrogatejava.lang.IllegalArgumentException
- if property is unknown, is a join or is derivedboolean isPropertyDirty(java.lang.String propertyName)
propertyName
- name of property to interrogatejava.lang.IllegalArgumentException
- if property is unknown, is a join or is derivedboolean isPropertyClean(java.lang.String propertyName)
propertyName
- name of property to interrogatejava.lang.IllegalArgumentException
- if property is unknown, is a join or is derivedboolean isPropertySupported(java.lang.String propertyName)
Independent
property which is not supported by
the repository, then this method returns false.propertyName
- name of property to checkjava.lang.Object getPropertyValue(java.lang.String propertyName)
propertyName
- name of property to get value ofjava.lang.IllegalArgumentException
- if property is unknown or if accessor
method declares throwing any checked exceptionsjava.lang.UnsupportedOperationException
- if property is independent but unsupportedjava.lang.NullPointerException
- if property name is nullvoid setPropertyValue(java.lang.String propertyName, java.lang.Object value)
propertyName
- name of property to set value tovalue
- new value for propertyjava.lang.IllegalArgumentException
- if property is unknown, or if value is
unsupported due to a constraint, or if mutator method declares throwing
any checked exceptionsjava.lang.UnsupportedOperationException
- if property is independent but unsupportedjava.lang.ClassCastException
- if value is of wrong typejava.lang.NullPointerException
- if property name is null or if primitive
value is required but value is nulljava.util.Map<java.lang.String,java.lang.Object> propertyMap()
S copy()
S prepare()
Storage.prepare()
void writeTo(java.io.OutputStream out) throws java.io.IOException, SupportException
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.
java.io.IOException
- if exception from streamSupportException
- if Storable cannot be serializedvoid readFrom(java.io.InputStream in) throws java.io.IOException, SupportException
writeTo(java.io.OutputStream)
.
Derived properties are not directly modified, but all other properties
not restored are reset to their initial state.java.io.IOException
- if exception from streamSupportException
- if Storable cannot be serializedint hashCode()
hashCode
in class java.lang.Object
boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- object to compare to for equalityboolean equalPrimaryKeys(java.lang.Object obj)
independent
properties in this or the target are not compared.obj
- object to compare to for equalityboolean equalProperties(java.lang.Object obj)
independent
properties in this or the target are not
compared.obj
- object to compare to for equalityjava.lang.String toString()
independent
properties are not included.toString
in class java.lang.Object
java.lang.String toStringKeyOnly()
independent
properties are not included.Copyright © 2006-2013 Amazon Technologies, Inc.. All Rights Reserved.