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 arguments 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.5.4</version>
        </dependency>
    </dependencies>
</project>

Gradle

apply plugin: 'java'

sourceCompatibility = 1.8
targetCompatibility = 1.8

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

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 (WebSocket 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 io = 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 or INI files to externalize your configuration. The following example demonstrates specifying a name for your app in a glue.conf file:

glue {
    application: "My Java App"
}

io.Connect Java will look for an io.Connect configuration file named glue (e.g., glue.conf, glue.json, etc.) 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 configuration file, 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 at runtime when initializing the io.Connect Java library, which will override any previous configurations:

Glue io = 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": "My Java App",
        "type": "exe",
        "name": "my-java-app",
        "details": {
            "path": "%GDDIR%/../Demos/MyJavaApp/",
            "command": "MyJavaApp.exe",
            "parameters": "-jar example.jar"
        }
    }
]

⚠️ Note that if you want to pass arguments 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".

⚠️ Note that 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 argument to the JVM by specifying it in the "parameters" property.

The "name", "type" and "path" properties are required and "type" must be set to "exe". The "path" property points to the app working directory.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

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: