为项目编写Readme.MD文件

1# shurnim-storage
2
3## 目录
4- [shurnim-storage](#shurnim-storage)
5 - [目录](#目录)
6 - [背景介绍](#背景介绍)
7 - [项目介绍](#项目介绍)
8 - [使用说明](#使用说明)
9  - [获取代码](#获取代码)
10  - [开发插件](#开发插件)
11  - [使用*ShurnimStorage*接口](#使用shurnimstorage接口)
12   - [接口介绍](#接口介绍)
13   - [使用样例](#使用样例)
14 - [其他](#其他)
15
16<a name="背景介绍"></a>
17## 背景介绍
18
19*Shurnim (鼠尼玛)*，是我和我老婆曾经养过的一只仓鼠的名字。<br/>
20*shurnim-storage*，是一个插件式云存储/网盘同步管理工具。是在参加又拍云开发大赛的过程中设计并开发。
21
22<a name="项目介绍"></a>
23## 项目介绍
24
25*shurnim-storage* 的设计初衷是给大家提供一个可方便扩展的云存储/网盘同步工具。分后端接口和前端UI界面两部分。<br>
26
27由于目前各种云存储和网盘系统层出不穷，单一工具往往支持支持某几个特定存储之间的同步，如**又拍云**到**七牛云存储**的同步工具，此时如若想同步到其他存则可能需要新的工具，给用户带来不便。*shurnim-storage*  正是为了解决此问题而设计的。
28
29在*shurnim-storage*中，用户使用的固定的统一的后端接口。而所有云存储/网盘API的支持则是以插件的形式部署到系统中的。如此，如果用户想要一个从**又拍云**到**Dropbox**的同步工具，则只需要在原有基础上，增加**Dropbox**的插件，即可实现互通，方便快捷。<br/>
30
31同时，后端统一接口的设计也考虑到界面开发的需求，可直接通过后端提供的接口开发具有上述扩展功能的云存储UI工具。<br>
32
33目前，后端整体框架的核心部分已经基本开发完成。只需逐步补充后端接口和插件开发接口的定义即可。但由于个人时间和能力所限，UI部分没有开发，有兴趣的同学可以一试。
34
35<a name="使用说明"></a>
36## 使用说明
37
38<a name="获取代码"></a>
39### 获取代码
40
41* GitHub项目主页: <https://github.com/lihongzheshuai/shurnim-storage>
42* OSChina项目主页: <http://git.oschina.net/onecoder/shurnim-storage><br>
43OSChina上的会持续更新。
44
45另外你也可以通过OSChina的Maven库获取依赖，或者自己编译jar包。
46
47* maven
48
49 1. 加入OSC仓库
50 
51    <repositories>
52              <repository>
53               <id>nexus</id>
54               <name>local private nexus</name>
55               <url>http://maven.oschina.net/content/groups/public/</url>
56               <releases>
57                <enabled>true</enabled>
58               </releases>
59               <snapshots>
60                <enabled>false</enabled>
61               </snapshots>
62              </repository>
63             </repositories>
64
65 2. 加入依赖
66 
67   <dependency>
68     <groupId>com.coderli</groupId>
69     <artifactId>shurnim-storage</artifactId>
70      <version>0.1-alpha</version>
71   </dependency>
72* Gradle 编译Jar
73
74在项目目录执行
75 
76 gradle jar
77 
78<a name="开发插件"></a>
79### 开发插件
80
81在*shurnim-storage*中，插件就像一块一块的积木，不但支撑着框架的功能，也是框架可扩展性的基石。开发一个插件，仅需两步：
82
831. 实现PluginAPI接口
84
85```java
86package com.coderli.shurnim.storage.plugin;
87
88import java.io.File;
89import java.util.List;
90
91import com.coderli.shurnim.storage.plugin.model.Resource;
92
93/**
94 * 各种云存储插件需要实现的通用接口
95 * 
96 * @author OneCoder
97 * @date 2014年4月22日 下午9:43:41
98 * @website http://www.coderli.com
99 */
100public interface PluginAPI {
101
102 /**
103  * 初始化接口
104  * 
105  * @author OneCoder
106  * @date 2014年5月19日 下午10:47:40
107  */
108 void init();
109
110 /**
111  * 获取子资源列表
112  * 
113  * @param parentPath
114  * @return
115  * @author OneCoder
116  * @date 2014年4月24日 下午11:29:14
117  */
118 List<Resource> getChildResources(String parentPath);
119
120 /**
121  * 下载特定的资源
122  * 
123  * @param parentPath
124  *            目录路径
125  * @param name
126  *            资源名称
127  * @param storePath
128  *            下载资源保存路径
129  * @return
130  * @author OneCoder
131  * @date 2014年4月24日 下午11:30:19
132  */
133 Resource downloadResource(String parentPath, String name, String storePath);
134
135 /**
136  * 创建文件夹
137  * 
138  * @param path
139  *            文件夹路径
140  * @param auto
141  *            是否自动创建父目录
142  * @return
143  * @author OneCoder
144  * @date 2014年5月15日 下午10:10:04
145  */
146 boolean mkdir(String path, boolean auto);
147
148 /**
149  * 上传资源
150  * 
151  * @param parentPath
152  *            父目录路径
153  * @param name
154  *            资源名称
155  * @param uploadFile
156  *            待上传的本地文件
157  * @return
158  * @author OneCoder
159  * @date 2014年5月15日 下午10:40:13
160  */
161 boolean uploadResource(String parentPath, String name, File uploadFile);
162}
163\```
164
165目前插件的接口列表仅为同步资源设计，如果想要支持更多操作(如删除，查找等)，可扩展该接口定义。<br/><br/>
166接口中，所有的参数和返回值均为*shurnim-storage*框架中定义的通用模型。因此，您在开发插件过程中需要将特定SDK中的模型转换成接口中提供的模型。<br/><br/>
167插件实现类只要与*shurnim-storage*工程在同一个classpath即可使用。您既可以直接在源码工程中开发插件，就如工程里提供的*upyun*和*qiniu*插件一样，也可以作为独立工程开发，打成jar，放置在同一个classpath下。<br/><br/>
168*upyun*插件样例(功能不完整):
169
170```java    
171package com.coderli.shurnim.storage.upyun.plugin;
172
173import java.io.File;
174import java.util.List;
175
176import com.coderli.shurnim.storage.plugin.AbstractPluginAPI;
177import com.coderli.shurnim.storage.plugin.model.Resource;
178import com.coderli.shurnim.storage.plugin.model.Resource.Type;
179import com.coderli.shurnim.storage.upyun.api.UpYun;
180
181public class UpYunPlugin extends AbstractPluginAPI {
182
183 private UpYun upyun;
184 private String username;
185 private String password;
186 private String bucketName;
187
188 public UpYun getUpyun() {
189  return upyun;
190 }
191
192 public void setUpyun(UpYun upyun) {
193  this.upyun = upyun;
194 }
195
196 public String getUsername() {
197  return username;
198 }
199
200 public void setUsername(String username) {
201  this.username = username;
202 }
203
204 public String getPassword() {
205  return password;
206 }
207
208 public void setPassword(String password) {
209  this.password = password;
210 }
211
212 public String getBucketName() {
213  return bucketName;
214 }
215
216 public void setBucketName(String bucketName) {
217  this.bucketName = bucketName;
218 }
219
220 /*
221  * (non-Javadoc)
222  * 
223  * @see
224  * com.coderli.shurnim.storage.plugin.PluginAPI#getChildResources(java.lang
225  * .String)
226  */
227 @Override
228 public List<Resource> getChildResources(String parentPath) {
229  return null;
230 }
231
232 /*
233  * (non-Javadoc)
234  * 
235  * @see
236  * com.coderli.shurnim.storage.plugin.PluginAPI#downloadResource(java.lang
237  * .String, java.lang.String, java.lang.String)
238  */
239 @Override
240 public Resource downloadResource(String parentPath, String name,
241   String storePath) {
242  File storeFile = new File(storePath);
243//  if (!storeFile.exists()) {
244//   try {
245//    storeFile.createNewFile();
246//   } catch (IOException e) {
247//    e.printStackTrace();
248//   }
249//  }
250  String filePath = getFullPath(parentPath, name);
251  upyun.readDir("/api");
252  if (upyun.readFile(filePath, storeFile)) {
253   Resource result = new Resource();
254   result.setName(name);
255   result.setPath(parentPath);
256   result.setType(Type.FILE);
257   result.setLocalFile(storeFile);
258   return result;
259  }
260  return null;
261 }
262
263 String getFullPath(String parentPath, String name) {
264  if (!parentPath.endsWith(File.separator)) {
265   parentPath = parentPath + File.separator;
266  }
267  return parentPath + name;
268 }
269
270 /*
271  * (non-Javadoc)
272  * 
273  * @see com.coderli.shurnim.storage.plugin.PluginAPI#mkdir(java.lang.String,
274  * boolean)
275  */
276 @Override
277 public boolean mkdir(String path, boolean auto) {
278  // TODO Auto-generated method stub
279  return false;
280 }
281
282 /*
283  * (non-Javadoc)
284  * 
285  * @see
286  * com.coderli.shurnim.storage.plugin.PluginAPI#uploadResource(java.lang
287  * .String, java.lang.String, java.io.File)
288  */
289 @Override
290 public boolean uploadResource(String parentPath, String name,
291   File uploadFile) {
292  // TODO Auto-generated method stub
293  return false;
294 }
295
296 /*
297  * (non-Javadoc)
298  * 
299  * @see com.coderli.shurnim.storage.plugin.AbstractPluginAPI#init()
300  */
301 @Override
302 public void init() {
303  upyun = new UpYun(bucketName, username, password);
304 }
305
306}
307\```
308
309
3102. 编写插件配置文件
311
312```xml
313<?xml version="1.0" encoding="UTF-8"?>
314<plugin>
315 <id>qiniu</id>
316 <name>七牛云存储</name>
317 <api>
318  <className>com.coderli.shurnim.storage.qiniu.QiniuPlugin</className>
319  <params>
320   <param name="access_key" displayName="ACCESS_KEY">EjREKHI_GFXbQzyrKdVhhXrIRyj3fRC1s9UmZPZO
321   </param>
322   <param name="secret_key" displayName="SECRET_KEY">88NofFWUvkfJ6T6rGRxlDSZOQxWkIxY2IsFIXJLX
323   </param>
324   <param name="bucketName" displayName="空间名">onecoder
325   </param>
326  </params>
327 </api>
328</plugin>
329\```
330   * **id** 为该插件在*shurnim-storage*框架下的唯一标识，不可重复，必填。
331    * **name** 为显示值，为UI开发提供可供显示的有语义的值。
332    * **className** 为插件接口实现类的完整路径。必填
333    * **params/param** 为插件需要用户配置的参数列表。其中
334     * *name* 代表参数名，需要与接口实现类中的参数名严格一致，且必须有相应的set方法的格式要求严格，即set+首字母大写的参数名。例如:setAccess_key(String arg); 目前只支持*String*类型的参数。
335     * *displayName* 为参数显示名，同样是为了UI开发的考虑，方便用户开发出可根据参数列表动态显示的UI界面。
336     * 参数的值可以直接配置在配置文件中，也可以在运行期动态赋值。直接配置值，对于直接使用后端接口来说较为方便。对于UI开发来说，运行期动态赋值更为合理。<br/></br>
337
338 在使用源码工程时，插件配置文件统一放置在工程的*plugins*目录下。你也可以统一放置在任何位置。此时，在构造后端接口实例时，需要告知接口该位置。
339 
340<a name="使用ShurnimStorage接口"></a>
341### 使用*ShurnimStorage*接口
342
343<a name="接口介绍"></a>
344#### 接口介绍
345
346**ShurnimStorage**接口是*shurinm-storage*框架全局的也是唯一的接口，目前定义如
347
348```java
349package com.coderli.shurnim.storage;
350
351import java.util.List;
352import java.util.Map;
353
354import com.coderli.shurnim.storage.plugin.model.Plugin;
355import com.coderli.shurnim.storage.plugin.model.Resource;
356
357/**
358 * 后台模块的全局接口<br>
359 * 通过该接口使用后台的全部功能。<br>
360 * 使用方式:<br>
361 * <li>
362 * 1.先通过{@link #getSupportedPlugins()}方法获取所有支持的平台/插件列表。 <li>
363 * 2.将列表中返回的ID传入对应的接口参数中，进行对应的平台的相关操作。<br>
364 * 需要注意的是，不同平台的插件需要给不同的参数赋值，该值可以直接配置在配置文件中。<br>
365 * 也可以在运行期动态赋值。(会覆盖配置文件中的值。)<br>
366 * 
367 * 参数列表的设计，方便UI开发人员动态的根据参数列表生成可填写的控件。并给参数赋值。增强了可扩展性。
368 * 
369 * @author OneCoder
370 * @date 2014年4月22日 下午9:21:58
371 * @website http://www.coderli.com
372 */
373public interface ShurnimStorage {
374
375 /**
376  * 获取当前支持的插件列表<br>
377  * 没有支持的插件的时候可能返回null
378  * 
379  * @return
380  * @author OneCoder
381  * @date 2014年5月7日 下午8:53:25
382  */
383 List<Plugin> getSupportedPlugins();
384
385 /**
386  * 给指定的插件的对应参数赋值<br>
387  * 此处赋值会覆盖配置文件中的默认值
388  * 
389  * @param pluginId
390  *            插件ID
391  * @param paramsKV
392  *            参数键值对
393  * @author OneCoder
394  * @date 2014年5月9日 上午12:41:53
395  */
396 void setParamValues(String pluginId, Map<String, String> paramsKV);
397
398 /**
399  * 获取插件对应目录下的资源列表
400  * 
401  * @param pluginId
402  *            插件ID
403  * @param path
404  *            指定路径
405  * @return
406  * @author OneCoder
407  * @date 2014年5月11日 上午8:52:00
408  */
409 List<Resource> getResources(String pluginId, String path);
410
411 /**
412  * 同步资源
413  * 
414  * @param fromPluginId
415  *            待同步的插件Id
416  * @param toPluginIds
417  *            目标插件Id
418  * @param resource
419  *            待同步的资源
420  * @return 同步结果
421  * @author OneCoder
422  * @date 2014年5月11日 上午11:41:24
423  */
424 boolean sycnResource(String fromPluginId, String toPluginId,
425    Resource resource) throws Exception;
426}
427\```      
428
429当前接口实际仅包含了获取资源列表*getResources*和同步资源*sycnResource*功能，*getSupportedPlugins*和*setParamValues*实际为辅助接口，在UI开发时较为有用。<br/><br/>
430同样，您也可以扩展开发该接口增加更多的您喜欢的特性。例如，同时删除给定存储上的文件。当然，这需要插件接口的配合支持。<br/><br/>
431
432这里，*sycnResource*设计成插件间一对一的形式，是考虑到获取同步是否成功的结果的需求。如果您想开发一次同步到多个存储的功能，建议您重新开发您自己的接口实现类，因为默认实现会多次下次资源(每次同步后删除)，造成网络资源的浪费。
433
434接口的默认实现类是: **DefaultShurnimStorageImpl**
435
436<a name="使用样例"></a>
437#### 使用样例
438```java        
439package com.coderli.shurnim.test.shurnimstorage;
440
441import org.junit.Assert;
442import org.junit.BeforeClass;
443import org.junit.Test;
444
445import com.coderli.shurnim.storage.DefaultShurnimStorageImpl;
446import com.coderli.shurnim.storage.ShurnimStorage;
447import com.coderli.shurnim.storage.plugin.model.Resource;
448import com.coderli.shurnim.storage.plugin.model.Resource.Type;
449
450/**
451 * 全局接口测试类<br>
452 * 时间有限，目前仅作整体接口测试。细粒度的单元测试，随开发补充。
453 * 
454 * @author OneCoder
455 * @date 2014年5月19日 下午10:50:27
456 * @website http://www.coderli.com
457 */
458public class ShurnimStorageTest {
459
460 private static ShurnimStorage shurnim;
461
462 @BeforeClass
463 public static void init() {
464  shurnim = new DefaultShurnimStorageImpl(
465    "/Users/apple/git/shurnim-storage-for-UPYUN/plugins");
466 }
467
468 @Test
469 public void testSycnResource() {
470  Resource syncResource = new Resource();
471  syncResource.setPath("/api");
472  syncResource.setName("api.html");
473  syncResource.setType(Type.FILE);
474  try {
475   Assert.assertTrue(shurnim.sycnResource("upyun", "qiniu",
476     syncResource));
477  } catch (Exception e) {
478   e.printStackTrace();
479  }
480 }
481}
482\```
483<a name="其他"></a>
484## 其他
485
486时间仓促，功能简陋，望您包涵。OneCoder(Blog:[http://www.coderli.com](http://www.coderli.com))特别希望看到该项目对您哪怕一点点的帮助。任意的意见和建议，欢迎随意与我沟通,联系方式：
487
488* Email: <wushikezuo@gmail.com>
489* QQ:57959968
490* Blog:[OneCoder](http://www.coderli.com)
491