Quick Start

This document provides a detailed guide on getting started with and using the main features of the Java SDK v2 for Object Storage Service.

Prerequisites

Ensure that Java is installed on your system. Java 1.7 or later is recommended. You can check your Java version by running java -version.

Sample Code

The Java SDK Rest v2 provides various sample programs, including the following:

SDK Installation

Before performing any operations, you must install the Java SDK. You can download the SDK from GitHub.

Add as a Dependency to a Maven Project

<dependency>
  <groupId>com.chinanetcenter.wcs.sdk</groupId>
  <artifactId>wcs-java-sdk-v2</artifactId>
  <version>1.0.3</version>
</dependency>

Importing JARs in IntelliJ IDEA

For version 1.0.0 as an example, follow these steps:

1. Download the Java SDK package.
2. Extract the package.
3. Copy the wcs-java-sdk-rest-v2-1.0.0.jar file and all JAR files from the lib directory into your project.
4. In IntelliJ IDEA, select your project and navigate to File -> Project Structure -> Modules -> Dependencies -> + -> JARs or directories.
5. Select all JAR files you copied and add them to External Libraries.

Initialization

WosClient is the Java client for managing buckets and objects. Before using the Java SDK, you must initialize WosConfiguration and adjust the default settings if necessary.

// Retrieve your Access Key (ak) and Secret Key (sk) from the Console: User Center > User Information > AccessKey Management
// Retrieve your endpoint and regionName from Console: Object Storage > Bucket Overview
String endPoint = "https://your-endpoint";
String regionName = "your regionName";
String ak = "*** Provide your Access Key ***";
String sk = "*** Provide your Secret Key ***";

WosConfiguration config = new WosConfiguration();
config.setSocketTimeout(30000);
config.setConnectionTimeout(10000);
config.setEndPoint(endPoint);
config.setRegionName(regionName);

// Create WosClient instance
WosClient wosClient = new WosClient(ak, sk, config);
        
// Close the wosClient
wosClient.close();

Creating a WosClient

// Create WosClient instance
WosClient wosClient = new WosClient(ak, sk, config, regionName);

// Close the wosClient
wosClient.close();

Note: When creating a new WosClient, you must specify the Endpoint. You can have one or more WosClient instances in your project. WosClient is thread-safe and supports concurrent usage.

Configuring WosClient

You can configure WosClient using WosConfiguration, which supports parameters such as timeouts, maximum connections, and more. Details are as follows:

Quick Start

The Java SDK supports common operations including:

1. Upload an Object

The code below demonstrates how to upload an object:

wosClient.putObject("bucketname", "objectname", new ByteArrayInputStream("Hello WOS".getBytes()));

2. Retrieve an Object

The following code shows how to retrieve the content of an object:

WosObject wosObject = wosClient.getObject("bucketname", "objectname");
InputStream content = wosObject.getObjectContent();
if (content != null) {
    BufferedReader reader = new BufferedReader(new InputStreamReader(content));
    while (true) {
        String line = reader.readLine();
        if (line == null)
            break;
        System.out.println("\n" + line);
    }
    reader.close();
}

Notes:

• Calling wosObject.getObject returns a WosObject instance containing both content and metadata.
• Use wosObject.getObjectContent to get an InputStream for reading the object; please close the stream when finished.

3. List Objects in a Bucket

After a series of object uploads, you might need to list the contents of a bucket. Example:

ObjectListing objectListing = wosClient.listObjects("bucketname");
for (WosObject wosObject : objectListing.getObjects()) {
    System.out.println(" - " + wosObject.getObjectKey() + "  " +  "(size = " + wosObject.getMetadata().getContentLength() + ")");
}

Notes:

• Calling wosClient.listObjects returns an ObjectListing instance, through which you can access object details via ObjectListing.getObjects.
• By default, up to 1,000 results are returned.

4. Delete an Object

The following code shows how to delete a specific object:

wosClient.deleteObject("bucketname", "objectname");

5. Get Object with Signed URL

The following example demonstrates how to generate a signed URL for accessing an object:

TemporarySignatureRequest req = new TemporarySignatureRequest(HttpMethodEnum.GET, 300);
req.setBucketName(bucketName);
req.setObjectKey(objectKey);
TemporarySignatureResponse res = wosClient.createTemporarySignature(req);
System.out.println("Getting object using temporary signature URL:");
System.out.println("\t" + res.getSignedUrl());

6. General Usage Example for WOS Client

After calling an API via the WOS client, if no exception is thrown, the return value is valid—either a base SDK response class or a subclass instance. If an exception occurs, retrieve error information from the SDK’s custom exception object.

The following code demonstrates the general usage pattern with the WOS client:

// You may maintain a single global WosClient instance in your project.
// WosClient is thread-safe and supports concurrent use.
WosClient wosClient = null; 
try {
    String endPoint = "https://your-endpoint";
    String regionName = "your regionName";
    String ak = "*** Provide your Access Key ***";
    String sk = "*** Provide your Secret Key ***";

    // Create config
    WosConfiguration config = new WosConfiguration();
    config.setSocketTimeout(30000);
    config.setConnectionTimeout(10000);
    config.setEndPoint(endPoint);
    config.setRegionName(regionName);

    // Create WosClient instance
    wosClient = new WosClient(ak, sk, config);
    // Call API—for example, upload an object
    HeaderResponse response = wosClient.putObject("bucketname", "objectname", new File("localfile"));  // 'localfile' is the path to the file to be uploaded; provide the full filename
    System.out.println(response);
} catch (WosException e) {
    System.out.println("HTTP Code: " + e.getResponseCode());
    System.out.println("Error Code: " + e.getErrorCode());
    System.out.println("Error Message: " + e.getErrorMessage());
    System.out.println("Request ID: " + e.getErrorRequestId());
    System.out.println("Host ID: " + e.getErrorHostId());
} finally {
    // Close the WosClient instance; if you have a global WosClient, you do not need to close after every API call
    // Do not use the WosClient again after calling wosClient.close()
    if (wosClient != null) {
        try {
            // wosClient.close();
        } catch (IOException e) {
            // Handle exception if needed
        }
    }
}