You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by re...@apache.org on 2017/05/31 13:21:40 UTC
svn commit: r1797034 - in /jackrabbit/oak/branches/1.4: ./
oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java
Author: reschke
Date: Wed May 31 13:21:40 2017
New Revision: 1797034
URL: http://svn.apache.org/viewvc?rev=1797034&view=rev
Log:
OAK-4771: Clarify exceptions in DocumentStore (ported to 1.4)
Modified:
jackrabbit/oak/branches/1.4/ (props changed)
jackrabbit/oak/branches/1.4/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java
Propchange: jackrabbit/oak/branches/1.4/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed May 31 13:21:40 2017
@@ -1,3 +1,3 @@
/jackrabbit/oak/branches/1.0:1665962
-/jackrabbit/oak/trunk:1733615,1733875,1733913,1733929,1734230,1734254,1734279,1734941,1735052,1735081,1735109,1735141,1735267,1735405,1735484,1735549,1735564,1735588,1735622,1735638,1735919,1735983,1736176,1737309-1737310,1737334,1737349,1737998,1738004,1738136,1738138,1738207,1738234,1738252,1738775,1738795,1738833,1738950,1738957,1738963,1739712,1739760,1739867,1739894,1739959-1739960,1740114,1740116,1740250,1740333,1740349,1740360,1740625-1740626,1740774,1740837,1740879,1740971,1741016,1741032,1741339,1741343,1742077,1742117,1742125,1742363,1742520,1742888,1742916,1743097,1743172,1743343,1743674,1744265,1744292,1744589,1744670,1744672,1744959,1745038,1745127,1745197,1745336,1745368,1746086,1746117,1746342,1746345,1746408,1746634,1746696,1746981,1747198,1747200,1747341-1747342,1747380,1747387,1747406,1747492,1747512,1747654,1748505,1748553,1748722,1748870,1749275,1749350,1749424,1749443,1749464,1749475,1749645,1749662,1749815,1749872,1749875,1749899,1750052,1750076-1750077,1750287
,1750457,1750462,1750465,1750495,1750626,1750809,1750886-1750887,1751396,1751410,1751419,1751445-1751446,1751478,1751748,1751753,1751755,1751871,1752198,1752202,1752259,1752273-1752274,1752283,1752292,1752438,1752447-1752448,1752508,1752596,1752616,1752659,1752672,1753262,1753331-1753332,1753335-1753336,1753355,1753444,1754117,1754239,1755157,1755191,1756505-1756506,1756520,1756580,1757119,1757166,1758213,1758713,1759433,1759795,1759826,1760326,1760340,1760373,1760387,1760486,1760492,1760494,1760661-1760662,1760677,1760701,1760709,1760946,1761412,1761444,1761571,1761762,1761787,1761866,1761876,1762453,1762612,1762632,1762635,1762825,1763347,1763355-1763356,1763378,1763465,1763735,1764678,1764705,1764814,1764898,1765817,1765983,1766071,1766390,1766423,1766496,1766519,1766554,1766644,1767025,1767265,1767502,1767704,1768446,1768637,1769078,1769939-1769940,1770694,1770982,1771022,1771093,1771098,1771739,1771852,1771870,1771902,1772155,1772162,1772228,1772593,1772768,1773190,1774497,1774
787,1775474,1775622,1775628,1775757,1778112,1778423,1778968,1779137,1779478,1780388,1780424,1780538,1780543,1781068,1781075,1781386,1781846,1781907,1782476,1782966,1783066,1783089,1783104-1783105,1783110,1783619,1783720,1783738,1783773,1783855,1783891,1784023,1784034,1784130,1784251,1784551,1784574,1784689,1785283,1785946,1787074,1787217,1787425,1789056,1792463,1792742,1793088,1793644,1795314,1795330,1795475,1795488,1795491,1795613,1795618,1796144
+/jackrabbit/oak/trunk:1733615,1733875,1733913,1733929,1734230,1734254,1734279,1734941,1735052,1735081,1735109,1735141,1735267,1735405,1735484,1735549,1735564,1735588,1735622,1735638,1735919,1735983,1736176,1737309-1737310,1737334,1737349,1737998,1738004,1738136,1738138,1738207,1738234,1738252,1738775,1738795,1738833,1738950,1738957,1738963,1739712,1739760,1739867,1739894,1739959-1739960,1740114,1740116,1740250,1740333,1740349,1740360,1740625-1740626,1740774,1740837,1740879,1740971,1741016,1741032,1741339,1741343,1742077,1742117,1742125,1742363,1742520,1742888,1742916,1743097,1743172,1743343,1743674,1744265,1744292,1744589,1744670,1744672,1744959,1745038,1745127,1745197,1745336,1745368,1746086,1746117,1746342,1746345,1746408,1746634,1746696,1746981,1747198,1747200,1747341-1747342,1747380,1747387,1747406,1747492,1747512,1747654,1748505,1748553,1748722,1748870,1749275,1749350,1749424,1749443,1749464,1749475,1749645,1749662,1749815,1749872,1749875,1749899,1750052,1750076-1750077,1750287
,1750457,1750462,1750465,1750495,1750626,1750809,1750886-1750887,1751396,1751410,1751419,1751445-1751446,1751478,1751748,1751753,1751755,1751871,1752198,1752202,1752259,1752273-1752274,1752283,1752292,1752438,1752447-1752448,1752508,1752596,1752616,1752659,1752672,1753262,1753331-1753332,1753335-1753336,1753355,1753444,1754117,1754239,1755157,1755191,1756505-1756506,1756520,1756580,1757119,1757166,1758213,1758713,1759433,1759754,1759795,1759826,1760326,1760340,1760373,1760387,1760486,1760492,1760494,1760661-1760662,1760677,1760701,1760709,1760946,1761412,1761444,1761571,1761762,1761787,1761866,1761876,1762453,1762612,1762632,1762635,1762825,1763347,1763355-1763356,1763378,1763465,1763735,1764678,1764705,1764814,1764898,1765817,1765983,1766071,1766390,1766423,1766496,1766519,1766554,1766644,1767025,1767265,1767502,1767704,1768446,1768637,1769078,1769939-1769940,1770694,1770982,1771022,1771093,1771098,1771739,1771852,1771870,1771902,1772155,1772162,1772228,1772593,1772768,1773190,1774
497,1774787,1775474,1775622,1775628,1775757,1778112,1778423,1778968,1779137,1779478,1780388,1780424,1780538,1780543,1781068,1781075,1781386,1781846,1781907,1782476,1782966,1783066,1783089,1783104-1783105,1783110,1783619,1783720,1783738,1783773,1783855,1783891,1784023,1784034,1784130,1784251,1784551,1784574,1784689,1785283,1785946,1787074,1787217,1787425,1789056,1792463,1792742,1793088,1793644,1795314,1795330,1795475,1795488,1795491,1795613,1795618,1796144
/jackrabbit/trunk:1345480
Modified: jackrabbit/oak/branches/1.4/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/branches/1.4/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java?rev=1797034&r1=1797033&r2=1797034&view=diff
==============================================================================
--- jackrabbit/oak/branches/1.4/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java (original)
+++ jackrabbit/oak/branches/1.4/oak-core/src/main/java/org/apache/jackrabbit/oak/plugins/document/DocumentStore.java Wed May 31 13:21:40 2017
@@ -36,10 +36,6 @@ import org.apache.jackrabbit.oak.plugins
* must not modify a document partially. Either the complete update operation is
* applied to a document or no modification is done at all.
* <p>
- * Even though none of the methods declare an exception, they will still throw
- * an implementation specific runtime exception when the operations fails (e.g.
- * an I/O error occurs).
- * <p>
* The key is the id of a document. Keys are opaque strings. All characters are
* allowed. Leading and trailing whitespace is allowed. For keys, the maximum
* length is 512 bytes in the UTF-8 representation (in the latest Unicode
@@ -58,9 +54,12 @@ public interface DocumentStore {
* @param collection the collection
* @param key the key
* @return the document, or null if not found
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@CheckForNull
- <T extends Document> T find(Collection<T> collection, String key);
+ <T extends Document> T find(Collection<T> collection, String key)
+ throws DocumentStoreException;
/**
* Get the document with the {@code key}. The implementation may serve the
@@ -77,9 +76,12 @@ public interface DocumentStore {
* @param key the key
* @param maxCacheAge the maximum age of the cached document (in ms)
* @return the document, or null if not found
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@CheckForNull
- <T extends Document> T find(Collection<T> collection, String key, int maxCacheAge);
+ <T extends Document> T find(Collection<T> collection, String key, int maxCacheAge)
+ throws DocumentStoreException;
/**
* Get a list of documents where the key is greater than a start value and
@@ -93,12 +95,14 @@ public interface DocumentStore {
* @param toKey the end value (excluding)
* @param limit the maximum number of entries to return (starting with the lowest key)
* @return the list (possibly empty)
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@Nonnull
<T extends Document> List<T> query(Collection<T> collection,
String fromKey,
String toKey,
- int limit);
+ int limit) throws DocumentStoreException;
/**
* Get a list of documents where the key is greater than a start value and
@@ -119,6 +123,8 @@ public interface DocumentStore {
* @param startValue the minimum value of the indexed property
* @param limit the maximum number of entries to return
* @return the list (possibly empty)
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@Nonnull
<T extends Document> List<T> query(Collection<T> collection,
@@ -126,44 +132,75 @@ public interface DocumentStore {
String toKey,
String indexedProperty,
long startValue,
- int limit);
+ int limit) throws DocumentStoreException;
/**
* Remove a document. This method does nothing if there is no document
* with the given key.
+ * <p>
+ * In case of a {@code DocumentStoreException}, the document with the given
+ * key may or may not have been removed from the store. It is the
+ * responsibility of the caller to check whether it still exists. The
+ * implementation however ensures that the result of the operation is
+ * properly reflected in the document cache. That is, an implementation
+ * could simply evict the document with the given key.
*
* @param <T> the document type
* @param collection the collection
* @param key the key
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
- <T extends Document> void remove(Collection<T> collection, String key);
+ <T extends Document> void remove(Collection<T> collection, String key)
+ throws DocumentStoreException;
/**
* Batch remove documents with given keys. Keys for documents that do not
* exist are simply ignored. If this method fails with an exception, then
* only some of the documents identified by {@code keys} may have been
* removed.
+ * <p>
+ * In case of a {@code DocumentStoreException}, the documents with the given
+ * keys may or may not have been removed from the store. It may also be
+ * possible that only some have been removed from the store. It is the
+ * responsibility of the caller to check which documents still exist. The
+ * implementation however ensures that the result of the operation is
+ * properly reflected in the document cache. That is, an implementation
+ * could simply evict documents with the given keys from the cache.
*
* @param <T> the document type
* @param collection the collection
* @param keys list of keys
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
- <T extends Document> void remove(Collection<T> collection, List<String> keys);
+ <T extends Document> void remove(Collection<T> collection, List<String> keys)
+ throws DocumentStoreException;
/**
* Batch remove documents with given keys and corresponding conditions. Keys
* for documents that do not exist are simply ignored. A document is only
- * removed if the corresponding conditions are met. If this method fails
- * with an exception, then only some of the documents may have been removed.
+ * removed if the corresponding conditions are met.
+ * <p>
+ * In case of a {@code DocumentStoreException}, the documents with the given
+ * keys may or may not have been removed from the store. It may also be
+ * possible that only some have been removed from the store. It is the
+ * responsibility of the caller to check which documents still exist. The
+ * implementation however ensures that the result of the operation is
+ * properly reflected in the document cache. That is, an implementation
+ * could simply evict documents with the given keys from the cache.
*
* @param <T> the document type
* @param collection the collection.
* @param toRemove the keys of the documents to remove with the
* corresponding conditions.
* @return the number of removed documents.
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
<T extends Document> int remove(Collection<T> collection,
- Map<String, Map<UpdateOp.Key, UpdateOp.Condition>> toRemove);
+ Map<String, Map<UpdateOp.Key, UpdateOp.Condition>> toRemove)
+ throws DocumentStoreException;
/**
* Try to create a list of documents. This method returns {@code true} iff
@@ -173,24 +210,32 @@ public interface DocumentStore {
* An implementation does not have to guarantee an atomic create of all the
* documents described in the {@code updateOps}. It is the responsibility of
* the caller to check, which documents were created and take appropriate
- * action. The same is true when this method throws an exception (e.g. when
- * a communication error occurs). In this case only some documents may have
- * been created.
+ * action. The same is true when this method throws
+ * {@code DocumentStoreException} (e.g. when a communication error occurs).
+ * In this case only some documents may have been created.
*
* @param <T> the document type
* @param collection the collection
* @param updateOps the list of documents to add (where {@link Condition}s are not allowed)
* @return true if this worked (if none of the documents already existed)
* @throws IllegalArgumentException when at least one of the {@linkplain UpdateOp}s is conditional
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
- <T extends Document> boolean create(Collection<T> collection, List<UpdateOp> updateOps);
+ <T extends Document> boolean create(Collection<T> collection,
+ List<UpdateOp> updateOps)
+ throws IllegalArgumentException, DocumentStoreException;
/**
* Update documents with the given keys. Only existing documents are
- * updated and keys for documents that do not exist are simply ignored. If
- * this method fails with an exception, then only some of the documents
- * identified by {@code keys} may have been updated. There is no guarantee
- * in which sequence the updates are performed.
+ * updated and keys for documents that do not exist are simply ignored.
+ * There is no guarantee in which sequence the updates are performed.
+ * <p>
+ * If this method fails with a {@code DocumentStoreException}, then only some
+ * of the documents identified by {@code keys} may have been updated. The
+ * implementation however ensures that the result of the operation is
+ * properly reflected in the document cache. That is, an implementation
+ * could simply evict documents with the given keys from the cache.
*
* @param <T> the document type.
* @param collection the collection.
@@ -198,32 +243,51 @@ public interface DocumentStore {
* @param updateOp the update operation to apply to each of the documents
* (where {@link Condition}s are not allowed)
* @throws IllegalArgumentException when the {@linkplain UpdateOp} is conditional
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
<T extends Document> void update(Collection<T> collection,
List<String> keys,
- UpdateOp updateOp);
+ UpdateOp updateOp)
+ throws IllegalArgumentException, DocumentStoreException;
/**
- * Create or update a document. For MongoDB, this is using "findAndModify" with
- * the "upsert" flag (insert or update). The returned document is immutable.
+ * Atomically checks if the document exists and updates it, otherwise the
+ * document is created (aka upsert). The returned document is immutable.
+ * <p>
+ * If this method fails with a {@code DocumentStoreException}, then the
+ * document may or may not have been created or updated. It is the
+ * responsibility of the caller to check the result e.g. by calling
+ * {@link #find(Collection, String)}. The implementation however ensures
+ * that the result of the operation is properly reflected in the document
+ * cache. That is, an implementation could simply evict documents with the
+ * given keys from the cache.
*
* @param <T> the document type
* @param collection the collection
* @param update the update operation (where {@link Condition}s are not allowed)
* @return the old document or <code>null</code> if it didn't exist before.
* @throws IllegalArgumentException when the {@linkplain UpdateOp} is conditional
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@CheckForNull
- <T extends Document> T createOrUpdate(Collection<T> collection, UpdateOp update);
+ <T extends Document> T createOrUpdate(Collection<T> collection,
+ UpdateOp update)
+ throws IllegalArgumentException, DocumentStoreException;
/**
- * Create or unconditionally update a number of documents.
+ * Create or unconditionally update a number of documents. An implementation
+ * does not have to guarantee that all changes are applied atomically,
+ * together.
* <p>
- * An implementation does not have to guarantee that all changes are applied
- * atomically, together. In case of an exception (e.g. when a communication
- * error occurs) only some changes may have been applied. In this case it is the
- * responsibility of the caller to check which {@linkplain UpdateOp}s were applied and
- * take appropriate action.
+ * In case of a {@code DocumentStoreException} (e.g. when a communication
+ * error occurs) only some changes may have been applied. In this case it is
+ * the responsibility of the caller to check which {@linkplain UpdateOp}s
+ * were applied and take appropriate action. The implementation however
+ * ensures that the result of the operations are properly reflected in the
+ * document cache. That is, an implementation could simply evict documents
+ * related to the given update operations from the cache.
*
* @param <T> the document type
* @param collection the collection
@@ -231,23 +295,39 @@ public interface DocumentStore {
* @return the list containing old documents or <code>null</code> values if they didn't exist
* before (see {@linkplain #createOrUpdate(Collection, UpdateOp)}), where the order
* reflects the order in the "updateOps" parameter
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
- <T extends Document> List<T> createOrUpdate(Collection<T> collection, List<UpdateOp> updateOps);
+ <T extends Document> List<T> createOrUpdate(Collection<T> collection,
+ List<UpdateOp> updateOps)
+ throws DocumentStoreException;
/**
* Performs a conditional update (e.g. using
* {@link UpdateOp.Condition.Type#EXISTS} and only updates the
* document if the condition is <code>true</code>. The returned document is
* immutable.
+ * <p>
+ * In case of a {@code DocumentStoreException} (e.g. when a communication
+ * error occurs) the update may or may not have been applied. In this case
+ * it is the responsibility of the caller to check whether the update was
+ * applied and take appropriate action. The implementation however ensures
+ * that the result of the operation is properly reflected in the document
+ * cache. That is, an implementation could simply evict the document related
+ * to the given update operation from the cache.
*
* @param <T> the document type
* @param collection the collection
* @param update the update operation with the condition
* @return the old document or <code>null</code> if the condition is not met or
* if the document wasn't found
+ * @throws DocumentStoreException if the operation failed. E.g. because of
+ * an I/O error.
*/
@CheckForNull
- <T extends Document> T findAndUpdate(Collection<T> collection, UpdateOp update);
+ <T extends Document> T findAndUpdate(Collection<T> collection,
+ UpdateOp update)
+ throws DocumentStoreException;
/**
* Invalidate the document cache. Calling this method instructs the
@@ -337,13 +417,17 @@ public interface DocumentStore {
Map<String, String> getMetadata();
/**
- * @return the estimated time difference in milliseconds between
- * the local instance and the (typically common, shared) document server system.
- * The value can be zero if the times are estimated to be equal,
- * positive when the local instance is ahead of the remote server
- * and negative when the local instance is behind the remote server. An invocation is not cached
- * and typically requires a round-trip to the server (but that is not a requirement).
- * @throws UnsupportedOperationException if this DocumentStore does not support this method
+ * @return the estimated time difference in milliseconds between the local
+ * instance and the (typically common, shared) document server system. The
+ * value can be zero if the times are estimated to be equal, positive when
+ * the local instance is ahead of the remote server and negative when the
+ * local instance is behind the remote server. An invocation is not cached
+ * and typically requires a round-trip to the server (but that is not a
+ * requirement).
+ * @throws UnsupportedOperationException if this DocumentStore does not
+ * support this method
+ * @throws DocumentStoreException if an I/O error occurs.
*/
- long determineServerTimeDifferenceMillis();
+ long determineServerTimeDifferenceMillis()
+ throws UnsupportedOperationException, DocumentStoreException;
}