Package com.nuix.superutilities.items

Class SuperItemUtility

  • public class SuperItemUtility
extends java.lang.Object
    Offers methods for working with items and item collections in the same spirit of the ItemUtility offered in the Nuix API.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected SuperItemUtility()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.Set<nuix.Item> deduplicateCustomTieBreaker​(java.util.Collection<nuix.Item> items, java.util.function.BiFunction<nuix.Item,​nuix.Item,​nuix.Item> tieBreaker)
      Custom deduplication implementation allowing code to specify which original is kept.
      nuix.Item findAncestor​(@NotNull nuix.Item item, @NotNull java.util.function.Predicate<nuix.Item> ancestorPredicate)
      Traverses an item's ancestors bottom up, until the first item for which the predicate yields true or null if no ancestor matches the predicate.
      nuix.Item findContainerAncestor​(nuix.Item item)
      Traverses up an item's path to locate the nearest ancestor container item (kind:container) or null if there is no container ancestor item.
      java.util.Set<nuix.Item> findContainerAncestors​(java.util.Collection<nuix.Item> items)
      Similar to findContainerAncestor(Item), but resolves nearest container ancestor items for multiple items at once.
      java.util.Set<nuix.Item> findFamiliesWithoutItemsResponsiveToQuery​(nuix.Case nuixCase, java.util.Collection<nuix.Item> inputItems, java.lang.String itemsToRemoveQuery)  
      java.util.Set<nuix.Item> findItemsAndParents​(java.util.Collection<nuix.Item> items)
      Resolves input collection of items to a set which includes both parents of input items and the input items themselves.
      java.util.Set<nuix.Item> findParents​(java.util.Collection<nuix.Item> items)
      Resolves input collection of items to parent items.
      nuix.Item findPhysicalFileAncestor​(nuix.Item item)
      Traverses up an item's path to locate the ancestor physical file item (flag:physical_file) or null if there is no physical file ancestor item.
      java.util.Set<nuix.Item> findPhysicalFileAncestors​(java.util.Collection<nuix.Item> items)
      Similar to findPhysicalFileAncestor(Item), but resolves physical file ancestor items for multiple items at once.
      static SuperItemUtility getInstance()  
      java.util.List<nuix.Item> getItemsAndNeighboringSiblings​(java.util.List<nuix.Item> items, int itemsBefore, int itemsAfter)
      Gets items and sibling items within a certain ordinal distance.
      java.lang.String getPhysicalAncestorPath​(nuix.Item item)
      Returns the file system path of an item's physical file ancestor.
      boolean itemsAreSiblings​(nuix.Item a, nuix.Item b)
      Tests whether 2 items have the same parent by comparing their tree position values
      java.util.Set<nuix.Item> removeItemsResponsiveToQuery​(nuix.Case nuixCase, java.util.Collection<nuix.Item> inputItems, java.lang.String itemsToRemoveQuery)
      Convenience method for removing items responsive to a query from another collection of items.
      void splitAndMaintainFamilies​(java.util.Collection<nuix.Item> items, int targetChunkSize, java.util.function.Consumer<java.util.Collection<nuix.Item>> chunkConsumer)
      Splits a collection of items into a target chunk size, while maintaining families.
      java.util.Set<nuix.Item> unionMany​(java.util.List<java.util.Collection<nuix.Item>> itemCollections)
      Unions multiple collections of items into a single Set of items.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SuperItemUtility

        protected SuperItemUtility()

    • Method Detail

      • unionMany

        public java.util.Set<nuix.Item> unionMany​(java.util.List<java.util.Collection<nuix.Item>> itemCollections)
        Unions multiple collections of items into a single Set of items.
        Parameters:
        itemCollections - A list of item collections to union into a single final Set
        Returns:
        A set at most 1 of each item in the provided input item collections

      • findPhysicalFileAncestor

        public nuix.Item findPhysicalFileAncestor​(nuix.Item item)
        Traverses up an item's path to locate the ancestor physical file item (flag:physical_file) or null if there is no physical file ancestor item.
        Parameters:
        item - The item to find the physical file ancestor for.
        Returns:
        The physical file ancestor item (if there is on) otherwise null

      • findAncestor

        public nuix.Item findAncestor​(@NotNull
                              @NotNull nuix.Item item,
                              @NotNull
                              @NotNull java.util.function.Predicate<nuix.Item> ancestorPredicate)
        Traverses an item's ancestors bottom up, until the first item for which the predicate yields true or null if no ancestor matches the predicate.
        Parameters:
        item - The item whose ancestors will be inspected
        ancestorPredicate - A predicate for matching the target ancestor
        Returns:
        The first ancestor matched walking bottom up or null if none matched the predicate

      • findPhysicalFileAncestors

        public java.util.Set<nuix.Item> findPhysicalFileAncestors​(java.util.Collection<nuix.Item> items)
        Similar to findPhysicalFileAncestor(Item), but resolves physical file ancestor items for multiple items at once. Resulting set will not contain nulls.
        Parameters:
        items - The items to resolve the physical file ancestors of.
        Returns:
        The physical file ancestors of the input items (if there were any)

      • findContainerAncestor

        public nuix.Item findContainerAncestor​(nuix.Item item)
        Traverses up an item's path to locate the nearest ancestor container item (kind:container) or null if there is no container ancestor item.
        Parameters:
        item - The item to resolve the nearest container ancestor of.
        Returns:
        The nearest container ancestor of the input item or null if no container ancestor could be found

      • findContainerAncestors

        public java.util.Set<nuix.Item> findContainerAncestors​(java.util.Collection<nuix.Item> items)
        Similar to findContainerAncestor(Item), but resolves nearest container ancestor items for multiple items at once. Resulting set will not contain nulls.
        Parameters:
        items - The items to resolve the nearest container ancestors of.
        Returns:
        The nearest container ancestors of the input items.

      • findParents

        public java.util.Set<nuix.Item> findParents​(java.util.Collection<nuix.Item> items)
        Resolves input collection of items to parent items.
        Parameters:
        items - The items to resolve to parent items
        Returns:
        The parent items of the provide input items

      • findItemsAndParents

        public java.util.Set<nuix.Item> findItemsAndParents​(java.util.Collection<nuix.Item> items)
        Resolves input collection of items to a set which includes both parents of input items and the input items themselves.
        Parameters:
        items - The items to resolve the parents of
        Returns:
        The input items and their parent items

      • splitAndMaintainFamilies

        public void splitAndMaintainFamilies​(java.util.Collection<nuix.Item> items,
                                     int targetChunkSize,
                                     java.util.function.Consumer<java.util.Collection<nuix.Item>> chunkConsumer)
        Splits a collection of items into a target chunk size, while maintaining families. Each chunk is passed as an argument to the provided chunkConsumer.
        Parameters:
        items - The items to split
        targetChunkSize - The target chunk size. Actual chunks may differ from this size based on where family boundaries land.
        chunkConsumer - A Consumer<Collection<Item>> which will receive each chunk as it is built.

      • removeItemsResponsiveToQuery

        public java.util.Set<nuix.Item> removeItemsResponsiveToQuery​(nuix.Case nuixCase,
                                                             java.util.Collection<nuix.Item> inputItems,
                                                             java.lang.String itemsToRemoveQuery)
                                                      throws java.io.IOException
        Convenience method for removing items responsive to a query from another collection of items. Internally this method runs a search for the given query and then uses ItemUtility.difference to remove them from the provided input items, returning the differenced result.
        Parameters:
        nuixCase - The Nuix case (needed to run the search)
        inputItems - The items from which you wish to remove items which are responsive to the given query
        itemsToRemoveQuery - The query used to define items you wish to have removed form the input items
        Returns:
        The input items, with items responsive to the query removed
        Throws:
        java.io.IOException - Likely thrown if there is an issue with the provided query

      • findFamiliesWithoutItemsResponsiveToQuery

        public java.util.Set<nuix.Item> findFamiliesWithoutItemsResponsiveToQuery​(nuix.Case nuixCase,
                                                                          java.util.Collection<nuix.Item> inputItems,
                                                                          java.lang.String itemsToRemoveQuery)
                                                                   throws java.io.IOException
        Throws:
        java.io.IOException

      • getPhysicalAncestorPath

        public java.lang.String getPhysicalAncestorPath​(nuix.Item item)
        Returns the file system path of an item's physical file ancestor. Begins by calling findPhysicalFileAncestor(Item). If an physical file ancestor is located, then gets its URI and attempts to convert that to an actual file system path.
        Parameters:
        item - The item to resolve the physical file ancestor file system path of.
        Returns:
        The physical file ancestor file system path (if possible), otherwise null

      • deduplicateCustomTieBreaker

        public java.util.Set<nuix.Item> deduplicateCustomTieBreaker​(java.util.Collection<nuix.Item> items,
                                                            java.util.function.BiFunction<nuix.Item,​nuix.Item,​nuix.Item> tieBreaker)
        Custom deduplication implementation allowing code to specify which original is kept. The normal behavior of ItemUtility.deduplicate is that the original with the earliest position value, amongst the items with the same MD5, is considered the original. This implementation allows code to provide a 2 argument function which will determine the winner. It may be a good idea for the custom function provided to default to the default position behavior when all other comparisons it may perform are equal, to mimic the behavior of the API. Like the API deduplicate method, items without an MD5 value are automatically included in the results and therefore never sent to the tie breaker function.
        Parameters:
        items - The items to deduplicate
        tieBreaker - A function which is provided 2 items with the same MD5, the first argument is the current "champion" item (the item currently considered original) and the second argument is the "contender" item (the item which may become the new champion). If function returns the "contender" item, then it becomes the new "champion", any other result (including null) leaves the current "champion" in place.
        Returns:
        A custom deduplicated set of items

      • itemsAreSiblings

        public boolean itemsAreSiblings​(nuix.Item a,
                                nuix.Item b)
        Tests whether 2 items have the same parent by comparing their tree position values
        Parameters:
        a - The first item to compare
        b - The second item to compare
        Returns:
        True if items appear to have the same parent item based on their tree position values

      • getItemsAndNeighboringSiblings

        public java.util.List<nuix.Item> getItemsAndNeighboringSiblings​(java.util.List<nuix.Item> items,
                                                                int itemsBefore,
                                                                int itemsAfter)
        Gets items and sibling items within a certain ordinal distance.
        Parameters:
        items - The items to obtain the neighboring siblings of
        itemsBefore - How many siblings before each item to include
        itemsAfter - How many siblings after each item to include
        Returns:
        A new list of items which includes both input items and neighboring siblings, sorted by position