回收站（Java）

KS3支持用户对存储空间配置回收站规则，规则配置成功后，存储空间内的文件被删除时会先进入回收站。用户可设置回收站内文件保留时长，到达指定时间后，KS3会自动彻底删除回收站内的文件。

注：有关回收站的详细介绍请参见文档：回收站。

启用/禁用回收站

以下代码用于启用/禁用回收站。

// 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
Ks3Client client = initClient();
// 初始化回收站规则
BucketRetentionConfiguration.Rule rule = new BucketRetentionConfiguration.Rule();
// 启用回收站
rule.setStatus(BucketRetentionConfiguration.Status.ENABLED);
// 禁用回收站
// rule.setStatus(BucketRetentionConfiguration.Status.DISABLED);
// 设置回收站内文件保留天数
rule.setDays(365);
PutBucketRetentionRequest request = new PutBucketRetentionRequest();
request.setBucketName("<your-bucket>");
request.setRetentionConfiguration(new BucketRetentionConfiguration(rule));
client.putBucketRetention(request);

获取回收站规则

以下代码用于获取回收站规则。

// 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
Ks3Client client = initClient();

// 获取回收站规则
BucketRetentionConfiguration bucketRetention = client.getBucketRetention(bucket);
BucketRetentionConfiguration.Rule rule = bucketRetention.getRule();

列举回收站中的文件

以下代码用于列举回收站中的文件。

/**
 *  列出一个桶的回收站下的文件，最多返回1000条
 */
public RetentionObjectListing listRetentionObjectsSimple() {
    // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
    Ks3Client client = initClient();       
    // 获取桶回收站的文件列表，最多返回1000条
    RetentionObjectListing list = client.listRetentionObjects("<您的bucket名称>");
    // 遍历文件列表
    for (RetentionObject retentionObject : list.getRetentionObjects()) {
        // 获取文件的名字
        retentionObject.getKey();
        // 获取文件的删除 ID
        getRetentionId.getRetentionId();
        // 获取文件的存储类型
        retentionObject.getStorageClass();
        // 获取文件的其他信息
        // retentionObject.
    }
    // 返回文件列表
    return list;
} 


/**
 * 将列出桶的回收站下满足Object Key前缀为指定字符串的文件，最多返回1000条
 */
public RetentionObjectListing listRetentionObjectsWithPrefix(){
    // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
    Ks3Client client = initClient();       
    // 根据前缀去获取桶回收站的文件列表
    RetentionObjectListing list = client.listRetentionObjects("<您的bucket名称>","<object key前缀>");
    // 遍历文件列表
    for (RetentionObject retentionObject : list.getRetentionObjects()) {
        // 获取文件的名字
        retentionObject.getKey();
        // 获取文件的删除 ID
        getRetentionId.getRetentionId();
        // 获取文件的存储类型
        retentionObject.getStorageClass();
        // 获取文件的其他信息
        // retentionObject.
    }
    // 返回文件列表
    return list;
}


/**
 * 手动调节列出桶回收站文件的参数
 */
public RetentionObjectListing listRetentionObjectsUseRequest(){
    // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
    Ks3Client client = initClient();       
    // 新建一个ListObjectsRequest
    ListRetentionObjectsRequest request = new ListRetentionObjectsRequest("<您的bucket名称>");
    // 设置参数
    request.setMaxKeys("<max keys>"); // 指定最多返回条数
    request.setPrefix("<object key前缀>"); // 返回以指定前缀开头的Object
    request.setDelimiter("<delimiter>"); // 设置文件分隔符，系统将根据该分隔符组织文件夹结构，一般是"/"
    // 执行操作
    RetentionObjectListing list = client.listRetentionObjects(request);
    for (RetentionObject retentionObject : list.getRetentionObjects()) {
        // 获取文件的名字
        retentionObject.getKey();
        // 获取文件的删除 ID
        getRetentionId.getRetentionId();
        // 获取文件的存储类型
        retentionObject.getStorageClass();
        // 获取文件的其他信息
        // retentionObject.
    }
    // 返回文件列表
    return list;
}


/**
 * 使用循环列出桶回收站中所有Object
 */
public void listAllRetentionObjects(){
    // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
    Ks3Client client = initClient();              
    RetentionObjectListing list = null;
    //初始化一个请求
    ListRetentionObjectsRequest request = new ListRetentionObjectsRequest("<您的bucket名称>");
    do {
        // isTruncated 为 true 时表示之后还有Object，所以应该继续循环
        if (list != null && list.isTruncated()) {
            // 在 RetentionObjectListing 中将返回下次请求的 marker
            // 如果请求时设置了 delimiter，则会返回 nextMarker
            // request.setMarker(list.getNextMarker());
            // 如果请求时没有设置 delimiter，则不会返回 nextMarker，需要使用上一次 List 的最后一个 Key 做为 nextMarker
            int size = list.getRetentionObjects().size();
            request.setMarker(list.getRetentionObjects().get(size - 1).getKey());
        }
        list = client.listRetentionObjects(request);
        for (RetentionObject retentionObject : list.getRetentionObjects()) {
            // 获取文件的名字
            retentionObject.getKey();
            // 获取文件的删除 ID
            getRetentionId.getRetentionId();
            // 获取文件的存储类型
            retentionObject.getStorageClass();
            // 获取文件的其他信息
            // retentionObject.
        }
    } while (list.isTruncated());
}

恢复回收站中的文件

以下代码用于恢复回收站中的文件。

 // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
Ks3Client client = initClient();

// 恢复指定 Object Key 的最新版本的文件
client.recoverObject("<您的 bucket 名称>", "<object key>");

// 恢复指定 Object Key 指定删除 ID 的文件
client.recoverObject("<您的 bucket 名称>", "<object key>", "<retention id>");

// 恢复指定 Object Key 的文件
RecoverObjectRequest request = new RecoverObjectRequest("<您的 bucket 名称>", "<object key>", "<retention id>");
// 桶中存在同名文件时的覆盖策略，true：直接覆盖，恢复成功；false：进行冲突报错，恢复失败
request.setOverwrite(true);
client.recoverObject(request);

删除回收站中的文件

以下代码用于彻底删除回收站中的文件。

 // 初始化 KS3Client，详情请参见文档：https://docs.ksyun.com/documents/40559
Ks3Client client = initClient();

// 清除指定 Object Key 指定删除 ID 的文件
client.clearObject("<您的 bucket 名称>", "<object key>", "<retention id>");