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

Class Utils

  • public class Utils
extends Object
    Utility methods.

    • 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.

      • PROPERTY_OR_DELETED_OR_COMMITROOT_OR_REVISIONS

        public static final Predicate<String> PROPERTY_OR_DELETED_OR_COMMITROOT_OR_REVISIONS
        A predicate for property, _deleted, _commitRoot or _revisions names.

      • COMMITROOT_OR_REVISIONS

        public static final Predicate<String> COMMITROOT_OR_REVISIONS
        A predicate for _commitRoot and _revisions names.

    • Constructor Detail

      • Utils

        public Utils()

    • Method Detail

      • pathDepth

        public static int pathDepth​(String path)

      • getIdDepth

        public static int getIdDepth​(Path path)
        Calculates the depth prefix of the id for the given path. The is the same as pathDepth(String), but takes a Path argument.
        Parameters:
        path - a path.
        Returns:
        the id depth prefix for the given path.

      • estimateMemoryUsage

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

      • mapEntryDiagnostics

        public static String mapEntryDiagnostics​(@NotNull
                                         @NotNull Set<Map.Entry<String,​Object>> entries)
        Generates diagnostics about the structure of the entries of the document by counting properties and their lengths.

      • 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​(@NotNull
                                   @NotNull String path)

      • getIdFromPath

        public static String getIdFromPath​(@NotNull
                                   @NotNull Path 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

        @Nullable
public static @Nullable 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

      • isNodeNameLong

        public static boolean isNodeNameLong​(Path path,
                                     int sizeLimit)
        Checks whether Node name is too long or not based on underlining document store
        Parameters:
        path - node path
        sizeLimit - sizeLimit for node name
        Returns:
        true if node name is long else false

      • isLongPath

        public static boolean isLongPath​(Path path)

      • isIdFromLongPath

        public static boolean isIdFromLongPath​(String id)

      • getPathFromId

        public static String getPathFromId​(String id)

      • getPreviousPathFor

        public static Path getPreviousPathFor​(Path path,
                                      Revision r,
                                      int height)

      • getPreviousIdFor

        public static String getPreviousIdFor​(Path 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​(Path 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​(Path path)
        Returns the upper key limit to retrieve the children of the given path.
        Parameters:
        path - a path.
        Returns:
        the upper key limit.

      • getParentIdFromLowerLimit

        @Nullable
public static @Nullable 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
                                  @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

        @NotNull
public static @NotNull Revision resolveCommitRevision​(@NotNull
                                                      @NotNull Revision rev,
                                                      @NotNull
                                                      @NotNull 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

        @Nullable
public static @Nullable Revision max​(@Nullable
                                     @Nullable Revision a,
                                     @Nullable
                                     @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

        @Nullable
public static @Nullable Revision max​(@Nullable
                                     @Nullable Revision a,
                                     @Nullable
                                     @Nullable Revision b,
                                     @NotNull
                                     @NotNull 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

        @Nullable
public static @Nullable Revision min​(@Nullable
                                     @Nullable Revision a,
                                     @Nullable
                                     @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

        @Nullable
public static @Nullable Revision min​(@Nullable
                                     @Nullable Revision a,
                                     @Nullable
                                     @Nullable Revision b,
                                     @NotNull
                                     @NotNull 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

        @NotNull
public static @NotNull NodeDocument getRootDocument​(@NotNull
                                                    @NotNull 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

      • isIncluded

        public static boolean isIncluded​(Path path,
                                 @NotNull
                                 @NotNull Set<String> includes,
                                 @NotNull
                                 @NotNull Set<String> excludes)
        Default implementation for applying include/exclude path prefixes client-side, meaning the query to the DocumentStore searches for all documents and include/excludes are then filtered after receiving that query. This variant is obviously not intended for production use, as client side filtering is slow. Hence this is only used for testing for any non-MongoDocumentStore. It should not be enabled in production, unless this performance hit here is understood and accepted.
        Parameters:
        path - the path for which to evaluate the include/excludes
        includes - set of path prefixes which should only be considered
        excludes - set of path prefixes which should be excluded. if these overlap with includes, then exclude has precedence.
        Returns:
        whether the provided path is included or not

      • isHiddenPath

        public static boolean isHiddenPath​(@NotNull
                                   @NotNull String path)
        Returns:
        if path represent oak's internal path. That is, a path element start with a colon.

      • 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
                          @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.

      • getStartRevisions

        @NotNull
public static @NotNull RevisionVector getStartRevisions​(@NotNull
                                                        @NotNull Iterable<ClusterNodeInfoDocument> clusterNodes)
        Returns a revision vector that contains a revision for each of the passed cluster nodes with a revision timestamp that corresponds to the last known time when the cluster node was started.
        Parameters:
        clusterNodes - the cluster node information.
        Returns:
        revision vector representing the last known time when the cluster nodes were started.

      • getMinTimestampForDiff

        public static long getMinTimestampForDiff​(@NotNull
                                          @NotNull RevisionVector fromRev,
                                          @NotNull
                                          @NotNull RevisionVector toRev,
                                          @NotNull
                                          @NotNull 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.

      • getMinTimestampForDiffManyChildren

        public static long getMinTimestampForDiffManyChildren​(@NotNull
                                                      @NotNull RevisionVector fromRev,
                                                      @NotNull
                                                      @NotNull RevisionVector toRev,
                                                      @NotNull
                                                      @NotNull RevisionVector minRevisions)
        Returns the minimum timestamp to use for a query for child documents that have been modified between fromRev and toRev. We use a different calculation method for for DocumentNodeStore#diffManyChildren(), see OAK-10812
        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.

      • isThrottlingEnabled

        public static boolean isThrottlingEnabled​(DocumentNodeStoreBuilder<?> builder)
        Check whether throttling is enabled or not for document store.
        Parameters:
        builder - instance for DocumentNodeStoreBuilder
        Returns:
        true if throttling is enabled else false

      • isFullGCEnabled

        public static boolean isFullGCEnabled​(DocumentNodeStoreBuilder<?> builder)
        Check whether full GC is enabled or not for document store.
        Parameters:
        builder - instance for DocumentNodeStoreBuilder
        Returns:
        true if full GC is enabled else false

      • isEmbeddedVerificationEnabled

        public static boolean isEmbeddedVerificationEnabled​(DocumentNodeStoreBuilder<?> builder)
        Check whether embedded verification for full GC mode is enabled or not for document store.
        Parameters:
        builder - instance for DocumentNodeStoreBuilder
        Returns:
        true if embedded verification is enabled else false

      • isAvoidMergeLockEnabled

        public static boolean isAvoidMergeLockEnabled​(DocumentNodeStoreBuilder<?> builder)
        Check whether avoid exclusive merge lock is enabled or not for document store.
        Parameters:
        builder - instance for DocumentNodeStoreBuilder
        Returns:
        true if avoid exclusive merge lock is enabled else false

      • isGreaterOrEquals

        public static boolean isGreaterOrEquals​(@NotNull
                                        @NotNull RevisionVector a,
                                        @NotNull
                                        @NotNull 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​(@NotNull
                                    @NotNull RevisionVector from,
                                    @NotNull
                                    @NotNull 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​(@NotNull
                                              @NotNull NodeDocument rootDoc,
                                              @NotNull
                                              @NotNull Clock clock,
                                              int clusterId,
                                              long warnThresholdMillis)
                                       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.
        warnThresholdMillis - log a warning when an external change in the future is detected with more than this time difference.
        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.

      • checkRevisionAge

        public static void checkRevisionAge​(DocumentStore store,
                                    ClusterNodeInfo info,
                                    Clock clock)
                             throws DocumentStoreException
        Check the revision age on the root document for the given cluster node info. The check will fail with a DocumentStoreException if the _lastRev timestamp for the cluster node is newer then the current clock time. The check will not fail if the root document does not exist or does not have a _lastRev entry for the cluster node.
        Parameters:
        store - the document store from where to read the root document.
        info - the cluster node info with the clusterId.
        clock - the clock to get the current time.
        Throws:
        DocumentStoreException - if the check fails.

      • sum

        public static long sum​(long... addends)
        Calculates the sum of the given long values. The implementation protects against overflow by returning Long#MAX_VALUE when the result would actually be bigger than that. Similarly, Long#MIN_VALUE is returned when the result would actually be smaller than that.
        Parameters:
        addends - the values.
        Returns:
        the sum of the values.

      • asISO8601

        public static String asISO8601​(long ms)
        Formats the epoch time in milliseconds as ISO-8601 in UTC.
        Parameters:
        ms - the time in milliseconds.
        Returns:
        date format for the time in milliseconds.