Installing or upgrading the LUSID Java SDK

The LUSID Java SDK provides convenient access to the LUSID REST API in Java environments.

Note: Supporting applications in the FINBOURNE platform (such as Drive, Scheduler and Luminesce) have their own Java SDKs.

Note the following:

We strongly recommend pinning a SDK to an exact version to control when you take updates and make your builds repeatable.
The master/main branch of a 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

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>

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>

To authenticate for the first time, you must generate a client ID and secret and store them with the credentials of a valid LUSID user as either environment variables or in a secrets file. The LUSID Java SDK uses these credentials to obtain a short-lived API access token from FINBOURNE's identity provider (Okta) on demand. More information.

Upgrading to v2 from an earlier version

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.

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.

Installing v1 of the LUSID Java SDK

Please note v1 of the LUSID Java SDK is now discontinued, but if you do need to install it for any reason, 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 it 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 it 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>
```