keger/java-sdk

UPYUN Java SDK

UPYUN Java SDK

又拍云存储Java SDK，基于 又拍云存储HTTP REST API接口 开发，适用于Java 6及以上版本。

Maven 安装

<dependency>
  <groupId>com.upyun</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.1</version>
</dependency>

更新说明

使用1.0.x系列版本SDK的用户，注意原有部分方法已经不再推荐使用，但是出于兼容考虑目前任然保留，建议更新升级程序使用新版SDK提供的方法。

目录

• 云存储基础接口
  • 初始化UpYun
  • 创建目录
  • 删除目录
  • 获取目录文件列表
  • 上传文件
  • 获取文件信息
  • 获取使用量信息
  • 下载文件
  • 删除文件
• 图片处理接口
  • 制作图片缩略图
  • 图片裁剪
  • 图片旋转

云存储基础接口

初始化UpYun

    UpYun upyun = new UpYun("空间名称", "操作员名称", "操作员密码");

可选属性：

• 是否开启debug模式：默认不开启

    upyun.setDebug(true);

• 手动设置超时时间：默认为30秒

    upyun.setTimeout(60);

• 选择最优的接入点

    upyun.setApiDomain(UpYun.ED_AUTO);

根据国内的网络情况，又拍云存储API目前提供了电信、联通网通、移动铁通三个接入点。可以通过setApiDomain()方法进行设置，默认将根据网络条件自动选择接入点。

接入点有四个值可选：

UpYun.ED_AUTO    //根据网络条件自动选择接入点
UpYun.ED_TELECOM //电信接入点
UpYun.ED_CNC     //联通网通接入点
UpYun.ED_CTT     //移动铁通接入点

**注：**建议大家根据服务器网络状况，手动设置合理的接入点已获取最佳的访问速度

---

创建目录

方法原型：

public boolean mkDir(String path, boolean auto);

参数说明：

• path：目录路径，以/结尾
• auto（可选）：若为true则自动创建父级目录（只支持自动创建10级以内的父级目录）

返回值说明：

• 结果为true创建目录成功
• 若空间相同目录下已经存在同名的文件，则将返回『不允许创建目录』的错误

举例说明：

	String path = "/dir1/dir2/";
    // 创建目录，自动创建父级目录
    boolean result = upyun.mkDir(path, true);

---

删除目录

方法原型：

public boolean rmDir(String path);

参数说明：

• path：目录路径

返回值说明：

• 结果为true删除目录成功
• 若待删除的目录path下还存在任何文件或子目录，将返回『不允许删除』的错误

举例说明：

	String path = "/dir1/dir2/";
    // 删除目录
    boolean result = upyun.rmDir(path); 

---

获取目录文件列表

方法原型：

public List<FolderItem> readDir(String path);

UpYun.FolderItem包含属性:

• name 文件名
• type 文件类型
• size 文件大小
• date 文件创建日期

以上属性作用域皆为public，可直接调用

参数说明：

• path：目录路径

返回值说明：

• 若path目录没有内容时，返回null
• 若path目录不存在时，则将返『不存在目录』的错误

举例说明：

	String path = "/dir1/";
    // 获取目录中文件列表
    List<UpYun.FolderItem> items = upyun.readDir(path);
    for (int i = 0; i < items.size(); i++) {
		System.out.println(items.get(i));
	}

---

上传文件

方法原型：

public boolean writeFile(String filePath, String datas, boolean auto);
public boolean writeFile(String filePath, File file, boolean auto);
public boolean writeFile(String filePath, byte[] datas, boolean auto);

参数说明：

• filePath：保存到又拍云存储的文件路径，以/开始
• 第二个参数：接受String、File和byte[]三种类型的数据
• auto（可选）：若为true则自动创建父级目录（只支持自动创建10级以内的父级目录）

返回值说明：

• 结果为true上传文件成功

可选属性：

• 上传文件时可进行文件的MD5校验，若又拍云服务端收到的文件MD5值与用户设置的不一致，将返回 406 Not Acceptable 错误。对于需要确保上传文件的完整性要求的业务，可以设置该参数：

    upyun.setContentMD5(UpYun.md5(file));  

举例说明：

    // 例1：上传纯文本内容，自动创建父级目录
    String str = "Hello UpYun";
    boolean result = upyun.writeFile("/path/to/file", str, true);

    // 例2：采用数据流模式上传文件（节省内存）,自动创建父级目录
	File file = new File(localFilePath);
	upyun.setContentMD5(UpYun.md5(file));
	boolean result = upyun.writeFile(filePath, file, true);

注： 若空间内指定目录已存在相同文件，则会被覆盖，且不可逆。若要避免此情况，可以先通过获取文件信息来判断是否已经存在相同文件

---

获取文件信息

方法原型：

public Map<String, String> getFileInfo(String filePath);

参数说明：

• filePath：又拍云中文件的路径

返回值说明：

• 若filePath所指定文件不存在，则直接返回null
• Map 包含3个Key：

• type 文件类型
• size 文件大小
• date 创建日期

举例说明：

	String filePath = "/path/to/file";
    // 获取文件信息
    Map<String, String> info = upyun.getFileInfo(filePath);
    String type = info.get("type"); 
    String size = info.get("size"); 
    String date = info.get("date");

---

获取使用量信息

方法原型：

public long getBucketUsage();
public long getFolderUsage(String path);

举例说明：

    // 例1：获取整个空间的使用量情况
    long usage = upyun.getBucketUsage();
    
    // 例2：获取某个目录的使用量情况
    long usage = upyun.getFolderUsage(dir);

返回值说明：

• 返回值单位为Byte

---

下载文件

方法原型：

public String readFile(String filePath)；
public boolean readFile(String filePath, File file)；

参数说明：

• filePath：文件在又拍云存储中的路径
• file：本地临时文件（用来保存下载下来的数据）

返回值说明：

• 方法一：文本内容
• 方法二：结果为true下载成功

举例说明：

    // 例1：直接读取文本内容
    String remoteFilePath = "/path/to/file";
    String datas = upyun.readFile(remoteFilePath);

    // 例2：下载文件，采用数据流模式下载文件（节省内存）
    String remoteFilePath = "/path/to/file";
    File file = new File(localFilePath); // 创建一个本地临时文件
    boolean result = upyun.readFile(remoteFilePath, file);

---

删除文件

方法原型：

public boolean deleteFile(String filePath);

参数说明：

• filePath：文件在又拍云的路径

返回值说明：

• 若filePath指定的文件不存在，则返回『文件不存在』的错误
• 结果为true删除文件成功

举例说明：

	String filePath = "/path/to/file";
    // 删除文件
    boolean result = upyun.deleteFile(filePath);

图片处理接口

方法原型：

public boolean writeFile(String filePath, File file, boolean auto, Map<String, String> params);
public boolean writeFile(String filePath, byte[] datas, boolean auto, Map<String, String> params);
public boolean writeFile(String filePath, String datas, boolean auto, Map<String, String> params);

参数说明：

• filePath：保存到又拍云存储的路径
• 第二个参数：接受String、File和byte[]三种类型的图片数据内容
• auto（可选）：自动创建父级目录（只支持自动创建10级以内的父级目录）
• params：自定义图片处理参数的组合，详情请看params参数说明

返回值说明：

• 结果为true图片上传并处理成功

图片处理包括『制作图片缩略图』，『图片裁剪』，『图片旋转』。只需要选则不同的PARAMS参数就可以分别完成这些操作，下面分别举例说明。

---

制作图片缩略图

举例说明：

    Map<String, String> params = new HashMap<String, String>();
    
    // 设置缩略图类型
    params.put(PARAMS.KEY_X_GMKERL_TYPE.getValue(), PARAMS.VALUE_FIX_BOTH.getValue());
    
    // 设置缩略图参数值
    params.put(PARAMS.KEY_X_GMKERL_VALUE.getValue(), "150x150");
    
    // 设置缩略图的质量，默认 95
    params.put(PARAMS.KEY_X_GMKERL_QUALITY.getValue(), "95");
    
    // 待上传的图片文件
    File file = new File(localFilePath);
    
    String filePath = "/path/to/file";
    
    // 上传图片，并同时进行图片处理
    boolean result = upyun.writeFile(filePath, file, true, params);

---

图片裁剪

举例说明：

    // 设置缩略图的参数
    Map<String, String> params = new HashMap<String, String>();
    
    // 设置图片裁剪，参数格式：x,y,width,height
    params.put(PARAMS.KEY_X_GMKERL_CROP.getValue(), "0,0,100,100");
    
    // 待上传的图片文件
    File file = new File(localFilePath);
    
    // 上传图片，并同时进行图片处理
    boolean result = upyun.writeFile(savePath, file, autoMkDir, params);

---

图片旋转

举例说明：

   // 设置缩略图的参数
    Map<String, String> params = new HashMap<String, String>();
    
    // 设置图片旋转
    params.put(PARAMS.KEY_X_GMKERL_ROTATE.getValue(), PARAMS.VALUE_ROTATE_90.getValue());
    
    // 待上传的图片文件
    File file = new File(localFilePath);
    
    // 上传图片，并同时进行图片处理
    boolean result = upyun.writeFile(savePath, file, autoMkDir, params);