Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
_layouts
docs
examples
latest/api
project
src
stylesheets
.gitignore
.travis.yml
Java-SDK-Icon-RGB-02.png
LICENSE
NetApp_SolidFire_Java_SDK_Release_Notes.pdf
README.md
_config.yml
build.sbt
favicon.ico
front.yml
index.md
params.json

README.md

SolidFire Java SDK

Java SDK library for interacting with SolidFire Element API

Description

The SolidFire Java SDK is a collection of software modules and libraries that facilitate integration and orchestration between proprietary systems and third-party applications. The Java SDK allows developers to deeply integrate SolidFire system API with the Java programming language. The SolidFire Java SDK reduces the amount of additional coding time required for integration.

Compatibility

Component Version
Java 7.0 & 8.0
SolidFire OS Element 7.0 - 10.0

Getting Help

Contacting SolidFire SDK Support If you have any questions or comments about this product, submit an issue on github or reach out to the developer community at ThePub. Your feedback helps us focus our efforts on new features and capabilities.

Download

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>com.solidfire</groupId>
  <artifactId>solidfire-sdk-java</artifactId>
  <version>1.5.0.89</version>
</dependency>

or SBT:

libraryDependencies += "com.solidfire" % "solidfire-sdk-java" % "1.5"

or Gradle:

compile 'com.solidfire:solidfire-sdk-java:1.5'

##Dependencies

Component Version
base64 2.3.9
solidfire.code.gson 2.6.2
joda-time 2.9.3
joda-convert 1.8.1
slf4j-api 1.7.25

Limitations with a Certificate Signed Assembly Jar

The SDK assembly is signed with a certificate controlled by SolidFire, Inc, assuring the archive is official and legitimate. One caveat to having a set of components also signed with SolidFire's certificate, is no other version of these components can exist on the classpath. This will cause a security exception in the JVM.

If using the SDK with a restricted version of the above listed components, e.g. logback, or in developing an enterprise solution that runs in a web application container, etc., use the publicly hosted versions of the SDK.

Documentation

Latest JavaDoc

Release Notes

Examples

Step 1 - Build a SolidFireElement object using the factory

This is the preferred way to construct the SolidFireElement object. The factory will make a call to the SolidFire cluster using the credentials supplied to test the connection. It will also set the version to communicate with based on the highest number supported by the SDK and Element OS. Optionally, you can choose to set the version manually and whether or not to verify SSL. Read more about it in the ElementFactory documentation.

Java:

import com.solidfire.client.ElementFactory;
import com.solidfire.element.api.*;
import com.solidfire.core.javautil.Optional;

// Import Optional common empty types (String, Long, & Map)
import static com.solidfire.core.javautil.Optional.*;

...
    // Use ElementFactory to get a SolidFireElement object.
    SolidFireElement sfe = ElementFactory.create("mvip", "username", "password");

Scala:

import com.solidfire.client.ElementFactory
import com.solidfire.element.api._
import com.solidfire.core.javautil.Optional.{empty, of}

...
  // Use ElementFactory to get a SolidFireElement object.
  val sf = ElementFactory.create( "mvip", "username", "password" )

Step 2 - Call the API method and retrieve the result

All service methods in SolidFireElement call API endpoints and they all return result objects. The naming convention is [methodName]Result. For example, listAccounts() returns a ListAccountsResult object which has a property called getAccounts() returns an array of Accounts that can be iterated.

This example sends a request to list accounts then pulls the first account from the AddAccountResult object.

Java:

    // Send the request and wait for the result then pull the Account
    ListAccountsResult listAccountsResult = sfe.listAccounts(ListAccountsRequest.builder().build());
    Account account = listAccountsResult.getAccounts()[0];

Scala:

    // Send the request and wait for the result then pull the first Account
    val listAccountsResult = sfe.listAccounts(ListAccountsRequest.builder.build)
    val account = listAccountsResult.getAccounts()(0)

Examples of using the API (Java)

import com.solidfire.client.ElementFactory;
import com.solidfire.element.api.*;
import com.solidfire.core.javautil.Optional;

// Import Optional common empty types (String, Long, & Map)
import static com.solidfire.core.javautil.Optional.*;
public class ReadmeJavaExample {
    public static void main(String[] args) {
        // Create Connection to SF Cluster
        SolidFireElement sf = ElementFactory.create("mvip", "username", "password", "8.0");

        //* --------- EXAMPLE 1 - CREATE AN ACCOUNT ----------- *//
        // Construct an "AddAccount" request with only required parameters using the builder
        AddAccountRequest addAccountRequest = AddAccountRequest.builder()
                                                               .username("username")
                                                               .build();
        // Send the request and pull the account ID from the result object
        Long accountId = sf.addAccount(addAccountRequest).getAccountID();

        //* --------- EXAMPLE 2 - CREATE A VOLUME ------------- *//
        // Construct a request with parameters using the constructor.
        CreateVolumeRequest createVolumeRequest = new CreateVolumeRequest("volumeName", accountId,
                                                                          1000000000l, false,
                                                                          Optional.<QoS>empty(),
                                                                          EMPTY_MAP);
                                                            
        // Send the "CreateVolume" request pull the VolumeID off the result object
        Long volumeId = sf.createVolume(createVolumeRequest).getVolumeID();

        //* --------- EXAMPLE 3 - LIST ONE VOLUME FOR AN ACCOUNT ------------- *//
        // Send the "ListVolume" request with desired parameters inline and pull the first volume in the result
        Volume volume = sf.listVolumesForAccount(accountId, of(volumeId), of(1l)).getVolumes()[0];
        // Pull the iqn from the volume
        String iqn = volume.getIqn();

        //* --------- EXAMPLE 3 - MODIFY A VOLUME ------------- *//
        // Change Min and Burst QoS while keeping Max and Burst Time the same
        QoS qos = new QoS(of(5000l), EMPTY_LONG, of(30000l), EMPTY_LONG);

        // Construct request to modify the volume size and QoS using the builder
        ModifyVolumeRequest modifyVolumeRequest = ModifyVolumeRequest.builder()
                                                                     .volumeID(volumeId)
                                                                     .optionalQos(qos)
                                                                     .optionalTotalSize(2000000000l)
                                                                     .build();

        // Send the modify volume request
        sf.modifyVolume(modifyVolumeRequest);
    }
}

Examples of using the API (Scala)

import com.solidfire.client.ElementFactory
import com.solidfire.element.api._
import com.solidfire.core.javautil.Optional.{empty, of}

class ReadmeScalaExample {

  // Create Connection to SF Cluster
  val sf = ElementFactory.create( "mvip", "username", "password", "8.0" )

  //* --------- EXAMPLE 1 - CREATE AN ACCOUNT ----------- *//
  // Construct an "AddAccount" request with only required parameters using the builder
  val addAccount = AddAccountRequest.builder.username( "username" ).build

  // Send the request and pull the account ID from the result object
  val accountId = sf.addAccount( addAccount ).getAccountID

  //* --------- EXAMPLE 2 - CREATE A VOLUME ------------- *//
  // Construct a "CreateVolume" request with parameters using the constructor.
  val createVolume = new CreateVolumeRequest( "volumeName", accountId, 
                                              1000000000L, false, empty[QoS], empty( ) )
  
  // Send the request pull the VolumeID off the result object
  val volumeId = sf.createVolume( createVolume ).getVolumeID

  //* --------- EXAMPLE 3 - LIST ONE VOLUME FOR AN ACCOUNT ------------- *//
  // Send the "ListVolume" request with desired parameters inline and pull the first volume in the result
  val iqn: Volume = sf.listVolumesForAccount( accountId, of( volumeId ), of( 1L ) ).getVolumes()(0)
  
  // pull the iqn from the volume
  val iqn: String = volume.getIqn

  //* --------- EXAMPLE 4 - MODIFY A VOLUME ------------- *//
  // Change Min and Burst QoS while keeping Max and Burst Time the same
  val qos: QoS = new QoS( of( 5000l ), empty(), of( 30000l ), empty() )

  // Construct request to modify the volume size and QoS using the builder.
  val modifyVolume = ModifyVolumeRequest.builder
                                        .volumeID( volumeId )
                                        .optionalQos( qos )
                                        .optionalTotalSize( 2000000000l )
                                        .build

  // Send the modify volume request
  sf.modifyVolume( modifyVolume )
}

Timeout

Connection timeout (useful for failing fast when a host becomes unreachable):

Java:

    import com.solidfire.client.ElementFactory;
    import com.solidfire.element.api.*;
    ...
    SolidFireElement sfe = ElementFactory.create("ip-address-of-cluster", "username", "password");
    sfe.getRequestDispatcher().setConnectionTimeout(600);

Read timeout (useful for extending time for a service call to return):

Java:

    import com.solidfire.client.ElementFactory;
    import com.solidfire.element.api.*;
    ...
    SolidFireElement sfe = ElementFactory.create("ip-address-of-cluster", "username", "password");
    sfe.getRequestDispatcher().setReadTimeout(600);

More Examples

<<<<<<< HEAD

For more examples check out the tutorials in the examples folder of this repo.^M

=======

For more examples check out the tutorials in the examples folder of this repo.

develop

Logging and Logback

The SDK and the Assembly leverage the SLF4J API for logging with the assembly also including logback-classic implementation. An advantage to using the SLF4J interface is the availability of legacy logging framework bridges, for intercepting and consolidating all logging calls into a single log.

Logback (Assembly Only) Tracing Request / Response calls in the log

An example logback.xml:

<configuration debug="true">

    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <!-- encoders are assigned the type
             ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <logger name="com.solidfire.core.client.ServiceBase" level="DEBUG" />

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

You also need to add the appropriate SLF4J dependency. Continuing with the logback example:

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.1.3</version>
</dependency>

License

Copyright © 2016, 2017 NetApp, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions andlimitations under the License.