How to...

Installation

The io.Connect Java library provides an easy way to make your enterprise Java apps interop-enabled. You can use the io.Connect Java library in the same way as any standard Java library.

The io.Connect Java library is available as a package in the Maven Central Repository and as a part of the io.Connect Desktop installer. It is highly recommended to use the shaded version of the library from the java-glue42-shaded artifact.

io.Connect Java requires JDK 8+ (Java SE 8+) and is JDK 9+ ready.

For io.Connect Java to work with Java SE 17+, you must pass the following parameters to the JVM:

--add-opens java.desktop/java.awt=ALL-UNNAMED
--add-opens java.desktop/sun.awt.windows=ALL-UNNAMED
--add-exports java.desktop/java.awt.peer=ALL-UNNAMED

Maven

<?xml version="1.0" encoding="utf-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>myproject</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.glue42</groupId>
            <artifactId>java-glue42-shaded</artifactId>
            <version>1.4.14</version>
        </dependency>
    </dependencies>
</project>

Gradle

apply plugin: 'java'

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    compile 'com.glue42:java-glue42-shaded:1.4.14'
}

Referencing & Initialization

To use io.Connect Java in your apps, add the io.Connect Java library and its dependencies to your app classpath, import the Glue class and create a Glue instance.

The following example demonstrates how to initialize the io.Connect Java library and access information about the io.Connect version, environment and region:

import com.tick42.glue.Glue;

try (Glue io = Glue.builder().build())
{
    // Print out the io.Connect version.
    System.out.println(io.version());

    // Print out the io.Connect environment.
    System.out.println(io.env());

    // Print out the io.Connect region.
    System.out.println(io.region());
}

Glue is the main entry point of the SDK. It is thread-safe and you should create a single instance (per io.Connect app) and share it throughout your code.

Always close the Glue instance once you are done with it, in order to free up underlying resources (ws connections, thread pools, etc.). This example uses a try block, because Glue extends AutoCloseable - in a real app, you will probably call close() or closeAsync() explicitly.

App Shutdown

When initializing io.Connect, you can pass an event listener that will notify your app when it is about to be stopped. This is useful when your app/process isn't started directly by io.Connect, but rather by io.Connect invoking a script/batch file or another app that in turn starts your app. With this listener you can properly shut down your app, free resources, etc.

Below is an example of passing a shutdown request listener when initializing io.Connect:

Glue.builder()
        .withShutdownRequestListener(io -> {
            System.out.println("Starting shutdown procedure...");
            io.closeAsync();
        })
        .build();

App Definition

To define your interop-enabled Java app and add it to the io.Connect launcher, you can use CONF, PROPERTIES, JSON files and system properties to externalize your configuration. For example, if you want to specify a name for your app, you can do so in a glue.conf file:

glue {
    application: "My Java App"
}

io.Connect Java will look for an io.Connect configuration file in the app classpath. If you are using Maven or Gradle as a build tool, you can place the glue.conf file for your app in the /src/main/resources folder of your project directory.

If you don't specify an app name in a glue.conf file, as in the example above, the name of the app will be taken from the io.Connect Desktop starting context which contains app definitions from JSON files.

You can also set the app name runtime when initializing the io.Connect Java library, which will override any previous configurations:

Glue.builder().withApplicationName("My Java App").build();

JSON app definition files must be placed in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO).

The following is an example JSON configuration for a Java app:

[
    {
        "title": "Java Example",
        "type": "exe",
        "name": "java-example",
        "details": {
            "path": "",
            "command": "java",
            "parameters": "-jar example.jar",
            "mode": "tab"
        }
    }
]

⚠️ Note that if you want to pass parameters to the JVM - e.g., to ensure compatibility of io.Connect Java with Java SE 17+ (see Installation), you must pass them before the command for running the executable JAR file - e.g., before "-jar example.jar".

Property Description
"type" Must be "exe".
"path" The path to the app - relative or absolute.
"command" The actual command to execute (java).
"parameters" Specifies command line arguments.

To be able to start io.Connect Java on a dual core machine, you have to pass the -Dglue.gateway.ws.max-pool-size=3 parameter to the JVM by adding it to the "parameters" property described above.

For more details, see the Developers > Configuration > Application section.

io.Connect Java Concepts

Once the io.Connect Java library has been initialized, your app has access to all io.Connect functionalities. For more detailed information on the different io.Connect capabilities and APIs, see: