如何配置ArchiveManager（一）

同步接口和异步接口


ArchiveManager中按交互模式，分成同步接口（阻塞式）和异步接口（非阻塞）两大类。同步接口会阻塞当前运行的程序，异步接口则反之。在使用过程中，建议使用异步接口，通过实现监听类来获取任务中间状态。 用户很容易通过方法的名称来区分这两类接口，比如：

1. [backcolor=transparent]upload(...) 即为同步式上传接口
2. [backcolor=transparent]uploadAsync(...) 即为异步式上传接口

下面的章节，将通过业务类型的划分，来分别介绍各种业务接口的具体定义。

上传Archive



普通上传


用户通过接口上传文件到指定名称的Vault，可选的 description参数是Archive的描述字段。使用普通上传接口时，用户无需关心是否开启Multipart，SDK会根据文件的大小选择适合用户的方式进行上传，两个普通上传接口定义如下： /**
* 上传文件到指定的vault中
* @param vaultName
*            目标vault的名称
* @param file
*            需要上传的文件对象
* @return 返回UploadResult对象
* @throws OASClientException
*             客户端异常
* @throws OASServerException
*             服务端异常
*/
public UploadResult upload(String vaultName, File file)
    throws OASClientException, OASServerException;

/**
* 上传文件到指定的vault中
* @param vaultName
*            目标vault的名称
* @param file
*            需要上传的文件对象
* @param description
*            上传archive的备注
* @return 返回UploadResult对象
* @throws OASClientException
*             客户端异常
* @throws OASServerException
*             服务端异常
*/
public UploadResult upload(String vaultName, File file, String description)
    throws OASClientException, OASServerException;

文件上传示例： File file = new File("[pathToYourFile]");
ServiceCredentials credentials = new ServiceCredentials(
    DemoConstants.ACCESS_ID,
    DemoConstants.ACCESS_KEY);

// 通过工厂类获得archiveManager接口
ArchiveManager archiveManager = OASFactory.archiveManagerFactory(credentials);

// java sdk 会帮助用户完成 vaultName 到 vaultId 的转换
// 由此避免了用户对一长串vaultId的记忆负担
UploadResult result = archiveManager
    .upload("[yourVaultName]", file, "[Description(not necessary)]");
String archiveId = result.getArchiveId();
System.out.println("Archive ID=" + archiveId);

注：上述的两个upload接口，已能满足用户的大部分需求

使用Multipart进行上传


用户可以指定使用Multipart模式进行上传，完成一个Multipart上传需要两步：

1. 初始化Multipart上传，获得UploadId
2. 根据获得的UploadId，上传数据

关于UploadId的定义和作用，请参考 《OAS API文档》-4.3.1章节初始化Multipart Upload任务 中的详细介绍。
涉及到的接口定义如下： /**
* 手工初始化Multipart上传任务
* @param vaultName 目标vault名称
* @param file 需要上传的文件
* @return 初始化成功的Multipart上传任务的UploadId字符串
* @throws OASClientException
* @throws OASServerException
*/
public String initiateMultipartUpload(String vaultName, File file)
    throws OASClientException, OASServerException;

/**
* 手工初始化Multipart上传任务
* @param vaultName 目标vault名称
* @param file 需要上传的文件
* @param description 文件描述
* @return 初始化成功的Multipart上传任务的UploadId字符串
* @throws OASClientException
* @throws OASServerException
*/
public String initiateMultipartUpload(String vaultName, File file, String description)
    throws OASClientException, OASServerException;

/**
* 根据具体的UploadId上传文件。
* 要配合 {@link initiateMultipartUpload} 使用
* @param vaultName 目标vault名称
* @param file 需要上传的文件
* @param uploadId 初始化完成的Multipart的UploadId
* @return 上传结果对象
* @throws OASClientException
* @throws OASServerException
*/
public UploadResult uploadWithUploadId(String vaultName, File file, String uploadId)
    throws OASClientException, OASServerException;

示例代码： File file = new File("[pathToYourFile]");
String vaultName = "[yourVaultName]";

//获得uploadId
//文件大小必须大于100MB，否则会抛异常提示用普通上传接口进行上传
String uploadId = archiveManager.initiateMultipartUpload(vaultName, file, "Hello OAS!");
//如果是已有的uploadId，直接使用之前获取过的uploadId
//String uploadId = "[uploadIdYouAlreadyHave]";
System.out.println("Get uploadId=" + uploadId);
UploadResult uploadResult = archiveManager.uploadWithUploadId(vaultName, file, uploadId);
System.out.println("Archive ID=" + uploadResult.getArchiveId());

使用已有的uploadId进行再次上传时，支持该任务的续传。例如，当一个Multipart任务在上传过程中被中止，这时，一些part已上传到OAS，一些part未完成。[backcolor=transparent]只要文件内容没有变化，根据保存下来的uploadId，可以继续上传这个文件剩余的part，已上传完毕的part不会重复上传。
如果开启了logger功能（如何配置logger请参考 《OAS Java SDK低级接口文档》），在日志中会看到以下信息： ....
Range 33554432-67108863 got from OAS server, contentEtag=BEC7D9E8EC48FFD9C3859C10B64B4EDF, treeEtag=8DA41EA468F5613080A3D14857EFEFFE
Range 33554432-67108863 has uploaded, contentEtag=BEC7D9E8EC48FFD9C3859C10B64B4EDF, treeEtag=8DA41EA468F5613080A3D14857EFEFFE
Range 33554432-67108863 is the same as remote,ignore it. md5=BEC7D9E8EC48FFD9C3859C10B64B4EDF,etagTree=8DA41EA468F5613080A3D14857EFEFFE
....

只有当这个part的md5和etagTree的校验信息一致时，SDK才会忽略它的上传动作，否则，这个part会被重传。日志中会出现 ....
Range 33554432-67108863 local Etag data is different from remote. It will be uploaded again!
....