Storable (Carbonado 1.2.3 API)

+
+
All Known Subinterfaces:
+
StoredIndexInfo, StoredLayout, StoredLayoutEquivalence, 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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Methods
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. +

+ +
- + + +
  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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.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
    +
    java.lang.IllegalStateException - if the state of this instance suggests + that any primary keys are unspecified
    +
  + + + +
  - +
    storableType
    +
```
java.lang.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:
    +
    java.lang.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:
    +
    java.lang.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(java.lang.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:
    +
    java.lang.IllegalArgumentException - if property is unknown, is a join or is derived
    +
  + + + +
  - +
    isPropertyDirty
    +
```
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.
    +
    Parameters:
    propertyName - name of property to interrogate
    +
    Throws:
    +
    java.lang.IllegalArgumentException - if property is unknown, is a join or is derived
    +
  + + + +
  - +
    isPropertyClean
    +
```
boolean isPropertyClean(java.lang.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:
    +
    java.lang.IllegalArgumentException - if property is unknown, is a join or is derived
    +
  + + + +
  - +
    isPropertySupported
    +
```
boolean isPropertySupported(java.lang.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
    +
```
java.lang.Object getPropertyValue(java.lang.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:
    +
    java.lang.IllegalArgumentException - if property is unknown or if accessor + method declares throwing any checked exceptions
    +
    java.lang.UnsupportedOperationException - if property is independent but unsupported
    +
    java.lang.NullPointerException - if property name is null
    Since:
    +
    1.2
    +
  + + + +
  - +
    setPropertyValue
    +
```
void setPropertyValue(java.lang.String propertyName,
+                    java.lang.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:
    +
    java.lang.IllegalArgumentException - if property is unknown, or if value is + unsupported due to a constraint, or if mutator method declares throwing + any checked exceptions
    +
    java.lang.UnsupportedOperationException - if property is independent but unsupported
    +
    java.lang.ClassCastException - if value is of wrong type
    +
    java.lang.NullPointerException - if property name is null or if primitive + value is required but value is null
    Since:
    +
    1.2
    +
  + + + +
  - +
    propertyMap
    +
```
java.util.Map<java.lang.String,java.lang.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(java.io.OutputStream out)
+             throws java.io.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:
    +
    java.io.IOException - if exception from stream
    +
    SupportException - if Storable cannot be serialized
    Since:
    +
    1.2
    +
  + + + +
  - +
    readFrom
    +
```
void readFrom(java.io.InputStream in)
+              throws java.io.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:
    +
    java.io.IOException - if exception from stream
    +
    SupportException - if Storable cannot be serialized
    Since:
    +
    1.2
    +
  + + + +
  - +
    hashCode
    +
```
int hashCode()
```
    +
    +
    Overrides:
    +
    hashCode in class java.lang.Object
    +
    +
  + + + +
  - +
    equals
    +
```
boolean equals(java.lang.Object obj)
```
    +
    True if all properties and fields are equal, but ignoring the state.
    +
    +
    Overrides:
    +
    equals in class java.lang.Object
    +
    Parameters:
    obj - object to compare to for equality
    +
  + + + +
  - +
    equalPrimaryKeys
    +
```
boolean equalPrimaryKeys(java.lang.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(java.lang.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
    +
```
java.lang.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 java.lang.Object
    +
    +
  + + + +
  - +
    toStringKeyOnly
    +
```
java.lang.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.
    +
  +
+

Interface Storable<S extends Storable<S>>

Method Summary

Method Detail

load

tryLoad

insert

tryInsert

update

tryUpdate

delete

tryDelete

storableType

copyAllProperties

copyPrimaryKeyProperties

copyVersionProperty

copyUnequalProperties

copyDirtyProperties

hasDirtyProperties

markPropertiesClean

markAllPropertiesClean

markPropertiesDirty

markAllPropertiesDirty

isPropertyUninitialized

isPropertyDirty

isPropertyClean

isPropertySupported

getPropertyValue

setPropertyValue

propertyMap

copy

prepare

writeTo

readFrom

hashCode

equals

equalPrimaryKeys

equalProperties

toString

toStringKeyOnly