Skip to content

Latest commit

 

History

History
254 lines (209 loc) · 11.5 KB

README.md

File metadata and controls

254 lines (209 loc) · 11.5 KB

file-downloader

FileDownloader, a powerful http/https file download tool, I am to make downloading http/https file easily on Android.

中文说明文档

Features

  • Multi task at same time, Broken-point download, Auto retry, Support download large file bigger than 2G, Powerful to deal with exceptions, download files CRUD and so on.

Captures

  • image
  • image

Quick start

  • step 1. add in dependencies in your module's build.gradle
compile 'org.wlf:FileDownloader:0.3.2'

for eclipse users, jars here: FileDownloader-0.3.2.jar, FileDownloader-0.3.2-sources.jar

  • step 2. init FileDownloader in your application's onCreate()
// 1.create FileDownloadConfiguration.Builder
Builder builder = new FileDownloadConfiguration.Builder(this);

// 2.config FileDownloadConfiguration.Builder
builder.configFileDownloadDir(Environment.getExternalStorageDirectory().getAbsolutePath() + File.separator +
        "FileDownloader"); // config the download path
// allow 3 download tasks at the same time, if not config, default is 2
builder.configDownloadTaskSize(3);
// config retry download times when failed, if not config, default is 0
builder.configRetryDownloadTimes(5);
// enable debug mode, if not config, default is false
builder.configDebugMode(true);
// config connect timeout, if not config, default is 15s
builder.configConnectTimeout(25000); // 25s

// 3.init FileDownloader with the configuration
FileDownloadConfiguration configuration = builder.build(); // build FileDownloadConfiguration with the builder
FileDownloader.init(configuration);
  • step 3. register listeners

-register a DownloadStatusListener(may be at the time the fragment or activity's onCreate called, you can ignore this if your app do not care the download progress, if you want to use in android service, see Use FileDownloader in Service)

private OnFileDownloadStatusListener mOnFileDownloadStatusListener = new OnSimpleFileDownloadStatusListener() {
    @Override
    public void onFileDownloadStatusRetrying(DownloadFileInfo downloadFileInfo, int retryTimes) {
        // retrying download when failed once, the retryTimes is the current trying times
    }
    @Override
    public void onFileDownloadStatusWaiting(DownloadFileInfo downloadFileInfo) {
        // waiting for download(wait for other tasks paused, or FileDownloader is busy for other operations)
    }
    @Override
    public void onFileDownloadStatusPreparing(DownloadFileInfo downloadFileInfo) {
        // preparing(connecting)
    }
    @Override
    public void onFileDownloadStatusPrepared(DownloadFileInfo downloadFileInfo) {
        // prepared(connected)
    }
    @Override
    public void onFileDownloadStatusDownloading(DownloadFileInfo downloadFileInfo, float downloadSpeed, long
            remainingTime) {
        // downloading, the downloadSpeed with KB/s unit, the remainingTime with seconds unit
    }
    @Override
    public void onFileDownloadStatusPaused(DownloadFileInfo downloadFileInfo) {
        // download paused
    }
    @Override
    public void onFileDownloadStatusCompleted(DownloadFileInfo downloadFileInfo) {
        // download completed(the url file has been finished)
    }
    @Override
    public void onFileDownloadStatusFailed(String url, DownloadFileInfo downloadFileInfo, FileDownloadStatusFailReason failReason) {
        // error occur, see failReason for details, some of the failReason you must concern

        String failType = failReason.getType();
        String failUrl = failReason.getUrl();// or failUrl = url, both url and failReason.getUrl() are the same

        if(FileDownloadStatusFailReason.TYPE_URL_ILLEGAL.equals(failType)){
            // the url error when downloading file with failUrl
        }else if(FileDownloadStatusFailReason.TYPE_STORAGE_SPACE_IS_FULL.equals(failType)){
            // storage space is full when downloading file with failUrl
        }else if(FileDownloadStatusFailReason.TYPE_NETWORK_DENIED.equals(failType)){
            // network access denied when downloading file with failUrl
        }else if(FileDownloadStatusFailReason.TYPE_NETWORK_TIMEOUT.equals(failType)){
            // connect timeout when downloading file with failUrl
        }else{
            // more....
        }

        // exception details
        Throwable failCause = failReason.getCause();// or failReason.getOriginalCause()

        // also you can see the exception message
        String failMsg = failReason.getMessage();// or failReason.getOriginalCause().getMessage()
    }
};
FileDownloader.registerDownloadStatusListener(mOnFileDownloadStatusListener);

-register a DownloadFileChangeListener if you care any change of the download file in db

private OnDownloadFileChangeListener mOnDownloadFileChangeListener = new OnDownloadFileChangeListener() {
    @Override
    public void onDownloadFileCreated(DownloadFileInfo downloadFileInfo) {
        // a new download file created, may be you need to sync your own data storage status, such as add a record in your own database
    }
    @Override
    public void onDownloadFileUpdated(DownloadFileInfo downloadFileInfo, Type type) {
        // a download file updated, may be you need to sync your own data storage status, such as update a record in your own database
    }
    @Override
    public void onDownloadFileDeleted(DownloadFileInfo downloadFileInfo) {
        // a download file deleted, may be you need to sync your own data storage status, such as delete a record in your own database
    }
};
FileDownloader.registerDownloadFileChangeListener(mOnDownloadFileChangeListener);

the difference between DownloadStatusListener and DownloadFileChangeListener is, DownloadStatusListener concerns the download progress, and DownloadFileChangeListener concerns the data change

  • step 4. start to download and operate the url files(the simple use of FileDownloader APIs)

-create a new download

FileDownloader.start(url);// start a new download if not download yet, or continue download if it start download before, it will auto Broken-point if the server supported

-or create a custom new download

FileDownloader.detect(url, new OnDetectBigUrlFileListener() {
    @Override
    public void onDetectNewDownloadFile(String url, String fileName, String saveDir, long fileSize) {
        // here to change to custom fileName, saveDir if needed
        FileDownloader.createAndStart(url, newFileDir, newFileName);
    }
    @Override
    public void onDetectUrlFileExist(String url) {
        // continue to download
        FileDownloader.start(url);
    }
    @Override
    public void onDetectUrlFileFailed(String url, DetectBigUrlFileFailReason failReason) {
        // error occur, see failReason for details
    }
});

-pause downloads

FileDownloader.pause(url);// pause single
FileDownloader.pause(urls);// pause multi
FileDownloader.pauseAll();// pause all

-continue a paused download

FileDownloader.start(url);// continue a paused download, it will auto Broken-point if the server supported

-move download files to new dir path

FileDownloader.move(url, newDirPath, mOnMoveDownloadFileListener);// move single file
FileDownloader.move(urls, newDirPath, mOnMoveDownloadFilesListener);// move multi files

-delete download files

FileDownloader.delete(url, true, mOnDeleteDownloadFileListener);// delete single file
FileDownloader.delete(urls, true, mOnDeleteDownloadFilesListener);// delete multi files

-rename a download file

FileDownloader.rename(url, newName, true, mOnRenameDownloadFileListener);
  • step 5. unregister listeners

-unregister the DownloadStatusListener(may be at the time the fragment or activity's onDestroy called)

FileDownloader.unregisterDownloadStatusListener(mOnFileDownloadStatusListener);

-unregister the DownloadFileChangeListener

FileDownloader.unregisterDownloadFileChangeListener(mOnDownloadFileChangeListener);

API docs


Version change log


Upgrade to latest version help

  • 0.2.X --> 0.3.X

-replace FileDownloader.detect(String, OnDetectUrlFileListener) with FileDownloader.detect(String, OnDetectBigUrlFileListener) for supporting large file bigger than 2G to detect recommended.

-replace DownloadFileInfo.getFileSize() with DownloadFileInfo.getFileSizeLong(), and also replace DownloadFileInfo.getDownloadedSize() with DownloadFileInfo.getDownloadedSizeLong() for supporting large file bigger than 2G to detect recommended.

-replace FileDownloader.registerDownloadStatusListener(OnFileDownloadStatusListener) with FileDownloader.registerDownloadStatusListener(OnSimpleFileDownloadStatusListener or OnRetryableFileDownloadStatusListener) for better experience.

-do not forget to do unregisterDownloadStatusListener(OnFileDownloadStatusListener) and unregisterDownloadFileChangeListener(OnDownloadFileChangeListener) if your registered then, because the listeners may cause memory overflow if you never unregister then.

-replace all FailReason classes started with On by those ones started with non-On, eg. OnFileDownloadStatusFailReason -->FileDownloadStatusFailReason.

  • 0.1.X --> 0.3.X

-replace class FileDownloadManager with new class FileDownloader, also replace all methods in the FileDownloadManager with new ones recommended.

-do steps in 0.2.X --> 0.3.X


Design of FileDownloader


Code Style, follow Google Android Code Style for Contributors, contributors are required to follow the rules


Supported system version: API 8 and above(Android 2.2+)


FAQ


LICENSE

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.