1. Introduction
This tutorial describes how to create a Java client that can log in to the yuuvis® Momentum API with username and password.
We will create a Maven project as basis for further interaction with the yuuvis® Momentum system.
2. Requirements
You need the knowledge and setup from the tutorial Installing a Minimal System.
To work through this tutorial, the following is required:
-
Simple Maven project
-
Java (we tested with Java 21)
3. Maven Configuration
In the tutorial, the OkHttpClient by Square, Inc. is used. Therefore, the first two dependencies in the following block must be added to the Maven dependencies in the pom.xml of the project. The third and forth dependencies are required for the handling of JSON request and response bodies that are expected/provided by the API.
<dependencies>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
<version>3.12.0</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp-urlconnection</artifactId>
<version>3.12.0</version>
</dependency>
<dependency>
<groupId>com.squareup.okio</groupId>
<artifactId>okio</artifactId>
<version>3.16.4</version>
</dependency>
<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20250517</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
</plugin>
</plugins>
</build>
We need to enable the usage of HTTP in our local Maven settings as only HTTPS is allowed in the Maven default configuration of version 3.8.1 and later. In our project, we create a .mvn directory with a local-setings.xml file.
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 http://maven.apache.org/xsd/settings-1.2.0.xsd">
<mirrors>
<mirror>
<id>release-http-unblocker</id>
<mirrorOf>central</mirrorOf>
<name></name>
<url>http://my-url/libs-release</url>
</mirror>
<mirror>
<id>snapshot-http-unblocker</id>
<mirrorOf>snapshots</mirrorOf>
<name></name>
<url>http://my-url/libs-snapshot</url>
</mirror>
</mirrors>
</settings>
4. Java Library Imports
We import the following Java libraries to use them in our application.
import okhttp3.*;
import java.net.CookieManager;
import java.net.CookiePolicy;
import java.util.Base64;
5. Login Data
To use our Java client, we need the login information. We store them in variables such that we can reuse the values later.
public static final String username = "root";
public static final String userpassword = "changeme";
public static final String auth = "Basic "+ Base64.getEncoder().encodeToString((username+":"+userpassword).getBytes());
public static final String tenant = "myfirsttenant";
public static final String baseUrl = "http://123.456.78.9:30080";
6. Session Management
The login is done using request headers, which are passed during the first call of an API function. The calling HTTP client must have a Cookie Manager to enrich further requests with the session cookie (GWSESSIONID). This prevents the user from logging on again for each request. To activate Cookie Management in the OkHttpClient, you can do the following:
try {
CookieJar cookieJar = new JavaNetCookieJar(new CookieManager(null, CookiePolicy.ACCEPT_ALL));
OkHttpClient client = new OkHttpClient.Builder().cookieJar(cookieJar).build();
} catch (Exception e) {
e.printStackTrace();
}
Please note that an IOException can be thrown by the OkHttpClient. That’s why we use it always wrapped with try and catch.
7. Testing
We can now easily test the login by calling a simple API endpoint. For example, we can retrieve the information on the currently running yuuvis® Momentum version.
Request getVersionRequest = new Request.Builder()
.header("Authorization", auth)
.header("X-ID-TENANT-NAME", tenant)
.url(baseUrl + "/api/dms/info")
.build();
Response getVersionResponse = client.newCall(getVersionRequest).execute();
System.out.println(getVersionResponse.body().string());
8. Summary
This tutorial explains how to authenticate an OkHttp3 Java client with cookie management using Basic authentication. We tested the login by calling an API endpoint.