Package com.nuix.enginebaseline

Class NuixEngine

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public class NuixEngine
extends java.lang.Object
implements java.lang.AutoCloseable
    This class represents a wrapper over the Nuix Engine API. It encapsulates the potentially error prone process of getting a Nuix Engine instance initialized and licensed with a simplified interface. Use this class as is or use it as a starting point for your own implementation.

    Basic usage example: 
     
 // Define a resolver which will resolve licenses from Cloud License Server (CLS),
 // authenticating using upon environment variable "NUIX_USERNAME" and "NUIX_PASSWORD",
 // that have at least 4 workers and the feature "CASE_CREATION".
 LicenseResolver cloud_4_workers = NuixLicenseResolver.fromCloud()
     .withLicenseCredentialsResolvedFromEnvVars()
     .withMinWorkerCount(4)
     .withRequiredFeatures("CASE_CREATION");

 // Define a resolver which will attempt to resolve a license from a local physical dongle
 // that has the feature "CASE_CREATION".
 LicenseResolver anyDongle = NuixLicenseResolver.fromDongle()
     .withRequiredFeatures("CASE_CREATION");

 // Create a new NuixEngine instance which will first attempt to resolve a cloud license and then
 // attempt to resolve a dongle license if one cannot be resolved from cloud, depending resolvers
 // defined above.  Calling run method to execute code with a licensed Engine instance (if a license can be obtained).
 NuixEngine.usingFirstAvailableLicense(cloud_4_workers, anyDongle)
     .setEngineDistributionDirectoryFromEnvVars()
     .run((utilities -> {
         log.info("License was obtained!");
         // Do something with Utilities and Engine here
     }));

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected NuixEngine()  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected void buildEngine()
      Builds an engine instance.
      void close()
      Cleans up resources associated with this instance: Calls close on underlying Engine instance Drop reference to obtained Utilities object Unregisters shutdown hook Shuts down logging
      static void closeGlobalContainer()  
      protected void ensureGlobalContainer()
      If we do not yet have a global container instance, creates one.
      NuixVersion getNuixVersion()
      Gets a NuixVersion object representing the Engine version as obtained by calling Engine.getVersion
      Note that if Engine instance has not yet been initialized this returns "0.0.0.0"
      java.lang.String getNuixVersionString()
      Returns the Nuix engine version by internally calling Engine.getVersion
      Note that if Engine instance has not yet been initialized this returns "0.0.0.0"
      nuix.Utilities getUtilities()
      Gets Utilities object to begin making use of the Nuix API.
      protected void initializeLogging()
      Initializes some logging details.
      protected void logAllDependencyInfo​(nuix.Utilities utilities)
      Logs information about all Nuix third party dependencies
      void run​(ThrowCapableConsumer<nuix.Utilities> throwCapableConsumer)
      Convenience method for running an operation with a licensed engine instance and then automatically closing this instance.
      RubyScriptRunner runRubyScriptAsync​(java.lang.String script, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the provided String, defaulting to logging standard/error script output.
      RubyScriptRunner runRubyScriptAsync​(java.lang.String script, @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the provided String, defaulting to logging standard/error script output.
      RubyScriptRunner runRubyScriptAsync​(java.lang.String script, @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables, @Nullable java.util.function.Consumer<java.lang.String> standardOutputReceiver, @Nullable java.util.function.Consumer<java.lang.String> errorOutputReceiver, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the provided String.
      RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the specified file, defaulting to logging standard/error script output.
      RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile, @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the specified file, defaulting to logging standard/error script output.
      RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile, @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables, @Nullable java.util.function.Consumer<java.lang.String> standardOutputReceiver, @Nullable java.util.function.Consumer<java.lang.String> errorOutputReceiver, @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
      Runs the Ruby script contained in the specified file.
      NuixEngine setEngineDistributionDirectory​(java.io.File directory)
      For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution.
      NuixEngine setEngineDistributionDirectoryFromEnvVar()
      For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution.
      NuixEngine setEngineDistributionDirectoryFromEnvVar​(java.lang.String environmentVariableName)
      For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution.
      NuixEngine setEngineDistributionDirectorySupplier​(java.util.function.Supplier<java.io.File> engineDistributionDirectorySupplier)
      For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution.
      NuixEngine setLogDirectory​(java.io.File directory)
      When logging is initialized a directory is specified in which log files are to be written.
      NuixEngine setLogDirectorySupplier​(java.util.function.Supplier<java.io.File> logDirectorySupplier)
      When logging is initialized a directory is specified in which log files are to be written.
      NuixEngine setUserDataDirectory​(java.io.File directory)
      The Nuix Engine will need to be capable of resolving various artifacts such as metadata profiles, processing profiles, export profiles, word lists, etc.
      NuixEngine setUserDataDirectorySupplier​(java.util.function.Supplier<java.io.File> userDataDirectorySupplier)
      The Nuix Engine will need to be capable of resolving various artifacts such as metadata profiles, processing profiles, export profiles, word lists, etc.
      static NuixEngine usingAnyAvailableLicense()
      Create a new instance which will attempt to retrieve its license from anywhere it can.
      static NuixEngine usingFirstAvailableLicense​(LicenseResolver... nuixLicenseResolvers)
      Creates a new instance which will attempt to retrieve its license from one of the provided LicenseResolver instances in the order specified.
      static NuixEngine usingFirstAvailableLicense​(java.util.List<LicenseResolver> nuixLicenseResolvers)
      Creates a new instance which will attempt to retrieve its license from one of the provided LicenseResolver instances in the order specified.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • engineDistributionDirectorySupplier

        protected java.util.function.Supplier<java.io.File> engineDistributionDirectorySupplier

      • logDirectorySupplier

        protected java.util.function.Supplier<java.io.File> logDirectorySupplier

      • userDataDirectorySupplier

        protected java.util.function.Supplier<java.io.File> userDataDirectorySupplier

      • nuixLicenseResolvers

        protected java.util.List<LicenseResolver> nuixLicenseResolvers

      • log

        protected org.apache.logging.log4j.Logger log

      • engine

        protected nuix.engine.Engine engine

      • utilities

        protected nuix.Utilities utilities

      • shutdownHook

        protected java.lang.Thread shutdownHook

    • Constructor Detail

      • NuixEngine

        protected NuixEngine()

    • Method Detail

      • closeGlobalContainer

        public static void closeGlobalContainer()

      • usingFirstAvailableLicense

        public static NuixEngine usingFirstAvailableLicense​(LicenseResolver... nuixLicenseResolvers)
        Creates a new instance which will attempt to retrieve its license from one of the provided LicenseResolver instances in the order specified.
        Parameters:
        nuixLicenseResolvers - One or more resolvers which will be called upon in the order provided to obtain a license until one is able to successfully acquire an available license based on its configured source and filtering/selection logic.
        Returns:
        A new NuixEngine instance

      • usingFirstAvailableLicense

        public static NuixEngine usingFirstAvailableLicense​(java.util.List<LicenseResolver> nuixLicenseResolvers)
        Creates a new instance which will attempt to retrieve its license from one of the provided LicenseResolver instances in the order specified.
        Parameters:
        nuixLicenseResolvers - List of one or more resolvers which will be called upon in the order provided to obtain a license until one is able to successfully acquire an available license based on its configured source and filtering/selection logic.
        Returns:
        A new NuixEngine instance

      • usingAnyAvailableLicense

        public static NuixEngine usingAnyAvailableLicense()
        Create a new instance which will attempt to retrieve its license from anywhere it can.
        Returns:
        A new NuixEngine instance

      • setEngineDistributionDirectorySupplier

        public NuixEngine setEngineDistributionDirectorySupplier​(java.util.function.Supplier<java.io.File> engineDistributionDirectorySupplier)
        For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution. This method allows you to provide a Supplier which will resolve it as needed. Note that due to the importance of being able to resolve this, you must configure this value via one of the following methods before calling run(ThrowCapableConsumer), or you will get an error:
        Parameters:
        engineDistributionDirectorySupplier - A supplier which will yield directory containing a Nuix Engine distribution.
        Returns:
        This instance for method call chaining

      • setEngineDistributionDirectoryFromEnvVar

        public NuixEngine setEngineDistributionDirectoryFromEnvVar​(java.lang.String environmentVariableName)
        For various reasons, this class needs to be able to resolve the location of a Nuix Engine distribution. This method allows you to specify an environment variable which contains as its value the a directory containing a Nuix Engine distribution. Note that due to the importance of being able to resolve this, you must configure this value via one of the following methods before calling run(ThrowCapableConsumer), or you will get an error:
        Parameters:
        environmentVariableName - The name of the environment variable which has its value set to a directory containing a Nuix Engine distribution.
        Returns:
        This instance for method call chaining

      • setLogDirectorySupplier

        public NuixEngine setLogDirectorySupplier​(java.util.function.Supplier<java.io.File> logDirectorySupplier)
        When logging is initialized a directory is specified in which log files are to be written. Calling this method allows you to provide a Supplier which will yield that directory when needed. Directory will be created if it does not exist. If neither this method nor the method setLogDirectory(File) are called before logging initialization, then a default will be assumed in the form of "%LOCAL_APP_DATA%\Nuix\Logs\Engine-[DATE]-[TIME]".
        Parameters:
        logDirectorySupplier - A Supplier which will yield a log directory to use
        Returns:
        This instance for method call chaining

      • setLogDirectory

        public NuixEngine setLogDirectory​(java.io.File directory)
        When logging is initialized a directory is specified in which log files are to be written. Calling this method allows you to set an explicit directory to use. Directory will be created if it does not exist. If neither this method nor the method setLogDirectorySupplier(Supplier) are called before logging initialization, then a default will be assumed in the form of "%LOCAL_APP_DATA%\Nuix\Logs\Engine-[DATE]-[TIME]".
        Parameters:
        directory - The log file directory to use
        Returns:
        This instance for method call chaining

      • setUserDataDirectorySupplier

        public NuixEngine setUserDataDirectorySupplier​(java.util.function.Supplier<java.io.File> userDataDirectorySupplier)
        The Nuix Engine will need to be capable of resolving various artifacts such as metadata profiles, processing profiles, export profiles, word lists, etc. This method allows you to provide a Supplier which will yield a directory containing this information as needed. If neither this method nor the method setUserDataDirectory(File) are called before calling run(com.nuix.enginebaseline.ThrowCapableConsumer<nuix.Utilities>), the "user-data" subdirectory of the Nuix Engine distribution will be used.
        Parameters:
        userDataDirectorySupplier - A Supplier which will yield directory containing engine user data
        Returns:
        This instance for method call chaining

      • setUserDataDirectory

        public NuixEngine setUserDataDirectory​(java.io.File directory)
        The Nuix Engine will need to be capable of resolving various artifacts such as metadata profiles, processing profiles, export profiles, word lists, etc. This method allows you to provide an explicit user data directory. If neither this method nor the method setUserDataDirectorySupplier(Supplier) are called before calling run(com.nuix.enginebaseline.ThrowCapableConsumer<nuix.Utilities>), the "user-data" subdirectory of the Nuix Engine distribution will be used.
        Parameters:
        directory - The user data directory to use
        Returns:
        This instance for method call chaining

      • getUtilities

        public nuix.Utilities getUtilities()
                            throws java.lang.Exception
        Gets Utilities object to begin making use of the Nuix API. If instance has been previously obtained, then that instance will be returned. Otherwise, calling this method performs a series of steps to get setup:
        1. A set of preconditions are checked. Generally if a condition is not met an exception explaining the issue will be thrown. In a couple instances a default will be assumed if possible.
          • Can we resolve an engine distribution?
          • Can we resolve a log directory?
          • Can we resolve a user data directory?
          • Does the system PATH have a reference to "[ENGINE_DIR]\bin"?
          • Does the system PATH have a reference to "[ENGINE_DIR]\bin\x86"?
        2. Logging is initialized
        3. The Nuix Engine GlobalContainer instance is created if needed
        4. An Engine instance is created
        5. Any provided NuixLicenseResolver instances are iteratively called upon to obtain a license until an instance has successfully acquired one.
        6. The callback provided when calling this method is invoked with a licenses Utilities object if license acquisition was successful.
        7. If an exception is thrown during this process, it is caught, written to System.out and then rethrown to be further handled by the caller.
        Note that before calling this method you must call one of the following methods to configure where a Nuix Engine distribution is located:
        Returns:
        If this instance already has an instance of Utilities, that is returned. Otherwise necessary steps will be taken to attempt to obtain and license underlying engine instance to ultimately provide a licensed Utilities instance.
        Throws:
        java.lang.Exception - Allows exceptions to bubble up so caller can handle them.

      • run

        public void run​(ThrowCapableConsumer<nuix.Utilities> throwCapableConsumer)
         throws java.lang.Exception
        Convenience method for running an operation with a licensed engine instance and then automatically closing this instance. Supplied consumer will be provided a utilities instance by internally calling getUtilities(). Upon return from consumer, either from normal return or exception, a 'finally' block will call the close() method for you. Exceptions will be allowed to bubble up, so caller can handle them directly.
        Parameters:
        throwCapableConsumer - A callback which is to receive Utilities upon successful initialization and licensing.
        Throws:
        java.lang.Exception - May be thrown by process or getting engine initialized or code in supplied consumer.

      • initializeLogging

        protected void initializeLogging()
        Initializes some logging details.

      • ensureGlobalContainer

        protected void ensureGlobalContainer()
        If we do not yet have a global container instance, creates one.

      • buildEngine

        protected void buildEngine()
        Builds an engine instance. Also registers a shutdown hook will attempt to release any license held by this instance in some situations which my not otherwise be handled cleanly. If this shutdown hook was not in place it is possible for a license to remain claimed after the claiming process has ended and until a timeout period has elapsed for the license.

      • getNuixVersionString

        public java.lang.String getNuixVersionString()
        Returns the Nuix engine version by internally calling Engine.getVersion
        Note that if Engine instance has not yet been initialized this returns "0.0.0.0"
        Returns:
        A String representing the Nuix Engine version or "0.0.0.0" if Engine has not yet been initialized.

      • getNuixVersion

        public NuixVersion getNuixVersion()
        Gets a NuixVersion object representing the Engine version as obtained by calling Engine.getVersion
        Note that if Engine instance has not yet been initialized this returns "0.0.0.0"
        Returns:
        A NuixVersion object representing the Nuix Engine version or one representing "0.0.0.0" if Engine has not yet been initialized.

      • runRubyScriptAsync

        public RubyScriptRunner runRubyScriptAsync​(java.lang.String script,
                                           @Nullable
                                           @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables,
                                           @Nullable
                                           @Nullable java.util.function.Consumer<java.lang.String> standardOutputReceiver,
                                           @Nullable
                                           @Nullable java.util.function.Consumer<java.lang.String> errorOutputReceiver,
                                           @Nullable
                                           @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                    throws java.lang.Exception
        Runs the Ruby script contained in the provided String. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        script - The Ruby script to execute. Cannot be null.
        additionalVariables - A map of any additional global/local variables you would like to set. Note that constants cannot be set using this approach. Can be null.
        standardOutputReceiver - Consumer which will receive standard output messages. If null is provided, will default to logging info messages.
        errorOutputReceiver - Consumer which will receive error output messages. If null is provided, will default to logging error messages.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • runRubyScriptAsync

        public RubyScriptRunner runRubyScriptAsync​(java.lang.String script,
                                           @Nullable
                                           @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables,
                                           @Nullable
                                           @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                    throws java.lang.Exception
        Runs the Ruby script contained in the provided String, defaulting to logging standard/error script output. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        script - The Ruby script to execute. Cannot be null.
        additionalVariables - A map of any additional global/local variables you would like to set. Note that constants cannot be set using this approach. Can be null.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • runRubyScriptAsync

        public RubyScriptRunner runRubyScriptAsync​(java.lang.String script,
                                           @Nullable
                                           @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                    throws java.lang.Exception
        Runs the Ruby script contained in the provided String, defaulting to logging standard/error script output. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        script - The Ruby script to execute. Cannot be null.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • runRubyScriptFileAsync

        public RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile,
                                               @Nullable
                                               @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables,
                                               @Nullable
                                               @Nullable java.util.function.Consumer<java.lang.String> standardOutputReceiver,
                                               @Nullable
                                               @Nullable java.util.function.Consumer<java.lang.String> errorOutputReceiver,
                                               @Nullable
                                               @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                        throws java.lang.Exception
        Runs the Ruby script contained in the specified file. Note that since you are pointing to an actual file, script will have a defined value for __FILE__, allowing for you to reference other files relative to the specified script file. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        scriptFile - The file containing the Ruby script to execute. Cannot be null.
        additionalVariables - A map of any additional global/local variables you would like to set. Note that constants cannot be set using this approach. Can be null.
        standardOutputReceiver - Consumer which will receive standard output messages. If null is provided, will default to logging info messages.
        errorOutputReceiver - Consumer which will receive error output messages. If null is provided, will default to logging error messages.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • runRubyScriptFileAsync

        public RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile,
                                               @Nullable
                                               @Nullable java.util.Map<java.lang.String,​java.lang.Object> additionalVariables,
                                               @Nullable
                                               @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                        throws java.lang.Exception
        Runs the Ruby script contained in the specified file, defaulting to logging standard/error script output. Note that since you are pointing to an actual file, script will have a defined value for __FILE__, allowing for you to reference other files relative to the specified script file. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        scriptFile - The file containing the Ruby script to execute. Cannot be null.
        additionalVariables - A map of any additional global/local variables you would like to set. Note that constants cannot be set using this approach. Can be null.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • runRubyScriptFileAsync

        public RubyScriptRunner runRubyScriptFileAsync​(java.io.File scriptFile,
                                               @Nullable
                                               @Nullable java.util.function.BiConsumer<java.lang.Object,​org.jruby.embed.internal.BiVariableMap> completedCallback)
                                        throws java.lang.Exception
        Runs the Ruby script contained in the specified file, defaulting to logging standard/error script output. Note that since you are pointing to an actual file, script will have a defined value for __FILE__, allowing for you to reference other files relative to the specified script file. The following variables/constants are injected into the Ruby environment before executing the script:
        • $utilities - The Nuix utilities object
        • $nuix_version - A NuixVersion object representing the current engine version
        • NUIX_VERSION - A String containing the current engine version
        Parameters:
        scriptFile - The file containing the Ruby script to execute. Cannot be null.
        completedCallback - Optional callback to be invoked upon script completion. Callback provided implicit value of last script operation as well as map of variables.
        Returns:
        A RubyScriptRunner instance. Call RubyScriptRunner.join() to wait for script to complete.
        Throws:
        java.lang.Exception - Exceptions are allowed to bubble up.

      • logAllDependencyInfo

        protected void logAllDependencyInfo​(nuix.Utilities utilities)
        Logs information about all Nuix third party dependencies
        Parameters:
        utilities - Needs an instance of Utilities to get access to third party dependency information

      • close

        public void close()
           throws java.lang.Exception
        Cleans up resources associated with this instance:
        • Calls close on underlying Engine instance
        • Drop reference to obtained Utilities object
        • Unregisters shutdown hook
        • Shuts down logging
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        java.lang.Exception - If thrown, was a result of a method being called by this method and allowed to bubble up to caller.