Installing the Tools

Prerequisite Downloads

The following software is required to use the Utilihive SDK and corresponding DSL:

  • Java 17

    The Java Development Kit (JDK) installer from Amazon Corretto will automatically set the necessary Java path variables for you. If you prefer using the command line instead, a Java 17 JDK can be installed with the SDKMAN tool.

    Utilihive SDK version 10.x and older required Java 11. If you are upgrading Utilihive SDK from an older version, make sure to install Java 17 and update your Intellij project to use it. In this case, it is best to uninstall Java 11 to avoid confusion.  
     
    It is a requirement that your default java command is at version 17.  
    When you run java -version on your command line, it must report jdk version 17. If this is not the case, you need to either set Java 17 as the default or uninstall any other versions of Java from your machine.

  • IntelliJ IDEA

    The IntelliJ code editor comes with built-in support for Kotlin and is the easiest way to interface with the Utilihive SDK. The free Community edition of IntelliJ is sufficient.

    Linux users, make sure to read the Install-Linux-tar.txt file for help on how to start IntelliJ after downloading it.

  • Git

    It’s recommended to start with an example project, which is downloaded as a Git repository. Windows and macOS users can optionally install Git through IntelliJ as part of the project setup.

Maven Configuration

The Utilihive SDK is installed as a project dependency with Maven. However, only licensed users are able to access and use the SDK. If you need help with your license, please contact Utilihive Support.

The Maven build tool can be downloaded as separate software, but the embedded version of Maven that comes with IntelliJ will also work. Whichever version you use, the next step is to configure Maven to use your licensed credentials. On your computer, create a settings.xml file in the $HOME/.m2 directory. For Windows, this would be C:\Users\<username>\.m2.

The .m2 directory might need to be created manually if it doesn’t already exist. On macOS and Linux, .m2 is a hidden directory and can be viewed using the ls -a command.

In the settings.xml file, add the following code:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <servers>
    <server>
      <id>utilihive-sdk</id>
      <username>YOUR USERNAME</username>
      <password>YOUR PASSWORD</password>
    </server>
  </servers>
</settings>
If you already have a settings.xml file, then simply add the utilihive-sdk <server> element to the existing list of servers.

Lastly, insert your own credentials in the <username> and <password> elements.

Project Setup

Example Project

The recommended approach for using the Utilihive SDK is to start with the official example project. This scaffolded project already has the dependencies needed to run the included tests and sample configurations. It can be cloned from the following GitHub URL:

https://github.com/utilihive/flow-developer-example-project-mvn.git

Open the IntelliJ editor and select File > New > Project from Version Control. Enter the GitHub URL and select Clone. The following image demonstrates what this process looks like:

The Get from Version Control window has the URL field set to the example project’s URL.

After the project has been cloned and opened in IntelliJ, verify that it’s using the correct JDK by navigating to File > Project Structure. Under the Project SDK setting, make sure the Java 17 JDK is selected and not <No SDK>. The following image demonstrates what you should see:

The Project Structure window displays a Project SDK dropdown with Java 17 selected.

Wait a moment for IntelliJ to finish downloading the project’s dependencies, and then you’re all set!

Windows users might see a pop-up warning about Windows Defender affecting performance. If you see this, select "Exclude directories" to prevent unnecessary virus scans on your project and IDE directories. For other antivirus programs and other OSs, it’s recommended to configure similar exclusions.

Now that you have a project set up, check out the flow tutorials for next steps.

Manual Setup

If you prefer to start with en empty IntelliJ project, do not forget to add the necessary dependencies to your pom.xml file including the Utilihive SDK. You can check the pom.xml file of the example project for reference.

Downloading Sources

Whether you are using the example project or your own project, it’s recommended that you download the Maven sources for the SDK’s dependencies. This gives you the ability to hover over processor properties and see immediate, contextual documentation directly in IntelliJ. For example, the following image displays documentation for an id property:

The "id" property displays a pop-up underneath with an explanation of valid characters.

To enable this feature in IntelliJ, select File > Settings on Windows and Linux or IntelliJ IDEA > Settings on macOS. Select "Build, Execution, Deployment", then Build Tools, Maven, and finally Importing. In the "Automatically download" section, make sure the Sources option is checked. The screen should look like the following image:

The Preferences window shows that "Sources" is checked next to "Automatically download".

If you don’t want Maven sources to be automatically downloaded, or the auto-download doesn’t seem to be working, you can still manually trigger a source download. Expand the Maven tool window on the right, then select the download button and the Download Sources option. The following image demonstrates what you should see:

The Maven tool window displays an option to download sources and/or documentation.