Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/solidfire/solidfire-sdk-java

netapp-public
Last synced: about 1 month ago
JSON representation
Host: GitHub
URL: https://github.com/solidfire/solidfire-sdk-java
Owner: solidfire
License: apache-2.0
Created: 2015-11-09T19:53:19.000Z (about 9 years ago)
Default Branch: master
Last Pushed: 2021-05-10T13:56:12.000Z (over 3 years ago)
Last Synced: 2024-08-02T21:38:34.746Z (4 months ago)
Topics: netapp-public
Language: Java
Homepage: https://solidfire.github.io/solidfire-sdk-java/
Size: 21.6 MB
Stars: 3
Watchers: 12
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project

awesome-solidfire - SolidFire Java SDK
README

        #  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 11.0 - 12.3 |

## 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](http://netapp.io). Your feedback helps us focus our efforts on new features and capabilities.

## Download

[Download](jar/solidfire-sdk-java-12.3.0.196.jar) the latest jar:

~~~ xml

  com.solidfire

  solidfire-sdk-java

  12.3.0.196

~~~

or SBT:

~~~ scala

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

~~~

or Gradle:

~~~ groovy

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

~~~

##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.  

## Documentation

[Latest JavaDoc](https://solidfire.github.io/solidfire-sdk-java/docs/index.html)

[Release Notes](NetApp_Element_Java_SDK_Release_Notes_12.3.pdf)

## Examples

Step 1 - Build a [SolidFireElement](https://solidfire.github.io/solidfire-sdk-java/docs/com/solidfire/element/api/SolidFireElement.html) object using the factory

---

This is the preferred way to construct the [SolidFireElement](https://solidfire.github.io/solidfire-sdk-java/docs/com/solidfire/element/api/SolidFireElement.html) 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](https://solidfire.github.io/solidfire-sdk-java/docs/com/solidfire/client/ElementFactory.html) documentation.

#### Java:

~~~ 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:

~~~ 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:

~~~ 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:

~~~ 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)

~~~ 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.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)

~~~ 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:

~~~ 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:

~~~ 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](examples) 

For more examples check out the tutorials in the [examples folder](examples) of this repo.

## Logging and Logback

The SDK and the Assembly leverage the [SLF4J API](http://www.slf4j.org/) for logging with the assembly also including  [logback-classic](http://logback.qos.ch/reasonsToSwitch.html) implementation.  An advantage to using the SLF4J interface is the availability of legacy logging framework [bridges](http://www.slf4j.org/legacy.html), 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: 

~~~ xml

    

        

        

            %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n

        

    

    

    

        

    

~~~

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

~~~

    ch.qos.logback

    logback-classic

    1.1.3

~~~

        

## License

Copyright © 2021 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

   

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.