Fusion Java SDK

A Java SDK for the Fusion platform API

Fusion by J.P. Morgan is a cloud-native data platform for institutional investors, providing end-to-end data management, analytics, and reporting solutions across the investment lifecycle. The platform allows clients to seamlessly integrate and combine data from multiple sources into a single data model that delivers the benefits and scale and reduces costs, along with the ability to more easily unlock timely analysis and insights. Fusion's open data architecture supports flexible distribution, including partnerships with cloud and data providers, all managed by J.P. Morgan data experts.

For more information, please visit fusion.jpmorgan.com

Usage

⚠️ This SDK is undergoing active development towards a stable release. While the version remains < 1.0.0 there may be some changes to the public API. We will endeavour to avoid that or keep to a minimum where possible

Acquiring

The Fusion SDK is published to Maven Central and can be retrieved from there using standard dependency resolution tools. For example, with Maven, add this to the dependencies in your POM:

  <dependency>
    <groupId>io.github.jpmorganchase.fusion</groupId>
    <artifactId>fusion-sdk</artifactId>
    <version>0.0.11</version>
  </dependency>

Getting started

Imports

import io.github.jpmorganchase.fusion.Fusion;

Creating the Fusion object

Once you have the dependency added to your project and imports configured, you will need an instance of the Fusion class to interact with the API. This will be the primary way to use Fusion from your own code. To create an instance, use the builder from the class. Examples below show different ways to intialise the Fusion object depending on your authentication mechanism.

With an OAUth client ID and secret

Fusion fusion = Fusion.builder()
                        .secretBasedCredentials(CLIENT_ID, CLIENT_SECRET, RESOURCE, AUTH_SERVER_URL)
                        .build();

This will configure the SDK to retrieve a bearer token from an OAuth server using the supplied parameters:

CLIENT_ID - A valid OAuth client identifier
CLIENT_SECRET - A valid OAuth client secret
RESOURCE - The OAUth audience
AUTH_SERVER_URL - URL for the OAuth authentication server

When configured in this way, the SDK will retrieve the token from the OAuth server prior to the first call you make to Fusion. On each subsequent call the same token will be re-used until it is close to expiry, at which point the SDK will retrieve a new token. Use this option if you want the SDK to manage the tokens on your behalf.

Loading the OAuth configuration from a file

Fusion fusion = Fusion.builder().configuration(FusionConfiguration.builder()
            .credentialsPath(CREDENTIALS_FILE_PATH)
            .build())
        .build();

This will configure the SDK to retrieve a bearer token from an OAuth server using configuration details stored in a file at the supplied path CREDENTIAL_FILE_PATH

Configuration files are JSON in the following format:

{
  "resource": "JPMC:URI:RS-12345-App-ENV",
  "client_secret": "aClientSecret",
  "auth_url": "https://authserver.domain.com/as/token.oauth2",
  "client_id": "aClientId"
}

Where:

resource - The OAUth audience
client_secret - A valid OAuth client secret
auth_url - URL for the OAuth authentication server
client_id - A valid OAuth client identifier

Similar to the above option, this will configure the SDK to manage the tokens on your behalf. Use this option if you want the OAuth configuration to be stored on the local filesystem.

With a pre-existing bearer token

Fusion fusion = Fusion.builder().bearerToken(BEARER_TOKEN).build();

Here BEARER_TOKEN is the String value of a bearer token you have retrieved which provides access to the Fusion API. You can use this mechanism in cases where you already have a means to retrieve the token and would prefer to manage that within your application than having the SDK manage that on your behalf.

Note than when your token has expired, you will need to pass a new token to the Fusion object by calling updateBearerToken, passing the new value.

Overriding attributes using FusionConfiguration

Fusion fusion = Fusion.builder().configuration(FusionConfiguration.builder()
         .build())
        .build();

rootURL - Defines the fusion root url to be used with api interactions. Defaults to "https://fusion-api.jpmorgan.com/fusion/v1/".
credentialsPath - Defines the path to the credentials file for auth/authz. Defaults to "config/client_credentials.json".
defaultCatalog - Set the default catalog to be used with simplified API calls. Defaults to "common"
downloadPath - Configures the path where distributions should be downloaded to. Defaults to "downloads"
singlePartUploadSizeLimit - Max size in MB of data allowed for a single part upload. if 32MB was the max size then 32 would be provided. Defaults to 50.
uploadPartSize - Upload part chunk size. If a value such as 8MB is required, then client would set this value to 8. Defaults to 16MB.
maxInFluxDataSize - Max in flux data to be read at a given time. Use this to protect data read to heap during upload. If a value such as 100MB is required, set to 100. Defaults to 500MB.
uploadThreadPoolSize - Size of Thread-Pool to be used for uploading chunks of a multipart file. Defaults to number of available processors.
downloadThreadPoolSize - Size of Thread-Pool to be used for uploading chunks of a multipart file. Defaults to number of available processors.
digestAlgorithm - Digest algorithm used by fusion to verify the integrity of upload/downloads. Defaults to SHA-256.

Using the SDK

Once you have initialised the Fusion object, you can interact with it to retrieve metadata or download distribution files for any datasets that you need.

Examples:

List catalogs

Map<String, Catalog> catalogs = fusion.listCatalogs();

List datasets

Map<String, Dataset> datasets = fusion.listDatasets("my-catalog");

Download some dataset metadata

Map<String, Attribute> attributes = fusion.listAttributes("my-catalog", "my-dataset");

List the series members available in the dataset

Map<String, DatasetSeries> members = fusion.listDatasetMembers("my-catalog", "my-dataset");

List the distributions available in the dataset member

Map<String, Distribution> distributions = fusion.listDistributions("my-catalog", "my-dataset", "my-series-member");

Download as a file

fusion.download("my-catalog", "my-dataset", "my-series-member", "csv", "/downloads/distributions");

Download as a stream

InputStream is = fusion.downloadStream("my-catalog", "my-dataset", "my-series-member", "csv");

Logging

The Fusion SDK makes log calls to the SLF4J API. If you wish to see the logging you must configure an SLF4J implementation for your application. See the SLF4J manual for details.

Exception Handling

All exceptions thrown from calls to the Fusion object are runtime exceptions. These are documented in the Javadoc for the class itself. Runtime exceptions are used in place of checked exception in order to provide flexibility to users to handle exceptions within the most appropriate layer of your application, without requiring catching, wrapping and rethrowing.