Skip to content

Commit dfd0120

Browse files
longbailongbai
committed
Merge pull request #152 from simon-liubin/pro/comment
 添加部分注释
2 parents efdd67e + 4ed6cc7 commit dfd0120

File tree

4 files changed

+209
-5
lines changed

4 files changed

+209
-5
lines changed

‎src/main/java/com/qiniu/common/Config.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ public final class Config {
88

99
public static final String VERSION = "7.0.0";
1010
/**
11-
* 断点上传时的分块大小(默认的分块大小, 不建议改变)
11+
* 断点上传时的分块大小(默认的分块大小, 不允许改变)
1212
*/
1313
public static final int BLOCK_SIZE = 4 * 1024 * 1024;
1414

@@ -38,7 +38,7 @@ public final class Config {
3838
*/
3939
public static String UP_HOST_BACKUP = "http://upload.qiniu.com";
4040
/**
41-
* 断点上传时的分片大小(可根据网络情况适当调整)
41+
* 断点上传时的分片大小(可根据网络情况适当调整，小于等于 4 * 1024 * 1024 )
4242
*/
4343
public static int CHUNK_SIZE = 256 * 1024;
4444
/**

‎src/main/java/com/qiniu/storage/BucketManager.java‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@
1414
import java.util.ArrayList;
1515
import java.util.Iterator;
1616

17+
/**
18+
* 主要涉及了空间资源管理及批量操作接口的实现，具体的接口规格可以参考
19+
*
20+
* @link http://developer.qiniu.com/docs/v6/api/reference/rs/
21+
*/
1722
public final class BucketManager {
1823
private final Auth auth;
1924
private final Client client;
@@ -23,6 +28,13 @@ public BucketManager(Auth auth) {
2328
client = new Client();
2429
}
2530

31+
/**
32+
* EncodedEntryURI格式
33+
*
34+
* @param bucket
35+
* @param key
36+
* @return urlsafe_base64_encode(Bucket:Key)
37+
*/
2638
public static String entry(String bucket, String key) {
2739
String en = bucket;
2840
if (key != null) {
@@ -32,21 +44,50 @@ public static String entry(String bucket, String key) {
3244
}
3345

3446
/**
47+
* 获取账号下所有空间名列表
48+
*
3549
* @return bucket 列表
3650
*/
3751
public String[] buckets() throws QiniuException {
3852
Response r = rsGet("/buckets");
3953
return r.jsonToObject(String[].class);
4054
}
4155

56+
/**
57+
* 根据前缀获取文件列表的迭代器
58+
*
59+
* @param bucket 空间名
60+
* @param prefix 文件名前缀
61+
* @return FileInfo迭代器
62+
*/
4263
public FileListIterator createFileListIterator(String bucket, String prefix) {
4364
return new FileListIterator(bucket, prefix, 1000, null);
4465
}
4566

67+
/**
68+
* 根据前缀获取文件列表的迭代器
69+
*
70+
* @param bucket 空间名
71+
* @param prefix 文件名前缀
72+
* @param limit 每次迭代的长度限制，最大1000，推荐值 100
73+
* @param delimiter 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。缺省值为空字符串
74+
* @return FileInfo迭代器
75+
*/
4676
public FileListIterator createFileListIterator(String bucket, String prefix, int limit, String delimiter) {
4777
return new FileListIterator(bucket, prefix, limit, delimiter);
4878
}
4979

80+
/**
81+
* 根据前缀获取文件列表
82+
*
83+
* @param bucket 空间名
84+
* @param prefix 文件名前缀
85+
* @param marker 上一次获取文件列表时返回的 marker
86+
* @param limit 每次迭代的长度限制，最大1000，推荐值 100
87+
* @param delimiter 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。缺省值为空字符串
88+
* @return
89+
* @throws QiniuException
90+
*/
5091
public FileListing listFiles(String bucket, String prefix, String marker, int limit, String delimiter)
5192
throws QiniuException {
5293
StringMap map = new StringMap().put("bucket", bucket).putNotEmpty("marker", marker)
@@ -57,53 +98,128 @@ public FileListing listFiles(String bucket, String prefix, String marker, int li
5798
return r.jsonToObject(FileListing.class);
5899
}
59100

101+
/**
102+
* 获取指定空间、文件名的状态
103+
*
104+
* @param bucket
105+
* @param key
106+
* @return
107+
* @throws QiniuException
108+
*/
60109
public FileInfo stat(String bucket, String key) throws QiniuException {
61110
Response r = rsGet("/stat/" + entry(bucket, key));
62111
return r.jsonToObject(FileInfo.class);
63112
}
64113

114+
/**
115+
* 删除指定空间、文件名的文件
116+
*
117+
* @param bucket
118+
* @param key
119+
* @throws QiniuException
120+
*/
65121
public void delete(String bucket, String key) throws QiniuException {
66122
rsPost("/delete/" + entry(bucket, key));
67123
}
68124

125+
/**
126+
* 修改指定空间、文件的文件名
127+
*
128+
* @param bucket
129+
* @param oldname
130+
* @param newname
131+
* @throws QiniuException
132+
*/
69133
public void rename(String bucket, String oldname, String newname) throws QiniuException {
70134
move(bucket, oldname, bucket, newname);
71135
}
72136

137+
/**
138+
* 复制文件。要求空间在同一账号下。
139+
*
140+
* @param from_bucket
141+
* @param from_key
142+
* @param to_bucket
143+
* @param to_key
144+
* @throws QiniuException
145+
*/
73146
public void copy(String from_bucket, String from_key, String to_bucket, String to_key) throws QiniuException {
74147
String from = entry(from_bucket, from_key);
75148
String to = entry(to_bucket, to_key);
76149
String path = "/copy/" + from + "/" + to;
77150
rsPost(path);
78151
}
79152

153+
/**
154+
* 移动文件。要求空间在同一账号下。
155+
*
156+
* @param from_bucket
157+
* @param from_key
158+
* @param to_bucket
159+
* @param to_key
160+
* @throws QiniuException
161+
*/
80162
public void move(String from_bucket, String from_key, String to_bucket, String to_key) throws QiniuException {
81163
String from = entry(from_bucket, from_key);
82164
String to = entry(to_bucket, to_key);
83165
String path = "/move/" + from + "/" + to;
84166
rsPost(path);
85167
}
86168

169+
/**
170+
* 修改完文件mimeTYpe
171+
*
172+
* @param bucket
173+
* @param key
174+
* @param mime
175+
* @throws QiniuException
176+
*/
87177
public void changeMime(String bucket, String key, String mime) throws QiniuException {
88178
String resource = entry(bucket, key);
89179
String encode_mime = UrlSafeBase64.encodeToString(mime);
90180
String path = "/chgm/" + resource + "/mime/" + encode_mime;
91181
rsPost(path);
92182
}
93183

184+
/**
185+
* 抓取指定地址的文件，已指定名称保存在指定空间。
186+
* 要求指定url可访问。
187+
* 大文件不建议使用此接口抓取。可先下载再上传。
188+
*
189+
* @param url
190+
* @param bucket
191+
* @param key
192+
* @throws QiniuException
193+
*/
94194
public void fetch(String url, String bucket, String key) throws QiniuException {
95195
String resource = UrlSafeBase64.encodeToString(url);
96196
String to = entry(bucket, key);
97197
String path = "/fetch/" + resource + "/to/" + to;
98198
ioPost(path);
99199
}
100200

201+
/**
202+
* 对于设置了镜像存储的空间，从镜像源站抓取指定名称的资源并存储到该空间中。
203+
* 如果该空间中已存在该名称的资源，则会将镜像源站的资源覆盖空间中相同名称的资源
204+
*
205+
* @param bucket
206+
* @param key
207+
* @throws QiniuException
208+
*/
101209
public void prefetch(String bucket, String key) throws QiniuException {
102210
String resource = entry(bucket, key);
103211
String path = "/prefetch/" + resource;
104212
ioPost(path);
105213
}
106214

215+
/**
216+
* 批量执行文件管理相关操作
217+
*
218+
* @param operations
219+
* @return
220+
* @throws QiniuException
221+
* @see Batch
222+
*/
107223
public Response batch(Batch operations) throws QiniuException {
108224
return rsPost("/batch", operations.toBody());
109225
}
@@ -137,6 +253,9 @@ private Response post(String url, byte[] body) throws QiniuException {
137253
return client.post(url, body, headers, Client.FormMime);
138254
}
139255

256+
/**
257+
* 文件管理操作指令
258+
*/
140259
public static class Batch {
141260
private ArrayList<String> ops;
142261

@@ -200,6 +319,9 @@ public byte[] toBody() {
200319
}
201320
}
202321

322+
/**
323+
* 获取文件列表迭代器
324+
*/
203325
public class FileListIterator implements Iterator<FileInfo[]> {
204326
private String marker = null;
205327
private String bucket;

‎src/main/java/com/qiniu/storage/UploadManager.java‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,14 @@ public Response put(final byte[] data, final String key, final String token) thr
7575
/**
7676
* 上传数据
7777
*
78-
* @param data 上传的数据
79-
* @param key 上传数据保存的文件名
78+
* @param data 上传的数据
79+
* @param key 上传数据保存的文件名
8080
* @param token 上传凭证
81+
* @param params 自定义参数，如 params.put("x:foo", "foo")
82+
* @param mime 指定文件mimetype
83+
* @param checkCrc 是否验证crc32
84+
* @return
85+
* @throws QiniuException
8186
*/
8287
public Response put(final byte[] data, final String key, final String token, StringMap params,
8388
String mime, boolean checkCrc) throws QiniuException {
@@ -106,6 +111,9 @@ public Response put(String filePath, String key, String token) throws QiniuExcep
106111
* @param filePath 上传的文件路径
107112
* @param key 上传文件保存的文件名
108113
* @param token 上传凭证
114+
* @param params 自定义参数，如 params.put("x:foo", "foo")
115+
* @param mime 指定文件mimetype
116+
* @param checkCrc 是否验证crc32
109117
*/
110118
public Response put(String filePath, String key, String token, StringMap params,
111119
String mime, boolean checkCrc) throws QiniuException {
@@ -129,6 +137,8 @@ public Response put(File file, String key, String token) throws QiniuException {
129137
* @param file 上传的文件对象
130138
* @param key 上传文件保存的文件名
131139
* @param token 上传凭证
140+
* @param mime 指定文件mimetype
141+
* @param checkCrc 是否验证crc32
132142
*/
133143
public Response put(File file, String key, String token, StringMap params,
134144
String mime, boolean checkCrc) throws QiniuException {

0 commit comments

Comments
 (0)