FileDownloader

Android 文件下载引擎，稳定、高效、灵活、简单易用

[![Gitter][gitter_svg]][gitter_url] [![Download][bintray_svg]][bintray_url] ![][file_downloader_svg] [![Build Status][build_status_svg]][build_status_link] ![][filedownloader_snapshot_svg]

README DOC

版本迭代日志: Change Log

英文文档: Wiki、优化建议

FileDownloader2

现在, FileDownloader2-OkDownload 已经正式发布, okdownload继承了所有FileDownloader的优点，甚至做了更多的优化以及更多的特性。

由于FileDownloader的单元测试覆盖太低，因此所有的进一步的需求以及提高都将会在okdownload上进行实现而非FileDownloader，而FileDownloader本身将只会关注于修复Bug。

特点

• 简单易用
• 单任务多线程/多连接/分块下载(并支持通过ConnectionCountAdapter定制)
• 高并发
• 灵活
• 可选择性支持: 独立/非独立进程
• 自动断点续传

需要注意

• 当下载的文件大小可能大于1.99GB(2^31-1=2_147_483_647 = 1.99GB)的时候, 请使用FileDownloadLargeFileListener而不是FileDownloadListener(同理使用getLargeFileSofarBytes()与getLargeFileTotalBytes())
• 暂停: paused, 恢复: 直接调用start，默认就是断点续传
• 引擎默认会打开避免掉帧的处理(使得在有些情况下回调(FileDownloadListener)不至于太频繁导致ui线程被ddos), 如果你希望关闭这个功能（关闭以后，所有回调会与0.1.9之前的版本一样，所有的回调会立马抛一个消息ui线程(Handler)）
• 如果没有特殊需要，直接通过配置filedownloader.properties将process.non-separate置为true，可以有效减少每次回调IPC带来的I/O。

Android 系统适配

适配 Android 8.0

从 Android 8.0 开发，后台服务的限制增强了，可以参考这里了解更多信息。 因此，自 FileDownloader 1.7.6 版本开始， Android 8.0 及之后的系统上，如果在后台启动下载服务，这个服务将会是一个前台服务，同时你会看到一个标题为 "FileDownloader" 的通知。 你可以参考这里去自定义通知的内容。

适配 Android 9.0

从 Android 9.0 (API level 28) 开始，明文请求默认被禁止，你可以在这里了解详细信息。 FileDownloader 1.7.6 已经在 demo 中处理了此问题。

根据迁移笔记，FOREGROUND_SERVICE 这个权限已经在 1.7.6 版本添加到 library 的 manifest 里面了。

欢迎提交 Pull requests

• 尽量多的英文注解。
• 每个提交尽量的细而精准。
• Commit message 遵循: AngularJS's commit message convention。

I. 效果

![][single_demo_gif] ![][chunked_demo_gif] ![][serial_tasks_demo_gif] ![][parallel_tasks_demo_gif] ![][tasks_manager_demo_gif] ![][mix_tasks_demo_gif] ![][avoid_drop_frames_1_gif] ![][avoid_drop_frames_2_gif]

II. 使用

在项目中引用:

implementation 'com.liulishuo.filedownloader:library:1.7.7'

如果是eclipse引入jar包参考: 这里

如果需要引入snapshot版本，请添加sonatype的仓库:

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 = 0; i < count; i++) {
     tasks.add(FileDownloader.getImpl().create(Constant.URLS[i]).setTag(i + 1));
}

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

// 所有任务在下载失败的时候都自动重试一次
queueSet.setAutoRetryTimes(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)说明

一般的下载回调流程:

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

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

paused / completed / error / warn

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

blockComplete -> completed

方法说明