快速入门

本文档详细讲解了​​对象存储服务的Java SDK v2版本完整使用准备工作和常用功能。

准备工作

请提前安装Java，建议使用 Java 1.7 及以上版本。你可以通过java-version查看你的Java版本。

示例代码

Java SDK Rest v2 为你提供了多种示例，具体如下：

示例文件	描述
DownloadSample	普通下载
SimpleMultipartUploadSample	分片上传
ListObjectsSample	列举文件
ObjectOperationsSample	对象管理
DeleteObjectsSample	批量删除对象
BucketLifecycleSample	存储空间生命周期管理
ConcurrentCopyPartSample	多线程分片拷贝大对象
ConcurrentDownloadObjectSample	多线程分片下载大对象
ConcurrentUploadPartSample	多线程分片上传大对象
CreateFolderSample	创建“文件夹”
DeleteObjectsSample	批量删除对象
ListBucketsSample	列举空间
ListObjectsV2Sample	列举文件
ObjectMetaSample	设置文件元信息
PostObjectSample	表单上传
RestoreObjectSample	文件解冻

SDK安装

进行各类操作前需要先安装Java SDK，您可通过此地址下载SDK： GitHub 。

添加依赖到Maven项目

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

Intellij IDEA中导入JAR包

以1.0.0版本为例，步骤如下：

1. 下载Java SDK开发包
2. 解压该开发包。
3. 将解压后文件夹中的文件wcs-java-sdk-rest-v2-1.0.0.jar以及lib文件夹下的所有JAR文件拷贝到您的项目中。
4. 在Intellij IDEA中选择您的工程，右键选择File->Project Structure->Modules->Dependencies->±>JARs or directories 。
5. 选中拷贝的所有JAR文件，导入到External Libraries中。

初始化

WosClient 是Java客户端，用于管理存储空间与对象。使用Java SDK时需优先初始化WosConfiguration并调整默认配置。

// 请从网宿控制台-用户中心-用户信息管理-AccessKey管理处获取aksk
// 请从网宿控制台-对象存储-空间概览处获取endpoint和regionName
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);


//创建WosClient实例
WosClient wosClient = new WosClient(ak, sk, config);
        
// 关闭wosClient
wosClient.close();

创建WosClient

//创建WosClient实例
WosClient wosClient = new WosClient(ak, sk, config, regionName);

//关闭wosClient
wosClient.close();

注意：新建WosClient时，需要指定Endpoint。您的工程中可以有一个或多个WosClient。WosClient可以并发使用。

配置WosClient

可通过WosConfiguration配置WosClient，包括超时时间、最大连接数等参数。详情如下表：

配置项	描述	方法
connectionTimeout	设置HTTP/HTTPS连接超时时间（单位：毫秒），默认为60000。	WosConfiguration.setConnectionTimeout
socketTimeout	设置Socket超时时间（单位：毫秒），默认为60000。	WosConfiguration.setSocketTimeout
idleConnectionTime	空闲连接的关闭时间，如果空闲时间超过此参数的设定值，则关闭连接（单位：毫秒），默认30000。	WosConfiguration.setIdleConnectionTime
maxIdleConnections	连接池中最大空闲连接数，默认1000。	WosConfiguration.setMaxIdleConnections
maxConnections	最大HTTP请求并发数，默认1000。	WosConfiguration.setMaxConnections
maxErrorRetry	失败重试次数，默认3次。	WosConfiguration.setMaxErrorRetry
endPoint	对象存储的服务地址，包括协议、域名、端口。例如：“https://your-endpoint:443”	WosConfiguration.setEndPoint
readBufferSize	Socket流读取缓存大小（单位：字节），默认-1表示不启用缓存。	WosConfiguration.setReadBufferSize
writeBufferSize	Socket流写入缓存大小（单位：字节），默认-1表示不启用缓存。	WosConfiguration.setWriteBufferSize
pathStyle	pathStyle为false时采用bucketName.endpoint域名格式，否则使用’endpoint/bucketName’格式。	WosConfiguration.setPathStyle

快速开始

Java SDK完成常见操作有：

1. 上传对象

以下代码展示如何上传对象：

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

2. 获取对象

以下代码展示如何获取对象的内容：

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();
}

说明：

• 调用wosObject.getObject返回一个WosObject实例，该实例包含对象内容及其属性。
• 调用wosObject.getObjectContent获取对象输入流，可读取此输入流获取其内容，用完之后请关闭这个流。

3. 列举存储空间内的对象

当完成一系列上传对象操作后，可能需要查看空间中包含哪些对象。以下代码展示如何列举指定空间的对象：

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

说明：

• 调用wosClient.listObjects返回ObjectListing实例，可通过ObjetListing.getObjects获取对象信息。
• 默认最多返回1000条。

4. 删除对象

以下代码展示如何删除指定的对象：

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

5. 带签名URL获取对象

以下代码展示如何生成一个带签名的URL访问空间中的某个对象：

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. WOS客户端通用示例

使用WOS客户端进行接口调用操作完成后，没有异常抛出，则表明返回值有效，返回SDK公共响应头实例或其子类实例；若抛出异常，则说明操作失败，此时应从SDK自定义异常实例中获取错误信息。

以下代码展示了使用WOS客户端的通用方式：

// 您的工程中可以只保留一个全局的WosClient实例
// WosClient是线程安全的，可在并发场景下使用
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 ***";

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

    // 创建WosClient实例
    wosClient = new WosClient(ak, sk, config);
    // 调用接口进行操作，例如上传对象
    HeaderResponse response = wosClient.putObject("bucketname", "objectname", new File("localfile"));  // localfile为待上传的本地文件路径，需要指定到具体的文件名
    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{
    // 关闭WosClient实例，如果是全局WosClient实例，可以不在每个方法调用完成后关闭
    // WosClient在调用WosClient.close方法关闭后不能再次使用
    if(wosClient != null){
        try
        {
            // wosClient.close();
        }
        catch (IOException e)
        {
        }
    }
}