Package com.nuix.superutilities.misc

Class DigestList

  • All Implemented Interfaces:
    java.lang.Iterable<java.lang.String>
    public class DigestList
extends java.lang.Object
implements java.lang.Iterable<java.lang.String>
    This class provides an in-memory representation of a Nuix binary digest list. This class is capable of loading Nuix binary digest lists into memory, modify digests present (add, remove, import) and saving out a new Nuix binary digest list.

    Note: When saving a digest list to one of the directories that Nuix looks for digest lists, Nuix may not immediately recognize the presence of that new digest list until all workbench tabs are closed and re-opened, case is closed and reopened, etc.

    • Constructor Summary

      Constructors 
      Constructor Description
      DigestList()
      Creates a new empty instance.
      DigestList​(java.io.File... sourceFiles)
      Creates a new instance and then imports digests from each provided source Nuix binary digest list file by iteratively calling importFile(File) for each.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addItem​(nuix.Item item)
      Adds the MD5 of the provided item to this instance (if not already present).
      void addItems​(java.util.Collection<nuix.Item> items)
      Adds the MD5s of the provided items to this instance (if not already present).
      void addMd5​(byte[] md5Bytes)
      Adds the given MD5 to this instance (if not already present).
      void addMd5​(java.lang.String md5)
      Adds the given MD5 to this instance (if not already present).
      static void combineDigestFiles​(java.io.File outputFile, java.util.Collection<java.io.File> inputFiles)
      Create a new digest list file from multiple source digest lists.
      static void combineDigestFiles​(java.lang.String outputFile, java.util.Collection<java.lang.String> inputFiles)
      Create a new digest list file from multiple source digest lists.
      boolean containsMd5​(byte[] md5Bytes)
      Gets whether the given MD5 is present in this instance.
      boolean containsMd5​(java.lang.String md5)
      Gets whether the given MD5 is present in this instance.
      static void eachDigest​(java.io.File sourceDigestList, java.util.function.Consumer<java.lang.String> md5StringConsumer)
      Provides a way to iterate each MD5 string present in a given digest list file without first reading the entirety of that digest list file into memory.
      java.util.Set<nuix.Item> findMatchingItems​(nuix.Case nuixCase)
      Finds items in given case which have MD5s matching those found in this instance.
      java.util.Set<nuix.Item> findMatchingItems​(nuix.Case nuixCase, int chunkSize)
      Finds items in given case which have MD5s matching those found in this instance.
      static int getDigestCount​(java.io.File sourceDigestList)
      Returns a count of digests present in the given Nuix binary digest list file.
      int importCaseLevelDigestList​(nuix.Case nuixCase, java.lang.String name)
      Imports digests from a file located at "[CASE_DIRECTORY]\Stores\User Data\Digest Lists\[NAME].hash" (case level digest list location).
      int importFile​(java.io.File digestListFile)
      Imports digests found in given input file to this instance (if not already present).
      int importFile​(java.lang.String digestListFile)
      Imports digests found in given input file to this instance (if not already present).
      int importSystemLevelDigestList​(java.lang.String name)
      Imports digests from a file located at "%programdata%\Nuix\Digest Lists\[NAME].hash" (system level digest list location).
      int importUserLevelDigestList​(java.lang.String name)
      Imports digests from a file located at "%appdata%\Nuix\Digest Lists\[NAME].hash" (user level digest list location).
      java.util.Iterator<java.lang.String> iterator()
      Provides an iterator over the hexadecimal string versions of the MD5s present in this instance.
      void removeItem​(nuix.Item item)
      Removes MD5 of provided item from this instance.
      void removeItems​(java.util.Collection<nuix.Item> items)
      Removes MD5s from this instance based on the MD5s of the given items.
      void removeMd5​(byte[] md5Bytes)
      Removes the given MD5 from this instance.
      void removeMd5​(java.lang.String md5)
      Removes the given MD5 from this instance.
      void saveCaseLevelDigestList​(nuix.Case nuixCase, java.lang.String name)
      Saves a new digest list to a file located at "[CASE_DIRECTORY]\Stores\User Data\Digest Lists\[NAME].hash" (case level digest list location).
      void saveFile​(java.io.File digestListFile)
      Saves a new Nuix binary digest list based on the digests stored in memory of this instance.
      void saveSystemLevelDigestList​(java.lang.String name)
      Saves a new digest list to a file located at "%programdata%\Nuix\Digest Lists\[NAME].hash" (system level digest list location).
      void saveUserLevelDigestList​(java.lang.String name)
      Saves a new digest list to a file located at "%appdata%\Nuix\Digest Lists\[NAME].hash" (user level digest list location).
      int size()
      Gets the count of digests present in this instance.

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • DigestList

        public DigestList()
        Creates a new empty instance.

      • DigestList

        public DigestList​(java.io.File... sourceFiles)
           throws java.lang.Exception
        Creates a new instance and then imports digests from each provided source Nuix binary digest list file by iteratively calling importFile(File) for each.
        Parameters:
        sourceFiles - One or more Nuix binary digest list files to import into this instance.
        Throws:
        java.lang.Exception - Thrown if there is an error while importing any digest list file.

    • Method Detail

      • saveFile

        public void saveFile​(java.io.File digestListFile)
              throws java.lang.Exception
        Saves a new Nuix binary digest list based on the digests stored in memory of this instance. Will overwrite existing files.
        Parameters:
        digestListFile - The location to which to save the new digest list.
        Throws:
        java.lang.Exception - Thrown most likely if there are IO errors.

      • importFile

        public int importFile​(java.lang.String digestListFile)
               throws java.lang.Exception
        Imports digests found in given input file to this instance (if not already present).
        Parameters:
        digestListFile - The location of the input Nuix binary digest list file.
        Returns:
        How many digests were imported from the given input Nuix binary digest list file that were not already present in this instance.
        Throws:
        java.lang.Exception - Thrown most likely due to IO errors.

      • combineDigestFiles

        public static void combineDigestFiles​(java.io.File outputFile,
                                      java.util.Collection<java.io.File> inputFiles)
                               throws java.lang.Exception
        Create a new digest list file from multiple source digest lists. A convenience method for the process of creating a new DigestList instance, importing each source digest list and then saving the combined imported results to a new output digest list.
        Parameters:
        outputFile - Location to save output Nuix binary digest list file.
        inputFiles - Locations of source Nuix binary digest list files.
        Throws:
        java.lang.Exception - Thrown if an exception occurs while importing or saving combined result.

      • combineDigestFiles

        public static void combineDigestFiles​(java.lang.String outputFile,
                                      java.util.Collection<java.lang.String> inputFiles)
                               throws java.lang.Exception
        Create a new digest list file from multiple source digest lists. A convenience method for the process of creating a new DigestList instance, importing each source digest list and then saving the combined imported results to a new output digest list.
        Parameters:
        outputFile - Location to save output Nuix binary digest list file.
        inputFiles - Locations of source Nuix binary digest list files.
        Throws:
        java.lang.Exception - Thrown if an exception occurs while importing or saving combined result.

      • eachDigest

        public static void eachDigest​(java.io.File sourceDigestList,
                              java.util.function.Consumer<java.lang.String> md5StringConsumer)
                       throws java.lang.Exception
        Provides a way to iterate each MD5 string present in a given digest list file without first reading the entirety of that digest list file into memory.
        Parameters:
        sourceDigestList - The Nuix binary digest list file to read MD5 digests from.
        md5StringConsumer - Callback which will receive each MD5 as a string as it is read from the source file.
        Throws:
        java.lang.Exception - Most likely thrown if there are IO errors while reading from the source file.

      • getDigestCount

        public static int getDigestCount​(java.io.File sourceDigestList)
        Returns a count of digests present in the given Nuix binary digest list file. This is really just a convenience for the calculation:

        DIGEST_COUNT = (FILE_SIZE_BYTES - 13) / 16
        Parameters:
        sourceDigestList - The digest list file to calculate the digest count of.
        Returns:
        The number of digest lists present in the given file based on file size in bytes.

      • importFile

        public int importFile​(java.io.File digestListFile)
               throws java.lang.Exception
        Imports digests found in given input file to this instance (if not already present).
        Parameters:
        digestListFile - The location of the input Nuix binary digest list file.
        Returns:
        How many digests were imported from the given input Nuix binary digest list file that were not already present in this instance.
        Throws:
        java.lang.Exception - Thrown most likely due to IO errors.

      • saveCaseLevelDigestList

        public void saveCaseLevelDigestList​(nuix.Case nuixCase,
                                    java.lang.String name)
                             throws java.lang.Exception
        Saves a new digest list to a file located at "[CASE_DIRECTORY]\Stores\User Data\Digest Lists\[NAME].hash" (case level digest list location). If digest list file already exists, it will be overwritten.
        Parameters:
        nuixCase - The case to save the digest relative to.
        name - The name of the digest list to save.
        Throws:
        java.lang.Exception - Thrown if there is an error while saving.

      • saveUserLevelDigestList

        public void saveUserLevelDigestList​(java.lang.String name)
                             throws java.lang.Exception
        Saves a new digest list to a file located at "%appdata%\Nuix\Digest Lists\[NAME].hash" (user level digest list location). If digest list file already exists, it will be overwritten.
        Parameters:
        name - The name of the digest list to save.
        Throws:
        java.lang.Exception - Thrown if there is an error while saving.

      • saveSystemLevelDigestList

        public void saveSystemLevelDigestList​(java.lang.String name)
                               throws java.lang.Exception
        Saves a new digest list to a file located at "%programdata%\Nuix\Digest Lists\[NAME].hash" (system level digest list location). If digest list file already exists, it will be overwritten.
        Parameters:
        name - The name of the digest list to save.
        Throws:
        java.lang.Exception - Thrown if there is an error while saving.

      • importCaseLevelDigestList

        public int importCaseLevelDigestList​(nuix.Case nuixCase,
                                     java.lang.String name)
                              throws java.lang.Exception
        Imports digests from a file located at "[CASE_DIRECTORY]\Stores\User Data\Digest Lists\[NAME].hash" (case level digest list location).
        Parameters:
        nuixCase - The Nuix case the digest list is relative to.
        name - The name of the digest list to import.
        Returns:
        How many digests were imported from the given input Nuix binary digest list file that were not already present in this instance.
        Throws:
        java.lang.Exception - Thrown if there was an error while importing.

      • importUserLevelDigestList

        public int importUserLevelDigestList​(java.lang.String name)
                              throws java.lang.Exception
        Imports digests from a file located at "%appdata%\Nuix\Digest Lists\[NAME].hash" (user level digest list location).
        Parameters:
        name - The name of the digest list to import.
        Returns:
        How many digests were imported from the given input Nuix binary digest list file that were not already present in this instance.
        Throws:
        java.lang.Exception - Thrown if there was an error while importing.

      • importSystemLevelDigestList

        public int importSystemLevelDigestList​(java.lang.String name)
                                throws java.lang.Exception
        Imports digests from a file located at "%programdata%\Nuix\Digest Lists\[NAME].hash" (system level digest list location).
        Parameters:
        name - The name of the digest list to import.
        Returns:
        How many digests were imported from the given input Nuix binary digest list file that were not already present in this instance.
        Throws:
        java.lang.Exception - Thrown if there was an error while importing.

      • addItem

        public void addItem​(nuix.Item item)
        Adds the MD5 of the provided item to this instance (if not already present). If the item has no MD5 it is ignored.
        Parameters:
        item - The item for which the MD5 of will be added to this instance.

      • addItems

        public void addItems​(java.util.Collection<nuix.Item> items)
        Adds the MD5s of the provided items to this instance (if not already present). Items without and MD5 value are ignored.
        Parameters:
        items - The items for which the MD5s will be added to this instance.

      • removeItem

        public void removeItem​(nuix.Item item)
        Removes MD5 of provided item from this instance. If the item has no MD5, it is ignored.
        Parameters:
        item - The item for which the MD5 will be removed from this instance.

      • removeItems

        public void removeItems​(java.util.Collection<nuix.Item> items)
        Removes MD5s from this instance based on the MD5s of the given items. Items without an MD5 value are ignored.
        Parameters:
        items - The items for which MD5s will be removed from this instance.

      • addMd5

        public void addMd5​(java.lang.String md5)
        Adds the given MD5 to this instance (if not already present).
        Parameters:
        md5 - Hexadecimal string of MD5 to add to this instance.

      • addMd5

        public void addMd5​(byte[] md5Bytes)
        Adds the given MD5 to this instance (if not already present).
        Parameters:
        md5Bytes - Byte array of MD5 to add to this instance.

      • removeMd5

        public void removeMd5​(java.lang.String md5)
        Removes the given MD5 from this instance.
        Parameters:
        md5 - MD5 string to remove.

      • removeMd5

        public void removeMd5​(byte[] md5Bytes)
        Removes the given MD5 from this instance.
        Parameters:
        md5Bytes - MD5 byte array to remove.

      • containsMd5

        public boolean containsMd5​(byte[] md5Bytes)
        Gets whether the given MD5 is present in this instance.
        Parameters:
        md5Bytes - MD5 byte array to check for the presence of.
        Returns:
        True if the given MD5 is present in this instance.

      • containsMd5

        public boolean containsMd5​(java.lang.String md5)
        Gets whether the given MD5 is present in this instance.
        Parameters:
        md5 - MD5 string to check for the presence of.
        Returns:
        True if the given MD5 is present in this instance.

      • size

        public int size()
        Gets the count of digests present in this instance.
        Returns:
        The number of digests present.

      • findMatchingItems

        public java.util.Set<nuix.Item> findMatchingItems​(nuix.Case nuixCase,
                                                  int chunkSize)
                                           throws java.lang.Exception
        Finds items in given case which have MD5s matching those found in this instance. Searches for MD5 values rather than using "digest-list" search field, meaning this digest list does not need to exist as a file in a location Nuix can find it, it can exist purely in memory. Searches are ran using a query like "md5:(md5A OR md5B OR ...)" with chunkSize determining how many MD5s max are submit in any given single query. Items obtained through each round of searching are then added to result using ItemUtility.union until all MD5s in this instance have been searched for. Resulting set should only ever have 1 instance of any given item, but also can have multiple different items with any given MD5.
        Parameters:
        nuixCase - The case to find matching items in.
        chunkSize - How many MD5s
        Returns:
        Set of items which have MD5s matching those present in this instance.
        Throws:
        java.lang.Exception - If there is an error while searching for a chunk of items.

      • findMatchingItems

        public java.util.Set<nuix.Item> findMatchingItems​(nuix.Case nuixCase)
                                           throws java.lang.Exception
        Finds items in given case which have MD5s matching those found in this instance. Searches for MD5 values rather than using "digest-list" search field, meaning this digest list does not need to exist as a file in a location Nuix can find it, it can exist purely in memory. Searches are ran using a query like "md5:(md5A OR md5B OR ...)" with chunkSize determining how many MD5s max are submit in any given single query. Items obtained through each round of searching are then added to result using ItemUtility.union until all MD5s in this instance have been searched for. Resulting set should only ever have 1 instance of any given item, but also can have multiple different items with any given MD5.
        Parameters:
        nuixCase - The case to find matching items in.
        Returns:
        Set of items which have MD5s matching those present in this instance.
        Throws:
        java.lang.Exception - If there is an error while searching for a chunk of items.

      • iterator

        public java.util.Iterator<java.lang.String> iterator()
        Provides an iterator over the hexadecimal string versions of the MD5s present in this instance. MD5 values iterate in order of MD5 values, based on comparison logic of ByteBuffer.
        Specified by:
        iterator in interface java.lang.Iterable<java.lang.String>