ds3_java_sdk

Contact Us

Join us at our Google Groups forum to ask questions, or see frequently asked questions.

Setup

See our Setup Guide which explains how to setup Eclipse with all the dependencies that you will need to build the sdk from source.

If using Intellij, simply import the project as a Gradle project.

Install

To install the latest ds3_java_sdk either download the latest release jar file from the Releases page or clone the repository with git clone https://github.com/SpectraLogic/ds3_java_sdk.git, cd to ds3_java_sdk and run ./gradlew clean ds3-sdk:install to install the sdk into your local maven repository. It is compatible with Java 8 and is additionally tested against Java 11 and 17.

Starting with the 5.6.0 release, the SDK is available on Maven Central and can be included directly into a Maven or Gradle build. There is also a fatjar version that you can optionally use with the all classifier, take a look at the commented out code in the examples below. To include the SDK into maven add the following to the pom.xml file:

<project>
  ...
    <dependencies>
      ...
      <dependency>
	      <groupId>com.spectralogic.ds3</groupId>
	      <artifactId>ds3-sdk</artifactId>
	      <version>Tag</version>
        <!-- <classifier>all</classifier> -->
	</dependency>
    ...
    </dependencies>
</project>

To include the sdk into Gradle include the following in the build.gradle.kts file:

dependencies {
    implementation(platform("com.spectralogic.ds3:ds3-bom:Tag"))
    implementation("com.spectralogic.ds3:ds3-sdk")
    //implementation("com.spectralogic.ds3:ds3-sdk::all")
}

or in the build.gradle file:

dependencies {
    implementation platform('com.spectralogic.ds3:ds3-bom:Tag')
    implementation 'com.spectralogic.ds3:ds3-sdk'
    //implementation 'com.spectralogic.ds3:ds3-sdk::all'
}

Previous versions

Versions prior to 5.6.0 are available on jitpack.io under different maven coordinates. Unfortunately, the 5.6.0 version on jitpack.io is a pre-release version and is missing important fixes, and it is recommended that the artifacts on Maven Central are used going forward. To access versions earlier than 5.6.0, please see the instructions at https://jitpack.io/#SpectraLogic/ds3_java_sdk.

Contributing

If you would like to contribute to the source code, sign the Contributors Agreement and make sure that your source conforms to our Java Style Guide. For an overview of how we use Github, please review our Github Workflow.

Examples

All the examples are listed in the ds3-sdk-samples module.

Logging

The ds3_java_sdk uses SLF4J for logging. Because of this, a consumer of the sdk can use many different logging implementations and so long as the correct SLF4J bridge is installed, have the sdk logs appear. For more information on SLF4J and how to add different logging bridges, please see SLF4j.org.

Tests

In addition to unit tests in the main ds3-sdk module, there are additional integration tests in the ds3-integration module. Please see the integration README for details on running the tests. To just run the SDK's unit tests use:

./gradlew clean ds3-sdk:test

Creating a New Release

Update the version of the SDK before creating a new release. The format is <major>.<minor>.<patch>, where the <major>.<minor> numbers must match the version of BP. The <patch> is an incrementing number that increments with each SDK release for a given major/minor release.

The version is specified in libs.versions.toml:

[versions]
#
# project version
#
ds3SdkVersion = "5.6.1"

Once released, increment the minor version and add the suffix "-SNAPSHOT" to prepare for the next development cycle.