org.apache.jackrabbit.oak.plugins.document

Interface DocumentStore

All Known Implementing Classes:

LeaseCheckDocumentStoreWrapper, LoggingDocumentStoreWrapper, MemoryDocumentStore, MongoDocumentStore, RDBDocumentStore, SynchronizingDocumentStoreWrapper, TimingDocumentStoreWrapper

public interface DocumentStore

The interface for the backend storage for documents.

In general atomicity of operations on a DocumentStore are limited to a single document. That is, an implementation does not have to guarantee atomicity of the entire effect of a method call. A method that fails with an exception may have modified just some documents and then abort. However, an implementation must not modify a document partially. Either the complete update operation is applied to a document or no modification is done at all.

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.

Method Summary

Modifier and Type	Method and Description
<T extends Document> boolean	create(Collection<T> collection, List<UpdateOp> updateOps) Try to create a list of documents.
<T extends Document> List<T>	createOrUpdate(Collection<T> collection, List<UpdateOp> updateOps) Create or unconditionally update a number of documents.
<T extends Document> T	createOrUpdate(Collection<T> collection, UpdateOp update) Atomically checks if the document exists and updates it, otherwise the document is created (aka upsert).
long	determineServerTimeDifferenceMillis()
void	dispose() Dispose this instance.
<T extends Document> T	find(Collection<T> collection, String key) Get the document with the given key.
<T extends Document> T	find(Collection<T> collection, String key, int maxCacheAge) Get the document with the key.
<T extends Document> T	findAndUpdate(Collection<T> collection, UpdateOp update) Performs a conditional update (e.g.
Iterable<CacheStats>	getCacheStats()
<T extends Document> T	getIfCached(Collection<T> collection, String key) Fetches the cached document.
Map<String,String>	getMetadata()
Map<String,String>	getStats() Returns statistics about the underlying storage.
CacheInvalidationStats	invalidateCache() Invalidate the document cache.
<T extends Document> void	invalidateCache(Collection<T> collection, String key) Invalidate the document cache for the given key.
CacheInvalidationStats	invalidateCache(Iterable<String> keys) Invalidate the document cache but only with entries that match one of the keys provided.
<T extends Document> List<T>	query(Collection<T> collection, String fromKey, String toKey, int limit) Get a list of documents where the key is greater than a start value and less than an end value.
<T extends Document> List<T>	query(Collection<T> collection, String fromKey, String toKey, String indexedProperty, long startValue, int limit) Get a list of documents where the key is greater than a start value and less than an end value and the given "indexed property" is greater or equals the specified value.
<T extends Document> void	remove(Collection<T> collection, List<String> keys) Batch remove documents with given keys.
<T extends Document> int	remove(Collection<T> collection, Map<String,Long> toRemove) Batch remove documents with given keys and corresponding equal conditions on NodeDocument.MODIFIED_IN_SECS values.
<T extends Document> void	remove(Collection<T> collection, String key) Remove a document.
<T extends Document> int	remove(Collection<T> collection, String indexedProperty, long startValue, long endValue) Batch remove documents where the given "indexed property" is within the given range (exclusive) - (startValue, endValue).
void	setReadWriteMode(String readWriteMode) Set the level of guarantee for read and write operations, if supported by this backend.

Method Detail

find

@CheckForNull
<T extends Document> T find(Collection<T> collection,
                                           String key)
                                    throws DocumentStoreException

Get the document with the given key. This is a convenience method and equivalent to find(Collection, String, int) with a maxCacheAge of Integer.MAX_VALUE.

The returned document is immutable.

Type Parameters:

T - the document type

Parameters:

collection - the collection

key - the key

Returns:

the document, or null if not found

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

find

@CheckForNull
<T extends Document> T find(Collection<T> collection,
                                           String key,
                                           int maxCacheAge)
                                    throws DocumentStoreException

Get the document with the key. The implementation may serve the document from a cache, but the cached document must not be older than the given maxCacheAge in milliseconds. An implementation must invalidate a cached document when it detects it is outdated. That is, a subsequent call to find(Collection, String) must return the newer version of the document.

The returned document is immutable.

Type Parameters:

T - the document type

Parameters:

collection - the collection

key - the key

maxCacheAge - the maximum age of the cached document (in ms)

Returns:

the document, or null if not found

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

query

@Nonnull
<T extends Document> List<T> query(Collection<T> collection,
                                             String fromKey,
                                             String toKey,
                                             int limit)
                                      throws DocumentStoreException

Get a list of documents where the key is greater than a start value and less than an end value.

The returned documents are sorted by key and are immutable.

Type Parameters:

T - the document type

Parameters:

collection - the collection

fromKey - the start value (excluding)

toKey - the end value (excluding)

limit - the maximum number of entries to return (starting with the lowest key)

Returns:

the list (possibly empty)

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

query

@Nonnull
<T extends Document> List<T> query(Collection<T> collection,
                                             String fromKey,
                                             String toKey,
                                             String indexedProperty,
                                             long startValue,
                                             int limit)
                                      throws DocumentStoreException

Get a list of documents where the key is greater than a start value and less than an end value and the given "indexed property" is greater or equals the specified value.

The indexed property can either be a Long value, in which case numeric comparison applies, or a Boolean value, in which case "false" is mapped to "0" and "true" is mapped to "1".

The returned documents are sorted by key and are immutable.

Type Parameters:

T - the document type

Parameters:

collection - the collection

fromKey - the start value (excluding)

toKey - the end value (excluding)

indexedProperty - the name of the indexed property (optional)

startValue - the minimum value of the indexed property

limit - the maximum number of entries to return

Returns:

the list (possibly empty)

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

remove

<T extends Document> void remove(Collection<T> collection,
                                 String key)
                          throws DocumentStoreException

Remove a document. This method does nothing if there is no document with the given key.

In case of a 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection

key - the key

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

remove

<T extends Document> void remove(Collection<T> collection,
                                 List<String> keys)
                          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 keys may have been removed.

In case of a 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection

keys - list of keys

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

remove

<T extends Document> int remove(Collection<T> collection,
                                Map<String,Long> toRemove)
                         throws DocumentStoreException

Batch remove documents with given keys and corresponding equal conditions on NodeDocument.MODIFIED_IN_SECS values. Keys for documents that do not exist are simply ignored. A document is only removed if the corresponding condition is met.

In case of a 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection.

toRemove - the keys of the documents to remove with the corresponding timestamps.

Returns:

the number of removed documents.

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

remove

<T extends Document> int remove(Collection<T> collection,
                                String indexedProperty,
                                long startValue,
                                long endValue)
                         throws DocumentStoreException

Batch remove documents where the given "indexed property" is within the given range (exclusive) - (startValue, endValue).

The indexed property is a Long value and numeric comparison applies.

In case of a 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection.

indexedProperty - the name of the indexed property

startValue - the minimum value of the indexed property (exclusive)

endValue - the maximum value of the indexed property (exclusive)

Returns:

the number of removed documents.

Throws:

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

create

<T extends Document> boolean create(Collection<T> collection,
                                    List<UpdateOp> updateOps)
                             throws IllegalArgumentException,
                                    DocumentStoreException

Try to create a list of documents. This method returns true iff none of the documents existed before and the create was successful. This method will return false if one of the documents already exists in the store. Some documents may still have been created in the store. An implementation does not have to guarantee an atomic create of all the documents described in the 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 DocumentStoreException (e.g. when a communication error occurs). In this case only some documents may have been created.

Type Parameters:

T - the document type

Parameters:

collection - the collection

updateOps - the list of documents to add (where UpdateOp.Conditions are not allowed)

Returns:

true if this worked (if none of the documents already existed)

Throws:

IllegalArgumentException - when at least one of the UpdateOps is conditional

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

createOrUpdate

@CheckForNull
<T extends Document> T createOrUpdate(Collection<T> collection,
                                                     UpdateOp update)
                                              throws IllegalArgumentException,
                                                     DocumentStoreException

Atomically checks if the document exists and updates it, otherwise the document is created (aka upsert). The returned document is immutable.

If this method fails with a 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 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection

update - the update operation (where UpdateOp.Conditions are not allowed)

Returns:

the old document or null if it didn't exist before.

Throws:

IllegalArgumentException - when the UpdateOp is conditional

DocumentStoreException - if the operation failed. E.g. because of an I/O error.

createOrUpdate

<T extends Document> List<T> createOrUpdate(Collection<T> collection,
                                            List<UpdateOp> updateOps)
                                     throws DocumentStoreException

Create or unconditionally update a number of documents. An implementation does not have to guarantee that all changes are applied atomically, together.

In case of a 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 UpdateOps 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection

updateOps - the update operation list

Returns:

the list containing old documents or null values if they didn't exist before (see 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.

findAndUpdate

@CheckForNull
<T extends Document> T findAndUpdate(Collection<T> collection,
                                                    UpdateOp update)
                                             throws DocumentStoreException

Performs a conditional update (e.g. using UpdateOp.Condition.Type.EXISTS and only updates the document if the condition is true. The returned document is immutable.

In case of a 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.

Type Parameters:

T - the document type

Parameters:

collection - the collection

update - the update operation with the condition

Returns:

the old document or null 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.

invalidateCache

@CheckForNull
CacheInvalidationStats invalidateCache()

Invalidate the document cache. Calling this method instructs the implementation to invalidate each document from the cache, which is not up to date with the underlying storage at the time this method is called. A document is considered in the cache if getIfCached(Collection, String) returns a non-null value for a key.

An implementation is allowed to perform lazy invalidation and only check whether a document is up-to-date when it is accessed after this method is called. However, this also includes a call to getIfCached(Collection, String), which must only return the document if it was up-to-date at the time this method was called. Similarly, a call to find(Collection, String) must guarantee the returned document reflects all the changes done up to when invalidateCache() was called.

In some implementations this method can be a NOP because documents can only be modified through a single instance of a DocumentStore.

Returns:

cache invalidation statistics or null if none are available.

invalidateCache

@CheckForNull
CacheInvalidationStats invalidateCache(Iterable<String> keys)

Invalidate the document cache but only with entries that match one of the keys provided. See invalidateCache() for the general contract of cache invalidation.

Parameters:

keys - the keys of the documents to invalidate.

Returns:

cache invalidation statistics or null if none are available.

invalidateCache

<T extends Document> void invalidateCache(Collection<T> collection,
                                          String key)

Invalidate the document cache for the given key. See invalidateCache() for the general contract of cache invalidation.

Parameters:

collection - the collection

key - the key

dispose

void dispose()

Dispose this instance.

getIfCached

@CheckForNull
<T extends Document> T getIfCached(Collection<T> collection,
                                                  String key)

Fetches the cached document. If the document is not present in the cache null will be returned. This method is consistent with other find methods that may return cached documents and will return null even when the implementation has a negative cache for documents that do not exist. This method will never return NodeDocument.NULL.

Type Parameters:

T - the document type

Parameters:

collection - the collection

key - the key

Returns:

cached document if present. Otherwise null.

setReadWriteMode

void setReadWriteMode(String readWriteMode)

Set the level of guarantee for read and write operations, if supported by this backend.

Parameters:

readWriteMode - the read/write mode

getCacheStats

@CheckForNull
Iterable<CacheStats> getCacheStats()

Returns:

status information about the cache

getMetadata

Map<String,String> getMetadata()

Returns:

description of the underlying storage.

getStats

@Nonnull
Map<String,String> getStats()

Returns statistics about the underlying storage. The information and keys returned by this method are implementation specific, may change between releases or may even depend on deployment aspects. E.g. depending on access rights, the method may return more or less information from the underlying store. This method should only be used for informational or debug purposes.

Returns:

statistics about this document store.

determineServerTimeDifferenceMillis

long determineServerTimeDifferenceMillis()
                                  throws UnsupportedOperationException,
                                         DocumentStoreException

Returns:

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

DocumentStoreException - if an I/O error occurs.