IBM/ibm-cos-sdk-java

Name: ibm-cos-sdk-java

Owner: International Business Machines

Description: ibm-cos-sdk-java

Created: 2017-09-09 13:10:54.0

Updated: 2018-05-22 12:18:05.0

Pushed: 2018-04-20 14:48:13.0

Homepage: null

Size: 17968

Language: Java

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

IBM Cloud Object Storage - Java SDK

This package allows Java developers to write software that interacts with IBM Cloud Object Storage. It is a fork of the AWS SDK for Java library.

Documentation

• Core documentation for IBM COS
• Java API reference documentation
• REST API reference documentation

Changes to the SDK are tracked in the CHANGELOG.md file.

• Example code
• Building from source
• Getting help

Quick start

You'll need:

• An instance of COS.
• An API key from IBM Cloud Identity and Access Management with at least Writer permissions.
• The ID of the instance of COS that you are working with.
• Token acquisition endpoint
• Service endpoint
• Java 1.6+.

These values can be found in the Bluemix UI by generating a 'service credential'.

Getting the SDK

The recommended way to use the IBM COS SDK for Java in your project is to consume it from Maven. Import the ibm-cos-java-sdk and specify the SDK Maven modules that your project needs in the dependencies:

endencies>
ependency>
<groupId>com.ibm.cos</groupId>
<artifactId>ibm-cos-java-sdk</artifactId>
dependency>
pendencies>

SDK dependencies

The below is a list of dependencies & their versions used within the SDK. If a client project has a different version of any of these libraries within its classpath it may have an adverse effect at compilation or runtime.

• jackson - 2.6.6
• ehcache - 2.10.2
• slf4j - 1.7.7
• asynchttp - 4.1.3
• ion java- 1.0.2
• junit - 4.12
• easymock - 3.2
• commons logging - 1.1.3
• jodatime - 2.8.1
• wiremock - 1.55
• log4j - 1.2.17
• hamcrest - 1.3
• commons io - 2.4
• mockito - 1.10.19
• equalsverifier - 1.7.5
• httpcomponents httpclient - 4.5.2
• cucumber info cukes - 1.2.4
• cucumber guice - 4.0
• unitils - 3.3

Deprecation Notice

Deprecation Notice for IBM Cloud Object Storage Java and Python SDK Versions 1.x

As of March 31, 2018, IBM will no longer add new features to the IBM Cloud Object Storage Java SDK Versions 1.x and the IBM Cloud Object Storage Python SDK Versions 1.x. We will continue to provide critical bug fixes to the 1.x releases through May 31, 2018.

Versions 1.x for Java and Python SDK will no longer be supported after May 31, 2018.

If you are using the 1.x version of the Java or Python SDK, please upgrade to the latest IBM Cloud Object Storage SDK versions 2.x. Instructions on how to upgrade from SDK Java and Python 1.x can be found in the “Migrating from 1.x.x” section of corresponding Readme.

Note: The IBM Cloud Object Storage Node.js SDK is NOT affected by this change.

For questions, please open an issue:

Java

Python

Migrating from 1.x.x

The 2.0 release of the SDK introduces a namespacing change that allows an application to make use of the original AWS library to connect to AWS resources within the same application or environment. To migrate from 1.x to 2.0 some changes are necessary:

1. Update using Maven by changing all ibm-cos-java-sdk dependency version tags to 2.0.0 in the pom.xml. Verify that there are no SDK module dependencies in the pom.xml with a version earlier than 2.0.0.
2. Update any import declarations from amazonaws to ibm.cloud.objectstorage.

Example code (Version 2.x)

age com.cos;

rt java.sql.Timestamp;
rt java.util.List;


ersion 1.x of the library uses 'com.amazonaws' for namespacing

rt com.ibm.cloud.objectstorage.ClientConfiguration;
rt com.ibm.cloud.objectstorage.SDKGlobalConfiguration;
rt com.ibm.cloud.objectstorage.auth.AWSCredentials;
rt com.ibm.cloud.objectstorage.auth.AWSStaticCredentialsProvider;
rt com.ibm.cloud.objectstorage.auth.BasicAWSCredentials;
rt com.ibm.cloud.objectstorage.client.builder.AwsClientBuilder.EndpointConfiguration;
rt com.ibm.cloud.objectstorage.services.s3.AmazonS3;
rt com.ibm.cloud.objectstorage.services.s3.AmazonS3ClientBuilder;
rt com.ibm.cloud.objectstorage.services.s3.model.Bucket;
rt com.ibm.cloud.objectstorage.services.s3.model.ListObjectsRequest;
rt com.ibm.cloud.objectstorage.services.s3.model.ObjectListing;
rt com.ibm.cloud.objectstorage.services.s3.model.S3ObjectSummary;
rt com.ibm.cloud.objectstorage.oauth.BasicIBMOAuthCredentials;

ic class CosExample


private static AmazonS3 _cos;

/**
 * @param args
 */
public static void main(String[] args)
{

    SDKGlobalConfiguration.IAM_ENDPOINT = "https://iam.bluemix.net/oidc/token";

    String bucketName = "<bucketName>";
    String api_key = "<apiKey>";
    String service_instance_id = "<resourceInstanceId>";
    String endpoint_url = "https://s3-api.us-geo.objectstorage.softlayer.net";
    String location = "us";

    System.out.println("Current time: " + new Timestamp(System.currentTimeMillis()).toString());
    _cos = createClient(api_key, service_instance_id, endpoint_url, location);
    listObjects(bucketName, _cos);
    listBuckets(_cos);
}

/**
 * @param bucketName
 * @param clientNum
 * @param api_key
 *            (or access key)
 * @param service_instance_id
 *            (or secret key)
 * @param endpoint_url
 * @param location
 * @return AmazonS3
 */
public static AmazonS3 createClient(String api_key, String service_instance_id, String endpoint_url, String location)
{
    AWSCredentials credentials;
    if (endpoint_url.contains("objectstorage.softlayer.net")) {
        credentials = new BasicIBMOAuthCredentials(api_key, service_instance_id);
    } else {
        String access_key = api_key;
        String secret_key = service_instance_id;
        credentials = new BasicAWSCredentials(access_key, secret_key);
    }
    ClientConfiguration clientConfig = new ClientConfiguration().withRequestTimeout(5000);
    clientConfig.setUseTcpKeepAlive(true);

    AmazonS3 cos = AmazonS3ClientBuilder.standard().withCredentials(new AWSStaticCredentialsProvider(credentials))
            .withEndpointConfiguration(new EndpointConfiguration(endpoint_url, location)).withPathStyleAccessEnabled(true)
            .withClientConfiguration(clientConfig).build();
    return cos;
}

/**
 * @param bucketName
 * @param cos
 */
public static void listObjects(String bucketName, AmazonS3 cos)
{
    System.out.println("Listing objects in bucket " + bucketName);
    ObjectListing objectListing = cos.listObjects(new ListObjectsRequest().withBucketName(bucketName));
    for (S3ObjectSummary objectSummary : objectListing.getObjectSummaries()) {
        System.out.println(" - " + objectSummary.getKey() + "  " + "(size = " + objectSummary.getSize() + ")");
    }
    System.out.println();
}

/**
 * @param cos
 */
public static void listBuckets(AmazonS3 cos)
{
    System.out.println("Listing buckets");
    final List<Bucket> bucketList = cos.listBuckets();
    for (final Bucket bucket : bucketList) {
        System.out.println(bucket.getName());
    }
    System.out.println();
}

Building from source

Once you check out the code from GitHub, you can build it using Maven:

clean install

Using a Service Credential (New)

From Release 2.1.0 you can source credentials directly from a Service Credential JSON document generated in the IBM Cloud console saved to ~/.bluemix/cos_credentials. The SDK will automatically load these providing you have not explicitly set other credentials during client creation. If the Service Credential contain HMAC keys the client will use those and authenticate using a signature, otherwise the client will use the provided API key to authenticate using bearer tokens.

Getting help

Feel free to use GitHub issues for tracking bugs and feature requests, but for help please use one of the following resources:

• Read a quick start guide in Bluemix Docs
• Ask a question on StackOverflow and tag it with ibm and object-storage
• Open a support ticket with IBM Bluemix Support
• If it turns out that you may have found a bug, please open an issue

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE.txt and NOTICE.txt for more information.