org.apache.jackrabbit.oak.plugins.document.util

Class Utils

java.lang.Object

org.apache.jackrabbit.oak.plugins.document.util.Utils

public class Utils
extends Object

Utility methods.

Field Summary

Fields

Modifier and Type	Field and Description
static int	NODE_NAME_LIMIT The maximum size a node name, in bytes.
static int	PATH_LONG The maximum length of the parent path, in bytes.
static int	PATH_SHORT The length of path (in characters), whose UTF-8 representation can not possibly be too large to be used for the primary key for the document store.
static Predicate<String>	PROPERTY_OR_DELETED A predicate for property and _deleted names.

Constructor Summary

Constructors

Constructor and Description
Utils()

Method Summary

Modifier and Type	Method and Description
static <T> CloseableIterable<T>	abortingIterable(Iterable<T> iterable, Predicate<T> p) Wraps the given iterable and aborts iteration over elements when the predicate on an element evaluates to false.
static void	alignWithExternalRevisions(NodeDocument rootDoc, Clock clock, int clusterId) Makes sure the current time is after the most recent external revision timestamp in the _lastRev map of the given root document.
static Long	asLong(Number n) Returns the given number instance as a Long.
static Iterable<StringValue>	asStringValueIterable(Iterable<String> values) Transforms the given Iterable from String to StringValue elements.
static void	closeIfCloseable(Object obj) Closes the obj its of type Closeable.
static <K> void	deepCopyMap(Map<K,Object> source, Map<K,Object> target) Deep copy of a map that may contain map values.
static StringBuilder	encodeHexString(byte[] data, StringBuilder sb) Encodes the given data as hexadecimal string representation and appends it to the StringBuilder.
static String	escapePropertyName(String propertyName)
static int	estimateMemoryUsage(Map<?,Object> map)
static Iterable<NodeDocument>	getAllDocuments(DocumentStore store) Returns an Iterable over all NodeDocuments in the given store.
static int	getDepthFromId(String id)
static String	getIdFromPath(String path)
static String	getKeyLowerLimit(String path) Returns the lower key limit to retrieve the children of the given path.
static String	getKeyUpperLimit(String path) Returns the upper key limit to retrieve the children of the given path.
static long	getMaxExternalTimestamp(Iterable<Revision> revisions, int localClusterId) Returns the highest timestamp of all the passed external revisions.
static long	getMinTimestampForDiff(RevisionVector fromRev, RevisionVector toRev, RevisionVector minRevisions) Returns the minimum timestamp to use for a query for child documents that have been modified between fromRev and toRev.
static String	getModuleVersion() Returns the version of the module that contains the DocumentNodeStore.
static String	getParentId(String id) Returns the parent id for given id if possible
static String	getParentIdFromLowerLimit(String fromKey) Returns parentId extracted from the fromKey.
static String	getPathFromId(String id)
static String	getPreviousIdFor(String path, Revision r, int height)
static String	getPreviousPathFor(String path, Revision r, int height)
static NodeDocument	getRootDocument(DocumentStore store) Returns the root node document of the given document store.
static Iterable<NodeDocument>	getSelectedDocuments(DocumentStore store, String indexedProperty, long startValue) Like getSelectedDocuments(DocumentStore, String, long, int) with a default batchSize.
static Iterable<NodeDocument>	getSelectedDocuments(DocumentStore store, String indexedProperty, long startValue, int batchSize) Returns an Iterable over all NodeDocuments in the given store matching a condition on an indexed property.
static boolean	isCommitted(String tag) Returns true if a revision tagged with the given revision should be considered committed, false otherwise.
static boolean	isGreaterOrEquals(RevisionVector a, RevisionVector b) Returns true if all the revisions in the a greater or equals to their counterparts in b.
static boolean	isHiddenPath(String path)
static boolean	isIdFromLongPath(String id)
static boolean	isLeafPreviousDocId(String id) Determines if the passed id belongs to a leaf level previous doc
static boolean	isLocalChange(RevisionVector from, RevisionVector to, int clusterId) Returns true if changes identified by the from and to RevisionVector are considered local changes.
static boolean	isLongPath(String path)
static boolean	isPreviousDocId(String id) Determines if the passed id belongs to a previous doc
static boolean	isPropertyName(String key)
static void	joinQuietly(Thread... threads) Calls Thread.join() on each of the passed threads and catches any potentially thrown InterruptedException.
static Revision	max(Revision a, Revision b) Returns the revision with the newer timestamp or null if both revisions are null.
static Revision	max(Revision a, Revision b, Comparator<Revision> c) Returns the revision which is considered more recent or null if both revisions are null.
static Revision	min(Revision a, Revision b) Returns the revision with the older timestamp or null if both revisions are null.
static Revision	min(Revision a, Revision b, Comparator<Revision> c) Returns the revision which is considered older or null if both revisions are null.
static int	pathDepth(String path)
static Iterable<String>	pathToId(Iterable<String> paths) Transforms the given paths into ids using getIdFromPath(String).
static Revision	resolveCommitRevision(Revision rev, String tag) Resolve the commit revision for the given revision rev and the associated commit tag.
static String	timestampToString(long timestamp) Provides a readable string for given timestamp
static String	unescapePropertyName(String key)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PATH_SHORT

public static final int PATH_SHORT

The length of path (in characters), whose UTF-8 representation can not possibly be too large to be used for the primary key for the document store.

PATH_LONG

public static final int PATH_LONG

The maximum length of the parent path, in bytes. If the parent path is longer, then the id of a document is no longer the path, but the hash of the parent, and then the node name.

NODE_NAME_LIMIT

public static final int NODE_NAME_LIMIT

The maximum size a node name, in bytes. This is only a problem for long path.

PROPERTY_OR_DELETED

public static final Predicate<String> PROPERTY_OR_DELETED

A predicate for property and _deleted names.

Constructor Detail

Utils

public Utils()

Method Detail

pathDepth

public static int pathDepth(String path)

estimateMemoryUsage

public static int estimateMemoryUsage(Map<?,Object> map)

escapePropertyName

public static String escapePropertyName(String propertyName)

unescapePropertyName

public static String unescapePropertyName(String key)

isPropertyName

public static boolean isPropertyName(String key)

getIdFromPath

public static String getIdFromPath(String path)

encodeHexString

public static StringBuilder encodeHexString(byte[] data,
                                            StringBuilder sb)

Encodes the given data as hexadecimal string representation and appends it to the StringBuilder. The hex digits are in lower case.

Parameters:

data - the bytes to encode.

sb - the hexadecimal string representation is appended to this StringBuilder.

Returns:

the StringBuilder passed to this method.

getParentId

@CheckForNull
public static String getParentId(String id)

Returns the parent id for given id if possible

It would return null in following cases

• If id is from long path
• If id is for root path
• If id is for an invalid path

Parameters:

id - id for which parent id needs to be determined

Returns:

parent id. null if parent id cannot be determined

isLongPath

public static boolean isLongPath(String path)

isIdFromLongPath

public static boolean isIdFromLongPath(String id)

getPathFromId

public static String getPathFromId(String id)

getDepthFromId

public static int getDepthFromId(String id)
                          throws IllegalArgumentException

Throws:

IllegalArgumentException

getPreviousPathFor

public static String getPreviousPathFor(String path,
                                        Revision r,
                                        int height)

getPreviousIdFor

public static String getPreviousIdFor(String path,
                                      Revision r,
                                      int height)

isPreviousDocId

public static boolean isPreviousDocId(String id)

Determines if the passed id belongs to a previous doc

Parameters:

id - id to check

Returns:

true if the id belongs to a previous doc

isLeafPreviousDocId

public static boolean isLeafPreviousDocId(String id)

Determines if the passed id belongs to a leaf level previous doc

Parameters:

id - id to check

Returns:

true if the id belongs to a leaf level previous doc

deepCopyMap

public static <K> void deepCopyMap(Map<K,Object> source,
                                   Map<K,Object> target)

Deep copy of a map that may contain map values.

Type Parameters:

K - the type of the map key

Parameters:

source - the source map

target - the target map

getKeyLowerLimit

public static String getKeyLowerLimit(String path)

Returns the lower key limit to retrieve the children of the given path.

Parameters:

path - a path.

Returns:

the lower key limit.

getKeyUpperLimit

public static String getKeyUpperLimit(String path)

Returns the upper key limit to retrieve the children of the given path.

Parameters:

path - a path.

Returns:

the upper key limit.

getParentIdFromLowerLimit

@CheckForNull
public static String getParentIdFromLowerLimit(String fromKey)

Returns parentId extracted from the fromKey. fromKey is usually constructed using Utils#getKeyLowerLimit

Parameters:

fromKey - key used as start key in queries

Returns:

parentId if possible.

isCommitted

public static boolean isCommitted(@Nullable
                                  String tag)

Returns true if a revision tagged with the given revision should be considered committed, false otherwise. Committed revisions have a tag, which equals 'c' or starts with 'c-'.

Parameters:

tag - the tag (may be null).

Returns:

true if committed; false otherwise.

resolveCommitRevision

@Nonnull
public static Revision resolveCommitRevision(@Nonnull
                                                       Revision rev,
                                                       @Nonnull
                                                       String tag)

Resolve the commit revision for the given revision rev and the associated commit tag.

Parameters:

rev - a revision.

tag - the associated commit tag.

Returns:

the actual commit revision for rev.

closeIfCloseable

public static void closeIfCloseable(Object obj)

Closes the obj its of type Closeable. It is mostly used to close Iterator/Iterables which are backed by say DBCursor

Parameters:

obj - object to close

timestampToString

public static String timestampToString(long timestamp)

Provides a readable string for given timestamp

max

@CheckForNull
public static Revision max(@Nullable
                                          Revision a,
                                          @Nullable
                                          Revision b)

Returns the revision with the newer timestamp or null if both revisions are null. The implementation will return the first revision if both have the same timestamp.

Parameters:

a - the first revision (or null).

b - the second revision (or null).

Returns:

the revision with the newer timestamp.

max

@CheckForNull
public static Revision max(@Nullable
                                          Revision a,
                                          @Nullable
                                          Revision b,
                                          @Nonnull
                                          Comparator<Revision> c)

Returns the revision which is considered more recent or null if both revisions are null. The implementation will return the first revision if both are considered equal. The comparison is done using the provided comparator.

Parameters:

a - the first revision (or null).

b - the second revision (or null).

c - the comparator.

Returns:

the revision considered more recent.

min

@CheckForNull
public static Revision min(@Nullable
                                          Revision a,
                                          @Nullable
                                          Revision b)

Returns the revision with the older timestamp or null if both revisions are null. The implementation will return the first revision if both have the same timestamp.

Parameters:

a - the first revision (or null).

b - the second revision (or null).

Returns:

the revision with the older timestamp.

min

@CheckForNull
public static Revision min(@Nullable
                                          Revision a,
                                          @Nullable
                                          Revision b,
                                          @Nonnull
                                          Comparator<Revision> c)

Returns the revision which is considered older or null if both revisions are null. The implementation will return the first revision if both are considered equal. The comparison is done using the provided comparator.

Parameters:

a - the first revision (or null).

b - the second revision (or null).

c - the comparator.

Returns:

the revision considered more recent.

getAllDocuments

public static Iterable<NodeDocument> getAllDocuments(DocumentStore store)

Returns an Iterable over all NodeDocuments in the given store. The returned Iterable does not guarantee a consistent view on the store. it may return documents that have been added to the store after this method had been called.

Parameters:

store - a DocumentStore.

Returns:

an Iterable over all documents in the store.

getRootDocument

@Nonnull
public static NodeDocument getRootDocument(@Nonnull
                                                     DocumentStore store)

Returns the root node document of the given document store. The returned document is retrieved from the document store via DocumentStore.find(Collection, String), which means the implementation is allowed to return a cached version of the document. The document is therefore not guaranteed to be up-to-date.

Parameters:

store - a document store.

Returns:

the root document.

Throws:

IllegalStateException - if there is no root document.

getSelectedDocuments

public static Iterable<NodeDocument> getSelectedDocuments(DocumentStore store,
                                                          String indexedProperty,
                                                          long startValue,
                                                          int batchSize)

Returns an Iterable over all NodeDocuments in the given store matching a condition on an indexed property. The returned Iterable does not guarantee a consistent view on the store. it may return documents that have been added to the store after this method had been called.

Parameters:

store - a DocumentStore.

indexedProperty - the name of the indexed property.

startValue - the lower bound value for the indexed property (inclusive).

batchSize - number of documents to fetch at once

Returns:

an Iterable over all documents in the store matching the condition

getSelectedDocuments

public static Iterable<NodeDocument> getSelectedDocuments(DocumentStore store,
                                                          String indexedProperty,
                                                          long startValue)

Like getSelectedDocuments(DocumentStore, String, long, int) with a default batchSize.

isHiddenPath

public static boolean isHiddenPath(@Nonnull
                                   String path)

Returns:

if path represent oak's internal path. That is, a path element start with a colon.

asStringValueIterable

public static Iterable<StringValue> asStringValueIterable(@Nonnull
                                                          Iterable<String> values)

Transforms the given Iterable from String to StringValue elements. The Iterable must no have null values.

pathToId

public static Iterable<String> pathToId(@Nonnull
                                        Iterable<String> paths)

Transforms the given paths into ids using getIdFromPath(String).

getMaxExternalTimestamp

public static long getMaxExternalTimestamp(Iterable<Revision> revisions,
                                           int localClusterId)

Returns the highest timestamp of all the passed external revisions. A revision is considered external if the clusterId is different from the passed localClusterId.

Parameters:

revisions - the revisions to consider.

localClusterId - the id of the local cluster node.

Returns:

the highest timestamp or Long.MIN_VALUE if none of the revisions is external.

asLong

public static Long asLong(@Nullable
                          Number n)

Returns the given number instance as a Long.

Parameters:

n - a number or null.

Returns:

the number converted to a Long or null if n is null.

getMinTimestampForDiff

public static long getMinTimestampForDiff(@Nonnull
                                          RevisionVector fromRev,
                                          @Nonnull
                                          RevisionVector toRev,
                                          @Nonnull
                                          RevisionVector minRevisions)

Returns the minimum timestamp to use for a query for child documents that have been modified between fromRev and toRev.

Parameters:

fromRev - the from revision.

toRev - the to revision.

minRevisions - the minimum revisions of foreign cluster nodes. These are derived from the startTime of a cluster node.

Returns:

the minimum timestamp.

isGreaterOrEquals

public static boolean isGreaterOrEquals(@Nonnull
                                        RevisionVector a,
                                        @Nonnull
                                        RevisionVector b)

Returns true if all the revisions in the a greater or equals to their counterparts in b. If b contains revisions for cluster nodes that are not present in a, return false.

Parameters:

a -

b -

Returns:

true if all the revisions in the a are at least as recent as their counterparts in the b

isLocalChange

public static boolean isLocalChange(@Nonnull
                                    RevisionVector from,
                                    @Nonnull
                                    RevisionVector to,
                                    int clusterId)

Returns true if changes identified by the from and to RevisionVector are considered local changes. That is the only difference between the two revision vectors are for the given (local) clusterId.

Parameters:

from - the from revision vector.

to - the to revision vector.

clusterId - the local clusterId.

Returns:

whether the changes are considered local.

abortingIterable

public static <T> CloseableIterable<T> abortingIterable(Iterable<T> iterable,
                                                        Predicate<T> p)

Wraps the given iterable and aborts iteration over elements when the predicate on an element evaluates to false. Calling close() on the returned iterable will close the passed iterable if it is Closeable.

Parameters:

iterable - the iterable to wrap.

p - the predicate.

Returns:

the aborting iterable.

alignWithExternalRevisions

public static void alignWithExternalRevisions(@Nonnull
                                              NodeDocument rootDoc,
                                              @Nonnull
                                              Clock clock,
                                              int clusterId)
                                       throws InterruptedException

Makes sure the current time is after the most recent external revision timestamp in the _lastRev map of the given root document. If necessary the current thread waits until clock is after the external revision timestamp.

Parameters:

rootDoc - the root document.

clock - the clock.

clusterId - the local clusterId.

Throws:

InterruptedException - if the current thread is interrupted while waiting. The interrupted status on the current thread is cleared when this exception is thrown.

joinQuietly

public static void joinQuietly(Thread... threads)

Calls Thread.join() on each of the passed threads and catches any potentially thrown InterruptedException.

Parameters:

threads - the threads to join.

getModuleVersion

public static String getModuleVersion()

Returns the version of the module that contains the DocumentNodeStore.

Returns:

the module version or "SNAPSHOT" if unknown.