You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
View the GitHub project [here](https://github.com/Nuix/Nuix-Java-Engine-Baseline) or download the latest release [here](https://github.com/Nuix/Nuix-Java-Engine-Baseline/releases).
7
7
@@ -17,37 +17,21 @@ This repository contains a series of examples making use of the Java Engine API
17
17
18
18
## Setup
19
19
20
-
- To begin you will need to [download a release](https://download.nuix.com/releases/engine) of the Nuix Java Engine and extract that somewhere on your local machine. You will want to extract the engine release to a directory with a relatively short name such as the following:
21
-
```
22
-
D:\engine-releases\9.2.4.392
23
-
```
24
-
- Have a Nuix license available on a Nuix license dongle, available from a Nuix Management Server instance or available from the Nuix Cloud License Server.
25
-
- Download a copy of this repository and open the `Java` sub directory in your IDE of choice. Add the contents of the `lib` sub directory of your engine release to your project's build path.
26
-
- Ensure that the Windows `PATH` environment variable references the `bin` sub directory of your engine release as well as the `bin\x86` directory. For example if I have my engine distribution located at `D:\engine-releases\9.2.4.392`, I will want to add the following to my `PATH`:
27
-
-`D:\engine-releases\9.2.4.392\bin`
28
-
-`D:\engine-releases\9.2.4.392\bin\x86`
29
-
- Build your project and export a JAR file.
30
-
31
-
The package `com.nuix.javaenginebaseline.examples` contains a series of examples demonstrating fundamental activities. Each example is executable (they have a static void main method). For example, to run the example [BasicInitializationExample]:
32
-
33
-
1. Build the project
34
-
2. Export a JAR file to a location such as `C:\MyCustomNuixApp\MyApp.jar`
35
-
3. Execute the `main` method of the class `BasicInitializationExample` using a 64-bit JRE (Java Runtime Environment) with a command along the lines of:
This project makes use of [Gradle](https://gradle.org/) and has been tested with [IntelliJ Idea IDE](https://www.jetbrains.com/idea/). It may work with other IDEs such as [Eclipse](https://www.eclipse.org/eclipseide/) as well, but it has only been tested in IntelliJ Idea.
21
+
22
+
[Gradle](https://gradle.org/) is a build automation tool. While it adds a small degree of additional complexity (the [build.gradle](https://github.com/Nuix/Nuix-Java-Engine-Baseline/blob/master/IntelliJ/build.gradle) file is not the most straightforward) it does provide some benefits that make it worth the additional complexity.
39
23
40
-
A breakdown of the above command:
41
-
- Uses the `-classpath` argument to include on the class path:
42
-
- All jars in `D:\engine-releases\9.2.4.392\lib`
43
-
- All jars in local directory so that `MyApp.jar` is picked up
44
-
- Specifies the fully qualified name (`com.nuix.javaenginesimple.examples.BasicInitializationExample`) of our class [BasicInitializationExample] which contains the `public static void main(String[] args)` method (an entry point into the program).
24
+
1. If you do not already have it installed, download and install [IntelliJ Idea IDE](https://www.jetbrains.com/idea/download/#section=windows) (the community edition should be fine).
25
+
1. Download or clone this repository to your development machine.
26
+
1. Download a Nuix Java Engine API release zip file and extract its contents to the `engine` sub-directory of your local copy.
27
+
1. Start IntelliJ Idea and open project by selecting `\Nuix-Java-Engine-Baseline\IntelliJ\build.gradle`.
28
+
1. Import process should begin. This can take a few minutes as dependencies are pulled down from the internet, dependencies are indexed, etc.
45
29
46
30
# Basic Overview
47
31
48
-
In the example above, we start by executing the `main` method of the [BasicInitializationExample] class. The method begins by creating a new instance of the [EngineWrapper] class, providing it the root directory of the engine release we downloaded earlier. At this point not much has happened. Its once we call[withDongleLicense], [withServerLicense] or [withCloudLicense]that the [EngineWrapper] class gets to work.
32
+
In the various examples, we start by executing the `main` method of the relevant class. The method begins by creating a new instance of the [EngineWrapper] class, providing it the root directory of the engine release. From there we obtain a licensed instance of the Engine by calling[withDongleLicense], [withServerLicense] or [withCloudLicense]method of the [EngineWrapper] class.
49
33
50
-
Note that the classes (such as [EngineWrapper]) provided in this project are not required to use the engine API, instead they demonstrate one way you can implement the Nuix engine initialization process.
34
+
Note that many of the classes (such as [EngineWrapper]) provided in this project are not required to use the engine API. Instead they provide a demonstration of how you might approach license acquisition, engine initialization, etc.
51
35
52
36
## EngineWrapper
53
37
@@ -132,7 +116,7 @@ For example, if I wish to only acquire a license which:
132
116
You configure the license filter to only acquire licenses meeting this criteria with the following code:
@@ -217,13 +201,13 @@ Once a license has been obtained by [EngineWrapper] and a `Utilities` object has
217
201
218
202
## NuixDiagnostics
219
203
220
-
When there is a problem, it is helpful to capture a snapshot of the state of things for trouble shooting purposes. In the Nuix Workbench GUI we can generate a diagnostics file with the click of a button. When using the Java engine API we have to do a bit more work. The class [NuixDiagnostics] provides a method [saveDiagnosticsToDirectory](https://nuix.github.io/Nuix-Java-Engine-Baseline/com/nuix/javaenginesimple/NuixDiagnostics.html#saveDiagnosticsToDirectory-java.lang.String-) which can generate a Nuix diagnostics file for you. The method accepts as an argument the directory (as a String or [java.io.File](https://docs.oracle.com/javase/8/docs/api/java/io/File.html)) to which the diagnostics zip will be saved. The generated zip file will automatically be given a time stamped name in the form `NuixEngineDiagnostics-yyyyMMddHHmmss.zip`, for example `NuixEngineDiagnostics-20200408113545.zip`.
204
+
When there is a problem, it is helpful to capture a snapshot of the state of things for trouble shooting purposes. In the Nuix Workbench GUI we can generate a diagnostics file with the click of a button. When using the Java engine API we have to do a bit more work. The class [NuixDiagnostics] provides a method [saveDiagnosticsToDirectory](https://nuix.github.io/Nuix-Java-Engine-Baseline/com/nuix/javaenginesimple/NuixDiagnostics.html#saveDiagnosticsToDirectory-java.lang.String-) which can generate a Nuix diagnostics file for you. The method accepts as an argument the directory (as a String or [java.io.File](https://docs.oracle.com/javase/8/docs/api/java/io/File.html)) to which the diagnostics zip will be saved. The generated zip file will automatically be given a time stamped name in the form `NuixEngineDiagnostics-yyyyMMddHHmmss.zip`, for example `NuixEngineDiagnostics-20220204113545.zip`.
221
205
222
206
In the example [saveDiagnosticsToDirectory](https://nuix.github.io/Nuix-Java-Engine-Baseline/com/nuix/javaenginesimple/NuixDiagnostics.html#saveDiagnosticsToDirectory-java.lang.String-) is called when an exception bubbles all the way up to our main `try`/`catch`.
1. Double-click one of the tasks to run the corresponding example (**BasicInitialization** is a good initial test).
233
+
234
+
# Gradle Build File
235
+
236
+
The `plugins` section allows us to include plugins that provide functionality to our build file. We include the `java` plugin which provides various functionality for a Java project.
237
+
238
+
```groovy
239
+
plugins {
240
+
id 'java'
241
+
}
242
+
```
243
+
244
+
The `repositories` section allows use to define where dependencies may be resolved from. Note that in addition to specifying dependencies be resolved from Maven, we also specify the `lib` sub-directory of the Nuix Java Engine release we have downloaded.
245
+
246
+
```groovy
247
+
repositories {
248
+
mavenCentral()
249
+
flatDir { dirs 'engine/lib' }
250
+
}
251
+
```
252
+
253
+
In the `dependencies` section we declare some dependencies as well as whether they are needed during development/compilation (`implementation`), or just on the class path while executing (`runtimeOnly`), etc. Note that we include Nuix scripting and engine jars from the `lib` sub-directory of the Nuix Java Engine release we have downloaded for development time and all the `lib` jars for run-time.
In the following section we specify that we need to use a version of Java that supports the Java 11 language specification.
275
+
276
+
```groovy
277
+
java {
278
+
toolchain {
279
+
languageVersion = JavaLanguageVersion.of(11)
280
+
}
281
+
}
282
+
```
283
+
284
+
Next we define some values that we will make use of in the rest of the file:
285
+
-`engineDirectory`: The location of out engine release, relative to the project directory (the `engine` sub-directory).
286
+
-`engineBinDirectory`, `engineX86BinDirectory`: Two directories within the engine release sub-directory that need to be on the `PATH` environment variable at run-time.
287
+
-`rootLogDir`: The location we will direct logs to be generated in, relative to the project directory (the `logs` sub-directory).
288
+
-`envPath`: The `PATH` environment variable we will inject into the JVM when running tests. The engine and worker processes need to be able to resolve some binaries on the `PATH`. This allows us to define a custom `PATH` value for our JVM that will point to the appropriate engine directories (relative to this project) without needing to alter the machine's actual `PATH` environment variable.
We define a series of JVM arguments we want to be used each time we run our code in a JVM. These arguments define some important things such as engine directory, log directory, accessible temp directory.
299
+
300
+
```groovy
301
+
def defaultJvmArgs = [
302
+
// Necessary for newer versions of Nuix. Without this you will likely see
303
+
// an error regarding loading the BouncyCastle crypto library at run-time
Beyond that, a series of [JavaExec tasks](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.JavaExec.html) are defined, each which provides a way to run one of the examples.
319
+
243
320
# License
244
321
245
322
```
246
-
Copyright 2021 Nuix
323
+
Copyright 2022 Nuix
247
324
248
325
Licensed under the Apache License, Version 2.0 (the "License");
249
326
you may not use this file except in compliance with the License.
@@ -262,6 +339,6 @@ limitations under the License.
0 commit comments