Installing and upgrading the Java SDK

Views:

SDKs > Java

This article explains how to install FINBOURNE Java SDKs, how to upgrade Java SDKs, what's included in the upgrade, and any other action you may be required to take.

Installing the latest LUSID Java SDK (Sep. 2023)
Installing v1 of the LUSID Java SDK
Upgrading to v2
Other Java SDKs in the FINBOURNE platform are also available now.

Note the following:

We strongly recommend pinning SDKs to an exact version to control when you take updates and make your builds repeatable.
The master/main branch of an SDK may not always have the latest API version; there may, for example, also be v2 or v3 branches. We aim to keep master/main updated with the latest API version, but there may be some lead time while we deprecate older endpoints. Once we deprecate older API versions, the latest API version is moved to the master/main branch.

Installing the latest LUSID Java SDK (Sep. 2023)

To install our Java packages, you must first configure your project's pom.xml file to use sonatype as a source for Java packages:

<repositories>
  <repository>
    <id>ossrh-SNAPSHOT</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>

As of September 2023, v2 is the latest major version of the LUSID Java SDK. You can install v2 of the LUSID Java SDK from GitHub, or by adding the following to the dependencies section of your project's pom.xml file:

<dependency>
    <groupId>com.finbourne</groupId>
    <artifactId>lusid-sdk-preview</artifactId>
    <version>[2.0,3.0)</version>
</dependency>

Click here if you are upgrading to v2 from an existing installation.

Installing v1 of the LUSID Java SDK

To install our Java packages, you must first configure your project's pom.xml file to use sonatype as a source for Java packages:

<repositories>
  <repository>
    <id>ossrh-SNAPSHOT</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>

For v1 of the LUSID Java SDK, two packages are published:

lusid-sdk contains only APIs with a lifecycle status of Production or Early Access. You can install the LUSID Java SDK from GitHub, or by adding the following to the dependencies section of your project's pom.xml file:
```
<dependency>
  <groupId>com.finbourne</groupId>
  <artifactId>lusid-sdk</artifactId>
  <version>[1.0,2.0)</version>
</dependency>
```
lusid-sdk-preview contains additional APIs with a lifecycle status of Experimental or Beta. You can install the LUSID Java Preview SDK from GitHub, or by adding the following to the dependencies section of your project's pom.xml file:
```
<dependency>
  <groupId>com.finbourne</groupId>
  <artifactId>lusid-sdk-preview</artifactId>
  <version>[1.0,2.0)</version>
</dependency>
```

Please note v1 of lusid-sdk and lusid-sdk-preview will be discontinued from April 2024.

Upgrading to v2

You can upgrade from v1 to v2 of the LUSID Java SDK by adding the following to the dependencies section of your project's pom.xml file:

<dependency>
    <groupId>com.finbourne</groupId>
    <artifactId>lusid-sdk-preview</artifactId>
    <version>[2.0,3.0)</version>
</dependency>

We recommend upgrading to v2 as soon as possible to ensure you have access to the latest features. Support for the previous SDK version (1.x.x) will be maintained until the end of March 2023.

Note that you must upgrade all SDKs used in a particular process to v2 at the same time. A process that uses both the Scheduler and Drive SDKs, for example, must either use v1 of both SDKs or v2 of both SDKs; mixing major versions will lead to dependency conflicts.

Users need to update their code to reflect the following v2 changes:

Prerequisites for v2

Built for the Jakarta EE platform.

Removal of snapshot repository source

We no longer publish snapshot versions of the LUSID Java SDK, so the snapshot repository source can be removed from the repositories section of your project's pom.xml file:

<repositories>
  <repository>
    <id>ossrh-release</id>
    <name>OSSRH</name>
    <url>https://oss.sonatype.org/content/repositories/releases/</url>
  </repository>
</repositories>

Preview SDKs

This release discontinues publishing the LUSID Java Preview SDK, instead adding the Experimental and Beta lifecycle APIs to a single SDK. Note that making requests to Experimental and Beta APIs requires additional licences; for more details please contact support.

Changes to executing API calls and optional parameters

In v1 of the Java SDK, API methods contained every parameter, so adding optional parameters to endpoints introduced breaking changes to the SDK. In v2, getters and setters are provided for optional parameters to eliminate occurrences of these breaking changes going forward:

Users need to modify all API calls to provide only required parameters in function calls, setting optional parameters using the provided getters and setters.
API calls must now be executed using the execute or executeAsync methods.

For example, the getPortfolio endpoint has two required parameters (scope and code) and four optional parameters (effectiveAt, asAt, propertyKeys and relationshipDefinitionIds). A v1 call that might look like this...

String scope = "your-portfolio-scope";
String code = "your-portfolio-code";
OffsetDateTime effectiveAt = OffsetDateTime.now();
OffsetDateTime asAt = OffsetDateTime.now();
List<String> propertyKeys = Arrays.asList();
List<String> relationshipDefinitionIds = null;
Portfolio result = apiInstance.getPortfolio(scope, code, effectiveAt, asAt, propertyKeys, relationshipDefinitionIds)

...must be updated to look as follows in v2:

String scope = "your-portfolio-scope";
String code = "your-portfolio-code";
OffsetDateTime effectiveAt = OffsetDateTime.now();
OffsetDateTime asAt = OffsetDateTime.now();
List<String> propertyKeys = Arrays.asList();
Portfolio result = apiInstance.getPortfolio(scope, code)
                                                .effectiveAt(effectiveAt)
                                                .asAt(asAt) 
                                                .propertyKeys(propertyKeys)
                                                .execute();

Notice we can omit optional parameters we don't wish to provide a value for in v2 , such as relationshipDefinitionIds.

`ApiClientBuilder` functionality changes to replace `HttpClientFactory`

The HttpClientFactory class is removed. This was previously used to provide an OkHttpClient to the ApiClientBuilder, configuring proxy settings and timeouts. The ApiClientBuilder class now provides this functionality.
The ApiClientBuilder no longer accepts arguments for setting default timeouts. Instead, it accepts an OkHttpClient.Builder which an ApiClient can be built from. Timeouts and many other settings can be configured on the OkHttpClient.Builder:
```
OkHttpClient.Builder clientBuilder = new OkHttpClient.Builder();
clientBuilder.readTimeout(20, TimeUnit.SECONDS);
ApiClient client = apiClientBuilder.build(apiConfiguration, clientBuilder);
```

`ApiConfiguration` requires PAT argument

The ApiConfiguration now additionally requires personalAccessToken as an argument. If you do not wish to use a personal access token, you can pass in null.

Namespaces and classes renamed

The following namespaces and classes have been renamed:

import com.finbourne.lusid.utilities becomes import com.finbourne.lusid.extensions.
Lusid. class prefix in the extensions module becomes Finbourne.

Keywords: Java, SDK