diff options
Diffstat (limited to 'src/main/java/com/amazon')
| -rw-r--r-- | src/main/java/com/amazon/carbonado/Storable.java | 64 |
1 files changed, 36 insertions, 28 deletions
diff --git a/src/main/java/com/amazon/carbonado/Storable.java b/src/main/java/com/amazon/carbonado/Storable.java index 20c7ab7..a9ebcf0 100644 --- a/src/main/java/com/amazon/carbonado/Storable.java +++ b/src/main/java/com/amazon/carbonado/Storable.java @@ -42,14 +42,18 @@ package com.amazon.carbonado; */
public interface Storable<S extends Storable<S>> {
/**
- * Loads or reloads this object from the storage layer by its primary
- * key. This object's primary key itself is never modified by calling
- * load. If load is successful, altering the primary key is no longer
- * allowed unless the object is deleted. Attempting to alter the primary
- * key in this state results in an {@link IllegalStateException}.
+ * 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.
+ *
+ * <p>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 {@link IllegalStateException}. Alternate keys
+ * may always be modified, however.
*
* <p>Note: This method differs from {@link #tryLoad} only in that it
- * throws an exception if no matching record was found instead of returning
+ * 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.
@@ -62,14 +66,18 @@ public interface Storable<S extends Storable<S>> { void load() throws FetchNoneException, FetchException;
/**
- * Loads or reloads this object from the storage layer by its primary
- * key. This object's primary key itself is never modified by calling
- * load. If load is successful, altering the primary key is no longer
- * allowed unless the object is deleted. Attempting to alter the primary
- * key in this state results in an {@link IllegalStateException}.
+ * 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.
+ *
+ * <p>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 {@link IllegalStateException}. Alternate keys
+ * may always be modified, however.
*
* <p>Note: This method differs from {@link #load} only in that it returns
- * false if no matching record was found instead of throwing an exception.
+ * 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.
@@ -83,9 +91,9 @@ public interface Storable<S extends Storable<S>> { /**
* Inserts a new persistent value for this object. If successful, altering
- * the primary key is no longer allowed unless the object is deleted.
- * Attempting to alter the primary key in this state results in an
- * {@link IllegalStateException}.
+ * 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 {@link
+ * IllegalStateException}. Alternate keys may always be modified, however.
*
* <p>Insert requires that all primary key properties be specified. If not,
* an {@link IllegalStateException} is thrown. Also, repository
@@ -94,7 +102,7 @@ public interface Storable<S extends Storable<S>> { * may be thrown.
*
* <p>Note: This method differs from {@link #tryInsert} only in that it may
- * throw a UniqueConstraintException instead of returning false.
+ * throw a UniqueConstraintException, instead of returning false.
*
* @throws UniqueConstraintException if it is absolutely known that a key
* of inserted object matches an existing one
@@ -107,9 +115,9 @@ public interface Storable<S extends Storable<S>> { /**
* Inserts a new persistent value for this object. If successful, altering
- * the primary key is no longer allowed unless the object is deleted.
- * Attempting to alter the primary key in this state results in an
- * {@link IllegalStateException}.
+ * 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 {@link
+ * IllegalStateException}. Alternate keys may always be modified, however.
*
* <p>Insert requires that all primary key properties be specified. If not,
* an {@link IllegalStateException} is thrown. Also, repository
@@ -118,7 +126,7 @@ public interface Storable<S extends Storable<S>> { * may be thrown.
*
* <p>Note: This method differs from {@link #insert} only in that it
- * returns false instead of throwing a UniqueConstraintException.
+ * returns false, instead of throwing a UniqueConstraintException.
*
* @return false if it is absolutely known that a key of inserted object
* matches an existing one
@@ -132,9 +140,9 @@ public interface Storable<S extends Storable<S>> { /**
* 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 the object is deleted.
- * Attempting to alter the primary key in this state results in an
- * {@link IllegalStateException}.
+ * primary key is no longer allowed unless a call to delete succeeds.
+ * Attempting to alter the primary key in this state results in an {@link
+ * IllegalStateException}. Alternate keys may always be modified, however.
*
* <p>If this object has a {@link Version version} property defined, then
* the update logic is a bit more strict. Updates of any storable require
@@ -166,9 +174,9 @@ public interface Storable<S extends Storable<S>> { /**
* 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 the object is deleted.
- * Attempting to alter the primary key in this state results in an
- * {@link IllegalStateException}.
+ * primary key is no longer allowed unless a call to delete succeeds.
+ * Attempting to alter the primary key in this state results in an {@link
+ * IllegalStateException}. Alternate keys may always be modified, however.
*
* <p>If this object has a {@link Version version} property defined, then
* the update logic is a bit more strict. Updates of any storable require
@@ -206,7 +214,7 @@ public interface Storable<S extends Storable<S>> { * deleted, the insert operation is permitted again.
*
* <p>Note: This method differs from {@link #tryDelete} only in that it may
- * throw a PersistNoneException instead of returning false.
+ * throw a PersistNoneException, instead of returning false.
*
* @throws PersistNoneException if record is missing and nothing was
* deleted
@@ -224,7 +232,7 @@ public interface Storable<S extends Storable<S>> { * deleted, the insert operation is permitted again.
*
* <p>Note: This method differs from {@link #delete} only in that it
- * returns false instead of throwing a PersistNoneException.
+ * returns false, instead of throwing a PersistNoneException.
*
* @return true if record likely existed and was deleted, or false if record
* absolutely no longer exists and no delete was necessary
|