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's 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:

Classpath

--add-opens java.desktop/java.awt=ALL-UNNAMED
--add-exports java.desktop/java.awt.peer=ALL-UNNAMED
--add-opens javafx.graphics/javafx.stage=ALL-UNNAMED
--add-exports javafx.graphics/com.sun.javafx.tk=ALL-UNNAMED

Modules

--add-opens java.desktop/java.awt=io.connect.desktop.client.sticky.windows
--add-exports java.desktop/sun.awt.windows=io.connect.desktop.client.sticky.windows
--add-opens javafx.graphics/javafx.stage=io.connect.desktop.client.sticky.windows
--add-exports javafx.graphics/com.sun.javafx.tk=io.connect.desktop.client.sticky.windows

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

Gradle

apply plugin: 'java'

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    compile 'com.glue42:java-glue42-shaded:1.7.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's 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's 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 <installation_location>/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 on defining apps, see the Developers > Configuration > Application section.

1.7.5
Release date: 13.03.2025
New Features

Added Connection API.

Added configuration for WebSocket upgrade request timeout.

Improvements & Bug Fixes

Dynamic Citrix Virtual Channels reconnection fixes.

Fixed regression in handshake timeout for Dynamic Citrix Virtual Channels (introduced in 1.7.4).

Shutdown improvements.

1.7.4
Release date: 05.03.2025
Improvements & Bug Fixes

Shutdown is now completed on Elastic scheduler.

Dynamic Citrix Virtual Channels enhancements.

1.7.3
Release date: 27.02.2025
Improvements & Bug Fixes

Decreased the default maximum wait timeout for dynamic Citrix Virtual Channels from 60 to 10 seconds.

Decreased the default connection retries for dynamic Citrix Virtual Channels from 10 to 0.

Fixed possible buffer loss in dynamic Citrix Virtual Channels when the wait timeout is exceeded before data has been received.

1.7.2
Release date: 13.02.2025
New Features

Dynamic Citrix Virtual Channels parse handshake timeout (defaults to 10 seconds).

1.7.1
Release date: 07.02.2025
New Features

Added a filterHandlers() method in the Intents API.

Added a ready() method to the ApplicationInstance object.

Added retry logic when trying to connect to a dynamic Citrix Virtual Channel.

Improvements & Bug Fixes

Upgraded to gateway-client 1.4.1.

Upgraded to jetty 9.4.56.v20240826.

Upgraded to jna 5.16.0.

Upgraded to asm 9.7.1.

Upgraded to assertj 3.27.3.

Upgraded to log4j 2.24.3.

Upgraded to junit 5.11.4.

The onClose() method of the ApplicationInstance object is now completed when an app is started from the current app.

1.7.0
Release date: 21.01.2025
New Features

Added support for using an Intents Resolver.

Added a register() method to the Intents API for registering apps as Intent handlers dynamically. This method allows the Intent handlers to receive information about the app instance that has raised the Intent.

Added support for Intent result type.

The registerInstanceHandler() method in the App Management API now allows customizing dynamic definitions of child apps.

Added a multi window JavaFX demo.

Improvements & Bug Fixes

Improved error handling in the Intents API (handling specific exceptions).

The addSaveListener() method of the Layouts API now works with asynchronous listeners too.

The default Gateway URL was changed from ws://127.0.0.1:8385/gw to ws://127.0.0.1:8385/.

Upgraded to reactor 2020.0.47.

Upgraded to log4j 2.24.2.

Added Support for context domain v3 (>2) (i.e., support for working with Gateway next).

Bug fixes in modularization.

Started to serialize io.Connect Window options set to true by default.

1.6

1.6.0
Release date: 19.11.2024
New Features

Added Pub/Sub API.

Added initial support for JavaFX (partial Citrix).

Added support for provider context for custom authenticators (requires gateway-client 1.4 or later).

Added module declarations prefixed with io.connect.desktop.client.

Improvements & Bug Fixes

App name from the starting context now has more precedence than the one defined in a glue.conf file (and its sources).

Started waiting for the Interop instance to be resolved by the Gateway when starting (fixed regression from io.Connect Java 1.5.4).

Race condition on window manager startup (was causing window to close)

Increased default window registration timeout from 10 to 60 seconds.

Improved logging for io.Connect Windows.

Upgraded to gateway-client 1.4.0.

Upgraded to junit 5.11.3.

1.5

1.5.4
Release date: 23.08.2024
New Features

Added initial support for reconnecting to the io.Connect Gateway.

Improvements & Bug Fixes

Fixes related to the support for dynamic Citrix Virtual Channels.

Fixes related to Channel contexts.

Upgraded to gateway-client 1.3.17.

Upgraded to jetty 9.4.55.v20240627.

Upgraded to slf4j 2.0.16.

Upgraded to assertj 3.25.3.

Upgraded to junit 5.10.3.

1.5.3
Release date: 20.05.2024
Improvements & Bug Fixes

The custom component for text extraction passed via the withClickStreamMetrics() method is now respected.

Reduced duplicated click events for Click Stream metrics.

1.5.2
Release date: 29.04.2024
New Features

Added Click Stream metrics.

Added a configuration option for the Gateway WebSocket heartbeat interval.

Improvements & Bug Fixes

Upgraded to gateway-client 1.3.16.

Upgraded to slf4j 2.0.13.

1.5.1
Release date: 28.03.2024
Improvements & Bug Fixes

Added more logging to detect error cause when unable to connect to a dynamic Citrix Virtual Channel.

1.5.0
Release date: 15.03.2024
Improvements & Bug Fixes

Change default region and environment to INTEROP.IO and DEMO respectively.

Started using the frame title if not specified explicitly in the window options in Citrix/headless mode.

Started processing window commands on the event dispatch thread.

Upgrade to gateway-client 1.3.15.

Upgrade log4j to 2.23.1.

Dynamic apps are now registered with type Citrix when in Citrix mode.

1.4

1.4.18
Release date: 21.02.2024
Improvements & Bug Fixes

The Citrix ID is now pre-pended to the window title instead of appended.

Upgraded to gateway-client 1.3.14.

Upgraded to jetty 9.4.54.v20240208.

1.4.17
Release date: 07.02.2024
New Features

Added support for configuring the system buttons of io.Connect Windows.

Added support for dynamic Citrix Virtual Channels.

Improvements & Bug Fixes

Upgraded to gateway-client 1.3.13.

Upgraded to jetty 9.4.53.v20231009.

Upgraded to slf4j 2.0.12.

Upgraded to log4j 2.22.1.

Upgraded to config 1.4.3.

Upgraded to jna 5.14.0.

Upgraded to junit 5.10.2.

Upgraded to json-path 2.9.0.

Upgraded to asm 9.6.

Upgraded to assertj 3.25.3.

1.4.16
Release date: 27.07.2023
New Features

Added support for the onClosing() hook that can prevent closing of io.Connect Windows.

Improvements & Bug Fixes

Fixed various issues in the Java App Management API.

Fixed shutdown handlers not being invoked when an app is started as a standalone app.

Fixed title window registration option not being shown when a Java app is started as a standalone app.

1.4.15
Release date: 30.06.2023
New Features

Added support for the always on top window state.

Improvements & Bug Fixes

Added dependency management for jul-to-slf4j, currently set to 2.0.7.

Upgraded to slf4j 2.0.7.

Upgraded to gateway-client 1.3.12.

Upgraded to log4j 2.20.0.

Upgraded to json-path 2.8.0.

Upgraded to asm 9.5.

The Java demo apps now use log4j-slf4j2-impl.

How to...

Installation

Maven

Gradle

Referencing & Initialization

App Shutdown

App Definition

io.Connect Java Concepts

Changelog

1.7

1.7.5

1.7.4

1.7.3

1.7.2

1.7.1

1.7.0

1.6

1.6.0

1.5

1.5.4

1.5.3

1.5.2

1.5.1

1.5.0

1.4

1.4.18

1.4.17

1.4.16

1.4.15