repositories {
    maven { url "https://oss.sonatype.org/content/repositories/snapshots/" }
}

全局初始化

如果你需要注册你的定制组件，你需要在Application#onCreate中调用FileDownloader.setupOnApplicationOnCreate(application):InitCustomMaker, 否则你只需要在使用FileDownloader之前的任意时候调用FileDownloader.setup(Context)即可。

这些初始化方法都十分的简单，不会启动下载服务，一般都是在10ms内完成。

启动单任务下载

FileDownloader.getImpl().create(url)
        .setPath(path)
        .setListener(new FileDownloadListener() {
            @Override
            protected void pending(BaseDownloadTask task, int soFarBytes, int totalBytes) {
            }

            @Override
            protected void connected(BaseDownloadTask task, String etag, boolean isContinue, int soFarBytes, int totalBytes) {
            }

            @Override
            protected void progress(BaseDownloadTask task, int soFarBytes, int totalBytes) {
            }

            @Override
            protected void blockComplete(BaseDownloadTask task) {
            }

            @Override
            protected void retry(final BaseDownloadTask task, final Throwable ex, final int retryingTimes, final int soFarBytes) {
            }

            @Override
            protected void completed(BaseDownloadTask task) {
            }

            @Override
            protected void paused(BaseDownloadTask task, int soFarBytes, int totalBytes) {
            }

            @Override
            protected void error(BaseDownloadTask task, Throwable e) {
            }

            @Override
            protected void warn(BaseDownloadTask task) {
            }
        }).start();

启动多任务下载

final FileDownloadListener queueTarget = new FileDownloadListener() {
    @Override
    protected void pending(BaseDownloadTask task, int soFarBytes, int totalBytes) {
    }

    @Override
    protected void connected(BaseDownloadTask task, String etag, boolean isContinue, int soFarBytes, int totalBytes) {
    }

    @Override
    protected void progress(BaseDownloadTask task, int soFarBytes, int totalBytes) {
    }

    @Override
    protected void blockComplete(BaseDownloadTask task) {
    }

    @Override
    protected void retry(final BaseDownloadTask task, final Throwable ex, final int retryingTimes, final int soFarBytes) {
    }

    @Override
    protected void completed(BaseDownloadTask task) {
    }

    @Override
    protected void paused(BaseDownloadTask task, int soFarBytes, int totalBytes) {
    }

    @Override
    protected void error(BaseDownloadTask task, Throwable e) {
    }

    @Override
    protected void warn(BaseDownloadTask task) {
    }
};

// 第一种方式 :

//for (String url : URLS) {
//    FileDownloader.getImpl().create(url)
//            .setCallbackProgressTimes(0) // 由于是队列任务, 这里是我们假设了现在不需要每个任务都回调`FileDownloadListener#progress`, 我们只关系每个任务是否完成, 所以这里这样设置可以很有效的减少ipc.
//            .setListener(queueTarget)
//            .asInQueueTask()
//            .enqueue();
//}

//if(serial){
    // 串行执行该队列
//    FileDownloader.getImpl().start(queueTarget, true);
// }

// if(parallel){
    // 并行执行该队列
//    FileDownloader.getImpl().start(queueTarget, false);
//}

// 第二种方式:

final FileDownloadQueueSet queueSet = new FileDownloadQueueSet(downloadListener);

final List<BaseDownloadTask> tasks = new ArrayList<>();
for (int i = <span class="pl-c1">0; i < count; i++) {
     tasks.add(FileDownloader.getImpl().create(Constant<span class="pl-c1">.URLS[i]).setTag(i + <span class="pl-c1">1));
}

queueSet.disableCallbackProgressTimes(); // 由于是队列任务, 这里是我们假设了现在不需要每个任务都回调`FileDownloadListener#progress`, 我们只关系每个任务是否完成, 所以这里这样设置可以很有效的减少ipc.

// 所有任务在下载失败的时候都自动重试一次
queueSet.setAutoRetryTimes(<span class="pl-c1">1);

if (serial) {
  // 串行执行该任务队列
     queueSet.downloadSequentially(tasks);
     // 如果你的任务不是一个List，可以考虑使用下面的方式，可读性更强
//      queueSet.downloadSequentially(
//              FileDownloader.getImpl().create(url).setPath(...),
//              FileDownloader.getImpl().create(url).addHeader(...,...),
//              FileDownloader.getImpl().create(url).setPath(...)
//      );
}

if (parallel) {
  // 并行执行该任务队列
   queueSet.downloadTogether(tasks);
   // 如果你的任务不是一个List，可以考虑使用下面的方式，可读性更强
//    queueSet.downloadTogether(
//            FileDownloader.getImpl().create(url).setPath(...),
//            FileDownloader.getImpl().create(url).setPath(...),
//            FileDownloader.getImpl().create(url).setSyncCallback(true)
//    );
}

// 最后你需要主动调用start方法来启动该Queue
queueSet.start()

// 串行任务动态管理也可以使用FileDownloadSerialQueue。

全局接口说明(FileDownloader)

所有的暂停，就是停止，会释放所有资源并且停到所有相关线程，下次启动的时候默认会断点续传

定制化组件接口说明(InitCustomMaker)

• 如果你希望Okhttp作为你的网络连接组件，可以使用这个库。
• 如果你不希望FileDownloader用到任何的数据库(是用于存储任务的断点续成信息的)，只需要使用NoDatabaseImpl.java即可。

Task接口说明

监听器(FileDownloadListener)说明

一般的下载回调流程:

<code>pending -> started -> connected -> (progress <->progress) -> blockComplete -> completed
</code>

可能会遇到以下回调而直接终止整个下载过程:

<code>paused / completed / error / warn
</code>

如果检测存在已经下载完成的文件(可以通过isReusedOldFile进行决策是否是该情况)(也可以通过setForceReDownload(true)来避免该情况):

<code>blockComplete -> completed
</code>

方法说明

由于FileDownloadListener中的方法回调过快，导致掉帧?

你有两种方法可以解决这个问题

1. FileDownloader#enableAvoidDropFrame, 默认 就是开启的
2. BaseDownloadTask#setSyncCallback, 默认是false, 如果设置为true，所有的回调都会在下载线程直接同步调用而不会抛到ui线程。

FileDownloadMonitor

你可以添加一个全局监听器来进行打点或者是调试

FileDownloadMonitor.IMonitor

监听器接口类

FileDownloadUtils

FileDownloadNotificationHelper

如何快速集成Notification呢? 建议参考NotificationMinSetActivity、NotificationSampleActivity。

filedownloader.properties

如果你需要定制化FileDownloader，可以在你的项目模块的assets 目录下添加 'filedownloader.properties' 文件(如 /demo/src/main/assets/filedownloader.properties)，然后添加以下可选相关配置。

格式: keyword=value

如果你使用broadcast.completed并且接收任务完成的广播,你需要注册Action为filedownloader.intent.action.completed的广播并且使用FileDownloadBroadcastHandler来处理接收到的Intent。

III. 异常处理

所有的异常，都将在 FileDownloadListener#error(BaseDownloadTask, Throwable) 中获知。

III. 低内存情况

非下载进程(一般是UI进程):

这边的数据并不多，只是一些队列数据，用不了多少内存。

前台进程数据被回收:

如果在前台的时候这个数据都被回收了, 你的应用应该也挂了。极低概率事件。

后台进程数据被回收:

一般事件, 如果是你的下载是UI进程启动的，如果你的UI进程处于后台进程(可以理解为应用被退到后台)状态，在内存不足的情况下会被回收(回收优先级高于服务进程)，此时分两种情况:

1. 是串行队列任务，在回收掉UI进程内存以后，下载进程会继续下载完已经pending到下载进程的那个任务，而还未pending到下载进程的任务会中断下载(由于任务驱动线性执行的是在UI进程); 有损体验: 下次进入应用重启启动整个队列，会继续上次的下载。
2. 是并行队列任务，在回收掉UI进程内存以后，下载进程会继续下载所有任务(所有已经pending到下载进程的任务，由于这里的pending速度是很快的，因此几乎是点击并行下载，所有任务在很短的时间内都已经pending到下载进程了)，而UI进程由于被回收，将不会收到所有的监听; 有损体验: 下次进入应用重新启动整个队列，就会和正常的下载启动一致，收到所有情况的监听。

下载进程:

对内存有一定的占用，但是并不多，每次启动进程会根据数据的有效性进行清理冗余数据，被回收是低概率事件

由于下载不断有不同的buffer占用内存，但是由于在下载时，是活跃的服务进程，因此被回收是低概率事件(会先回收完所有空进程、后台进程(后台应用)以后，如果内存还不够，才会回收该进程)。

即使被回收，也不会有任何问题。由于我们使用的是START_STICKY(如果不希望被重启可主动调用FileDownloader#unBindService/FileDownloader#unBindServiceIfIdle)，因此在内存足够的时候，下载进程会尝试重启(系统调度)，非下载进程(一般是UI进程) 接收到下载进程的连接，会继续下载与继续接收回调，下载进程也会断点续传没有下载完的所有任务(无论并行与串行)，不会影响体验。

IV. LICENSE

<code>Copyright (c) 2015 LingoChamp Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</code>