/ThinDownloadManager

To download files and to avoid using DOWNLOAD_WITHOUT_NOTIFICATION permission if you are using Android's DownloadManager in your apps.

Primary LanguageJavaApache License 2.0Apache-2.0

ThinDownloadManager

Thin DownloadManager is an android library primary to download files and to avoid using DOWNLOAD_WITHOUT_NOTIFICATION permission when using Android provided DownloadManager in your application.

##Why ? There are few reasons why you might want to use this library.

  • There are situations where you wanted to download a file into application's sandboxed cache or files directory where no one else can access to. DownloadManager provided by android does not have facility to download directly to application's cache or files directory (/data/data//cache/ or /data/data//files/). It can only accept destination in external SDcard as download destination. And if you are not using application's external file directory as destination i.e (setDestinationInExternalFilesDir()) you have to have android.permission.WRITE_EXTERNAL_STORAGE

Most of the times we download using Android's DownloadManager to external files directory and upon successful completion move the downloaded file to the sandboxed application's cache/file directory to avoid writing a own download manager which is a bit tedious. This library is handy in such situations.

  • No additional permissions required. Any download initiated by your application using android DownloadManager would throw a progress notification on status bar letting user know that you are downloading a file. So you end up using setVisibleInDownloadsUi(false) & having this permission android.permission.DOWNLOAD_WITHOUT_NOTIFICATION. When users install your app, they would be shown this permission and it makes them scary not to install your app because you are downloading some files without user's notification. Why give a chance of user not installing your app for this permission. You definetly need this library in this case.

  • Volley - Google recommended Networking library for android doesn't have options to download a file.

##Usuage ####DownloadStatusListener (Deprecated)

  • Provides call back option to know when the download is completed, failed and reason for failure, and to know the progress of the download.
    //Callback when download is successfully completed
    void onDownloadComplete (int id);

    //Callback if download is failed. Corresponding error code and
    //error messages are provided
    void onDownloadFailed (int id, int errorCode, String errorMessage);

    //Callback provides download progress
    void onProgress (int id, long totalBytes, long downlaodedBytes, int progress);

####DownloadStatusListenerV1

  • Provides call back option to know when the download is completed, failed and reason for failure, and to know the progress of the download. DownloadRequest is given back in the callback so that you can easily set some Object as context to download request and get the context object back from the request object.
    //Callback when download is successfully completed
    void onDownloadComplete(DownloadRequest downloadRequest);

    //Callback if download is failed. Corresponding error code and
    //error messages are provided
    void onDownloadFailed(DownloadRequest downloadRequest, int errorCode, String errorMessage);


    //Callback provides download progress
    void onProgress(DownloadRequest downloadRequest, long totalBytes, long downloadedBytes, int progress);

####DownloadRequest

  • Takes all the necessary information required for download.

  • Download URI, Destination URI.

  • Set Priority for request as HIGH or MEDIUM or LOW.

  • Takes Callback listener DownloadStatusListener

  • Use custom Http Headers for a download request

  • You can set a Retry Policy

       Uri downloadUri = Uri.parse("http://tcrn.ch/Yu1Ooo1");
       Uri destinationUri = Uri.parse(this.getExternalCacheDir().toString()+"/test.mp4");
       DownloadRequest downloadRequest = new DownloadRequest(downloadUri)
               .addCustomHeader("Auth-Token", "YourTokenApiKey")
               .setRetryPolicy(new DefaultRetryPolicy())
               .setDestinationURI(destinationUri).setPriority(DownloadRequest.Priority.HIGH)
               .setDownloadContext(downloadContextObject)//Optional
               .setDownloadListener(new DownloadStatusListener() {
                   @Override
                   public void onDownloadComplete(int id) {
    
                   }
    
                   @Override
                   public void onDownloadFailed(int id, int errorCode, String errorMessage) {
    
                   }
    
                   @Override
                   public void onProgress(int id, long totalBytes, long downlaodedBytes, int progress)) {
    
                   }
               });

####ThinDownloadManager

  • The number of threads used to perform parallel download is determined by the available processors on the device. Uses Runtime.getRuntime().availableProcessors() api.

    private ThinDownloadManager downloadManager;
    .....
    
    downloadManager = new ThinDownloadManager();
    
    ....

  * To start a download use *add( DownloadRequest request)*
   	```java
   	int downloadId = downloadManager.add(downloadRequest);
   	```

  * To cancel a particular download use *cancel(int downloadId)* by passing download id.
  	- Returns 1 if successfull cancelled.
  	- Returns -1 if supplied download id is not found.

  	```java
  	int status = downloadManager.cancel(downloadId);
  	```

  * To cancel all running requests use *cancelAll()*
  	```java
  	downloadManager.cancelAll();
  	```

  * To query for a particular download use *query(int downloadId)*

    The possible status could be
  	- STATUS_PENDING
  	- STATUS_STARTED
  	- STATUS_RUNNING

  	```java
  	int status = downloadManager.query(downloadId);
  	```
  * To release all the resources used by download manager use *release()*.

  	```java
  	downloadManager.release();
  	```


##No Permissions Required
  * Unless if you specify download destination to be in external public SDCard location.You might need *android.permission.WRITE_EXTERNAL_STORAGE* permission.

##Setup
Include below line your build.gradle:

```java
dependencies {
    compile 'com.mani:ThinDownloadManager:1.2.4'
}

Make sure you included jcenter() in your repositories section.

##Download

  • The source code of sample app code is available for you to play around and the app itself is available for download from play store :

Get it on Google Play

  • Sample app demonstrates with 4 thread pool size and download three different formats of files jpg, mp3, mp4.
  • The files are downloaded to applications sandboxed files directory. */data/data//files.

Android Arsenal

##Credits https://android.googlesource.com/platform/packages/providers/DownloadProvider/

NOTE: Android's DownloadManager has plenty of features which is not available in ThinDownloadManager. For ex. pause and continue download when network connectivity changes.So analyse your requirement thoroughly and decide which one to use.

https://www.virag.si/2015/01/publishing-gradle-android-library-to-jcenter/ Steps for uploading to bintray.

##License

 Copyright 2013 Mani Selvaraj

 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.