readme

2017-08-01 13:52:03 +08:00
parent 3644ae02c9
commit fdf6879288
82 changed files with 181 additions and 20702 deletions
--- a/README.md
+++ b/README.md
@ -8,7 +8,7 @@ Aria有以下特点：
   - 可以在Activity、Service、Fragment、Dialog、popupWindow、Notification等组件中使用
   - 支持任务自动调度，使用者不需要关心任务状态切换的逻辑
   - [通过Aria的事件，能很容易获取当前下载任务的下载状态](#下载状态获取)
-   - [一句代码加可以获取当前的下载速度](#常用接口)
+   - [一句代码加可以获取当前的下载速度](#任务实体常用数据)
   - [一句代码就可以动态设置最大下载数](#代码中设置参数)
   - [一句代码实现速度限制](#常用接口)
   - [通过修改配置文件很容易就能修改下载线程数](#配置文件设置参数)
@ -18,11 +18,10 @@ Aria有以下特点：
   - 在配置文件中很容易就可以设置CA证书的信息
 + 支持300、301、302重定向下载链接下载
 + 支持上传操作
-
-
-Aria怎样使用？
-* [下载](#使用)
-* [上传](#上传)
+ + 支持FTP断点续传下载、上传
+   - [FTP 单文件下载](#单任务下载)
+   - [FTP 文件夹下载](#文件夹下载)
+   - [FTP 单文件上传](#单任务上传)

 如果你觉得Aria对你有帮助，您的star和issues将是对我最大支持.`^_^`

@ -72,6 +71,7 @@ annotationProcessor 'com.arialyy.aria:aria-compiler:3.2.12'
  ```java
  Aria.download(this).load(DOWNLOAD_URL).cancel();
  ```
+
 ### 一组任务下载
 任务组的下载和普通任务的下载基本上差不多，区别在于，任务组下载不需要对每一个子任务设置保存路径，**但是需要设置任务组保存文件夹路径，所有子任务都保存在该文件夹下**

@ -94,211 +94,7 @@ annotationProcessor 'com.arialyy.aria:aria-compiler:3.2.12'
  ```java
  Aria.download(this).load(urls).cancel();
  ```
-
-### 下载状态获取
-如果你希望读取下载进度或下载信息，那么你需要创建事件类，并在onResume(Activity、Fragment)或构造函数(Dialog、PopupWindow)，将该事件类注册到Aria管理器。
-
-1. 将对象注册到Aria
-
- `Aria.download(this).register();`或`Aria.upload(this).register();`
- ```java
- @Override
- protected void onCreate(Bundle savedInstanceState) {
-    super.onCreate(savedInstanceState);
-    Aria.download(this).register();
-  }
- ```
-
-2. 使用`@Download`或`@Upload`或`@DownloadGroup`注解你的函数
-
- **注意：**
- - 注解回掉采用Apt的方式实现，所以，你不需要担心这会影响你机器的性能
- - 被注解的方法**不能被private修饰**
- - 被注解的方法**只能有一个参数，并且参数类型必须是`DownloadTask`或`UploadTask`或`DownloadGroupTask`**
- - 方法名可以为任意字符串
-
-3. 除了在widget（Activity、Fragment、Dialog、Popupwindow）中使用注解方法外，你还可以在Service、Notification等组件中使用注解函数。
-
-  ```java
-  @Download.onPre(DOWNLOAD_URL)
-  protected void onPre(DownloadTask task) {}
-
-  @Download.onTaskStart
-  void taskStart(DownloadTask task) {}
-
-  @Download.onTaskRunning
-  protected void running(DownloadTask task) {}
-
-  @Download.onTaskResume
-  void taskResume(DownloadTask task) {}
-
-  @Download.onTaskStop
-  void taskStop(DownloadTask task) {}
-
-  @Download.onTaskCancel
-  void taskCancel(DownloadTask task) {}
-
-  @Download.onTaskFail
-  void taskFail(DownloadTask task) {}
-
-  @Download.onTaskComplete
-  void taskComplete(DownloadTask task) {}
-
-  @Download.onNoSupportBreakPoint
-  public void onNoSupportBreakPoint(DownloadTask task) {}
-
-  ```
-4. 如果你希望对单个任务，或某一些特定任务设置监听器。<br>
- **在注解中添加任务的下载地址，则表示只有该任务才会触发被注解的方法**。
-
- ```java
- @Download.onTaskRunning({
-      "https://test.xx.apk",
-      "http://test.xx2.apk"
-  }) void taskRunning(DownloadTask task) {
-    mAdapter.setProgress(task.getDownloadEntity());
-  }
- ```
-在上面的例子中，只有下载地址是`https://test.xx.apk`和`http://test.xx2.apk`才会触发
-`taskRunning(DownloadTask task)`方法。
-
-### Aria参数配置
-#### 配置文件设置参数
-创建`aria_config.xml`文件，将其放在`assets`目录下，添加以下内容
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<aria>
-
-  <!--注意，修改该配置文件中的属性会覆盖代码中所设置的属性-->
-  <download>
-
-    <!--设置下载线程，线程下载数改变后，新的下载任务才会生效-->
-    <threadNum value="4"/>
-
-    <!--是否打开下载广播，默认为false，不建议使用广播，你可以使用Download注解来实现事件回调-->
-    <openBroadcast value="false"/>
-
-    <!--设置下载队列最大任务数， 默认为2-->
-    <maxTaskNum value="2"/>
-
-    <!--设置下载失败，重试次数，默认为10-->
-    <reTryNum value="10"/>
-
-    <!--设置重试间隔，单位为毫秒，默认2000毫秒-->
-    <reTryInterval value="5000"/>
-
-    <!--设置url连接超时时间，单位为毫秒，默认5000毫秒-->
-    <connectTimeOut value="5000"/>
-
-    <!--设置IO流读取时间，单位为毫秒，默认20000毫秒，该时间不能少于10000毫秒-->
-    <iOTimeOut value="20000"/>
-
-    <!--设置写文件buff大小，该数值大小不能小于2048，数值变小，下载速度会变慢-->
-    <buffSize value="8192"/>
-
-    <!--设置https ca 证书信息；path 为assets目录下的CA证书完整路径，name 为CA证书名-->
-    <ca name="" path=""/>
-
-    <!--是否需要转换速度单位，转换完成后为：1b/s、1kb/s、1mb/s、1gb/s、1tb/s，如果不需要将返回byte长度-->
-    <convertSpeed value="true"/>
-
-    <!--设置最大下载速度，单位：kb, 为0表示不限速-->
-    <maxSpeed value="0"/>
-
-  </download>
-
-  <upload>
-    <!--是否打开上传广播，默认为false，不建议使用广播，你可以使用Upload注解来实现事件回调-->
-    <openBroadcast value="false"/>
-
-    <!--设置上传队列最大任务数， 默认为2-->
-    <maxTaskNum value="2"/>
-
-    <!--设置上传失败，重试次数，默认为10-->
-    <reTryNum value="10"/>
-
-    <!--设置重试间隔，单位为毫秒-->
-    <reTryInterval value="2000"/>
-
-    <!--设置url连接超时时间，单位为毫秒，默认5000毫秒-->
-    <connectTimeOut value="5000"/>
-  </upload>
-
-</aria>
-```
-
-#### 代码中设置参数
-除了文件方式外修改Aria参数外，同样的，你也可以在代码中动态修改Aria参数</br>
-通过`Aria.get(this).getDownloadConfig()`或`Aria.get(this).getUploadConfig()`直接获取配置文件，然后修改参数</br>
-如以下所示：
-```java
-// 修改最大下载数，调用完成后，立即生效
-// 如当前下载任务数是4，修改完成后，当前任务数会被Aria自动调度任务数
-Aria.get(this).getDownloadConfig().setMaxTaskNum(3);
-```
-
-### 常用接口
-* 停止所有任务
-
- ```java
- Aria.download(this).stopAllTask();
- ```
-
-* 恢复所有停止的任务
-
- ```java
-Aria.download(this).resumeAllTask();
- ```
-
-* 删除所有任务
-
- ```java
- Aria.download(this).removeAllTask();
- ```
-
-* 最大下载速度限制
- ```java
- //单位为 kb
- Aria.download(this).setMaxSpeed(speed);
- ```
-
-* 获取当前任务的下载速度<br>
-速度参数有点特殊，需要[下载事件支持](#下载状态获取)
-``` java
-@Override public void onTaskRunning(DownloadTask task) {
-  //如果你打开了速度单位转换配置，将可以通过以下方法获取带单位的下载速度，如：1 mb/s
-  String convertSpeed = task.getConvertSpeed();
-  //如果你有自己的单位格式，可以通过以下方法获取原始byte长度
-  long speed = task.getSpeed();
-}
-```
-
-* 获取下载的文件大小、当前进度百分比</br>
-同样的，你也可以在DownloadTask对象中获取下载的文件大小
-```
-@Override public void onTaskRunning(DownloadTask task) {
-  //获取文件大小
-  long fileSize = task.getFileSize();
-  //获取单位转换后的文件大小
-  String fileSize1 = task.getConvertFileSize();
-  //当前进度百分比
-  int percent = task.getPercent();
-}
-```
-
-* 设置高优先级任务<br>
- 如果你希望优先下载某一个任务，你可以
-``` java
-Aria.download(this).load(DOWNLOAD_URL).setDownloadPath(PATH).setHighestPriority();
-```
-
-* 设置扩展字段<br>
- 有的时候，你可能希望在下载的时候存放一些自己的数据</br>
-**TIP**: 如果你数据比较多，或者数据比较复杂，你可以先把数据转换为**JSON**，然后再将其存到Aria的下载实体中
-```java
-Aria.download(this).load(DOWNLOAD_URL).setExtendField(str)
-```
-
+  
 ## 上传
 * 添加任务(只添加，不上传)

@ -324,6 +120,169 @@ Aria.download(this).load(DOWNLOAD_URL).setExtendField(str)
 ```java
 Aria.upload(this).load(filePath).cancel();
 ```
+ 
+## FTP
+### 单文件下载
+* 开始\恢复下载
+```java
+Aria.download(this)
+	.loadFtp("ftp://172.18.104.129:21/haha/large.rar")
+    .login("lao", "123456")				//登录FTP服务器
+    .setDownloadPath("/mnt/sdcard/")	//设置文件保存文件夹
+    .start();
+```
+
+* 暂停
+```java
+Aria.download(this).loadFtp(URL).stop();
+```
+
+* 删除任务
+```java
+Aria.download(this).loadFtp(URL).cancel();
+```
+
+### 文件夹下载
+* 开始\恢复下载
+
+ ```java
+ Aria.download(this)
+	.loadFtpDir("ftp://172.18.104.129:21/haha/")
+    .setDownloadDirPath(downloadPath)
+            .login("lao", "123456")
+            .start();
+ ```
+
+* 暂停
+```java
+Aria.download(this).loadFtpDir(dir).stop();
+```
+
+* 删除任务
+```java
+Aria.download(this).loadFtpDir(dir).cancel();
+```
+
+### 单文件上传
+* 开始\恢复上传
+
+ ```java
+ Aria.upload(this)
+ 	.loadFtp("/mnt/sdcard/gggg.apk") //上传文件路径
+    .setUploadUrl(URL)		//上传的ftp服务器地址
+    .login("lao", "123456")
+    .start();
+ ```
+
+* 暂停
+```java
+ Aria.upload(this).loadFtp(FILE_PATH).stop();
+```
+
+* 删除任务
+```java
+Aria.upload(this).loadFtp(FILE_PATH).cancel();
+```
+
+### 任务状态获取
+如果你希望读取任务进度或任务的信息，那么你需要创建事件类，并在onResume(Activity、Fragment)或构造函数(Dialog、PopupWindow)，将该事件类注册到Aria管理器。
+
+1. 将对象注册到Aria
+
+ `Aria.download(this).register();`或`Aria.upload(this).register();`
+ ```java
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+    super.onCreate(savedInstanceState);
+    Aria.download(this).register();
+  }
+ ```
+
+2. 使用 `@Download` 或 `@Upload` 或 `@DownloadGroup` 注解你的函数
+
+ **注意：**
+ - 注解回掉采用Apt的方式实现，所以，你不需要担心这会影响你机器的性能
+ - 被注解的方法**不能被private修饰**
+ - 被注解的方法**只能有一个参数，并且参数类型必须是`DownloadTask`或`UploadTask`或`DownloadGroupTask`**
+ - 方法名可以为任意字符串
+
+3. 除了在widget（Activity、Fragment、Dialog、Popupwindow）中使用注解方法外，你还可以在Service、Notification等组件中使用注解函数。
+
+| 注解 | 说明 | 示例 |
+| ------| ------ | ------ |
+| `@Download.onPre` | 预处理的注解，在任务为开始前回调（一般在此处预处理UI界面） |  `@Download.onPre void onPre(DownloadTask task) {}` |
+| `@Download.onTaskStart` | 任务开始时的注解，新任务开始时进行回调 |  `@Download.onTaskStart void taskStart(DownloadTask task) {}`|
+| `@Download.onTaskResume` | 任务恢复时的注解，任务从停止恢复到运行前进行回调 | `@Download.onTaskResume void taskResume(DownloadTask task) {}` |
+| ` @Download.onTaskRunning` | 任务执行时的注解，任务正在执行时进行回调 | `@Download.onTaskRunning void running(DownloadTask task) {}` |
+| `@Download.onTaskStop` | 任务停止时的注解，任务停止时进行回调 | `@Download.onTaskStop void taskStop(DownloadTask task) {}` |
+| `@Download.onTaskCancel` | 任务被删除时的注解，任务被删除时进行回调 | `@Download.onTaskCancel void taskCancel(DownloadTask task) {}` |
+| `@Download.onTaskFail` | 任务失败时的注解，任务执行失败时进行回调 | `@Download.onTaskFail void taskFail(DownloadTask task) {}` |
+| ` @Download.onTaskComplete` | 任务完成时的注解，任务完成时进行回调 | ` @Download.onTaskComplete void taskComplete(DownloadTask task) {}` |
+| `@Download.onNoSupportBreakPoint` | 这是一个特殊的注解，用于处理不支持断点续传的任务 | `@Download.onNoSupportBreakPoint void onNoSupportBreakPoint(DownloadTask task) {}` |
+
+**TIP: **如果你子希望对单个任务，或某一些特定任务设置监听器。 <br>
+ **在注解中添加任务的下载地址，则表示只有该任务才会触发被注解的方法**。
+
+ ```java
+ @Download.onTaskRunning({
+      "https://test.xx.apk",
+      "http://test.xx2.apk"
+  }) void taskRunning(DownloadTask task) {
+    mAdapter.setProgress(task.getDownloadEntity());
+  }
+ ```
+在上面的例子中，只有下载地址是`https://test.xx.apk`和`http://test.xx2.apk`才会触发
+`taskRunning(DownloadTask task)`方法。
+
+### Aria参数配置
+#### 配置文件设置参数
+创建 [aria_config.xml](https://github.com/AriaLyy/Aria/blob/master/app/src/main/assets/aria_config.xml) 文件，将其放在`assets`目录下
+
+#### 代码中设置参数
+除了文件方式外修改Aria参数外，同样的，你也可以在代码中动态修改Aria参数</br>
+通过`Aria.get(this).getDownloadConfig()`或`Aria.get(this).getUploadConfig()`直接获取配置文件，然后修改参数</br>
+如以下所示：
+```java
+// 修改最大下载数，调用完成后，立即生效
+// 如当前下载任务数是4，修改完成后，当前任务数会被Aria自动调度任务数
+Aria.get(this).getDownloadConfig().setMaxTaskNum(3);
+```
+
+### 常用接口
+| api | 说明 |
+| ------| ------ |
+| `Aria.download(this).stopAllTask();` | 停止所有正在下载的任务 | 
+| `Aria.download(this).resumeAllTask();` | 恢复所有停止的任务 |
+| `Aria.download(this).removeAllTask();` | 删除所有任务</br> 1、如果任务为完成，会删除没有完成的文件</br> 2、如果使用`removeAllTask(true)`方法，会将已经下载完成和未完成的文件删除</br> 3、如果是上传任务，不会删除本地的上传文件，但如果使用`removeAllTask(true)`，同样会删除本地上传文件 |
+| `Aria.download(this).setMaxSpeed(speed)` | 限制单个任务的上传、下载的最大速度（单位为 kb） |
+| `Aria.download(this).load(DOWNLOAD_URL)`<br>`.setExtendField(str)` | 设置扩展字段，有的时候，你可能希望在下载的时候存放一些自己的数据，这时你可以调用该接口将数据保存下来（如果你数据比较多，或者数据比较复杂，你可以先把数据转换为**JSON**，然后再将其存到Aria的下载实体中） |
+| `Aria.download(this).load(DOWNLOAD_URL)`<br>`.getExtendField()` | 获取保存的扩展字段 |
+| `Aria.download(this).load(DOWNLOAD_URL)`<br>`.setDownloadPath(PATH).setHighestPriority();` | 将任务设置为最高优先级任务，最高优先级任务有以下特点：<br>1、在下载队列中，有且只有一个最高优先级任务<br> 2、最高优先级任务会一直存在，直到用户手动暂停或任务完成<br>3、任务调度器不会暂停最高优先级任务<br>4、用户手动暂停或任务完成后，第二次重新执行该任务，该命令将失效<br>5、如果下载队列中已经满了，则会停止队尾的任务，当高优先级任务完成后，该队尾任务将自动执行<br>6、把任务设置为最高优先级任务后，将自动执行任务，不需要重新调用start()启动任务 |
+
+### 任务实体常用数据
+* 获取当前任务的下载速度<br>
+速度参数有点特殊，需要[下载事件支持](#下载状态获取)
+``` java
+@Override public void onTaskRunning(DownloadTask task) {
+  //如果你打开了速度单位转换配置，将可以通过以下方法获取带单位的下载速度，如：1 mb/s
+  String convertSpeed = task.getConvertSpeed();
+  //如果你有自己的单位格式，可以通过以下方法获取原始byte长度
+  long speed = task.getSpeed();
+}
+```
+
+* 获取下载的文件大小、当前进度百分比</br>
+同样的，你也可以在DownloadTask对象中获取下载的文件大小
+```
+@Override public void onTaskRunning(DownloadTask task) {
+  //获取文件大小
+  long fileSize = task.getFileSize();
+  //获取单位转换后的文件大小
+  String fileSize1 = task.getConvertFileSize();
+  //当前进度百分比
+  int percent = task.getPercent();
+}
+```

 ## 混淆配置
 ```
@ -331,9 +290,11 @@ Aria.download(this).load(DOWNLOAD_URL).setExtendField(str)
 -keep class com.arialyy.aria.**{*;}
 -keep class **$$DownloadListenerProxy{ *; }
 -keep class **$$UploadListenerProxy{ *; }
+-keep class **$$DownloadGroupListenerProxy{ *; }
 -keepclasseswithmembernames class * {
    @Download.* <methods>;
    @Upload.* <methods>;
+    @DownloadGroup.* <methods>;
 }

 ```
@ -345,12 +306,11 @@ Aria.download(this).load(DOWNLOAD_URL).setExtendField(str)
 ***

 ## 后续版本开发规划
-* ~~ftp断点下载~~
-* ~~http、scoket断点上传~~
-* ~~实现上传队列调度功能~~
+* ~~代码优化~~


 ## 开发日志
+  + v_3.2.12 实现FTP多线程断点续传下载，FTP断点续传上传功能
  + v_3.2.9 修复任务组下载完成两次回掉的问题，修复又是获取不到下载状态的问题
  + v_3.2.8 修复下载超过2G大小的文件失败的问题
  + v_3.2.7 移除设置文件名的api接口，修复断开网络时出现的进度条错误的问题
@ -361,9 +321,6 @@ Aria.download(this).load(DOWNLOAD_URL).setExtendField(str)
  + v_3.1.5 优化代码结构，增加优先下载任务功能。
  + v_3.1.4 修复快速切换，暂停、恢复功能时，概率性出现的重新下载问题，添加onPre()回调，onPre()用于请求地址之前执行界面UI更新操作。
  + v_3.1.0 添加Aria配置文件，优化代码
-  + v_3.0.3 修复暂停后删除任务，闪退问题，添加删除记录的api
-  + v_3.0.2 支持30x重定向链接下载
-  + v_3.0.0 添加上传任务支持，修复一些已发现的bug

 License
 -------