FileDownloader (library 1.7.2 API)

java.lang.Object
- com.liulishuo.filedownloader.FileDownloader

```
public class FileDownloader
extends Object
```
The basic entrance for FileDownloader.

See Also:

The service for FileDownloader., FileDownloadProperties

Constructor Summary

Constructors
Constructor and Description

FileDownloader()

Constructors
Constructor and Description
`FileDownloader()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addServiceConnectListener(FileDownloadConnectListener listener)` Add the listener for listening when the status of connection with the downloader service is changed.
`void`	`bindService()` Start and bind the FileDownloader service.
`void`	`bindService(Runnable runnable)` Start and bind the FileDownloader service and run `runnable` as soon as the binding is successful.
`boolean`	`clear(int id, String targetFilePath)` Clear the data with the provided `id`.
`void`	`clearAllTaskData()` Clear all data in the filedownloader database.
`BaseDownloadTask`	`create(String url)` Create a download task.
`static void`	`disableAvoidDropFrame()` Disable avoiding missing screen frames, let all callbacks in `FileDownloadListener` can be invoked at once when it achieve.
`static void`	`enableAvoidDropFrame()` Avoid missing screen frames, this leads to all callbacks in `FileDownloadListener` do not be invoked at once when it has already achieved to ensure callbacks don't be too frequent
`static FileDownloader`	`getImpl()`
`long`	`getSoFar(int downloadId)` Get downloaded bytes so far by the downloadId.
`byte`	`getStatus(int id, String path)`
`byte`	`getStatus(String url, String path)`
`byte`	`getStatusIgnoreCompleted(int id)`
`long`	`getTotal(int id)` Get the total bytes of the target file for the task with the {code id}.
`static void`	`init(Context context)` Deprecated. please use `setup(Context)` instead.
`static void`	`init(Context context, DownloadMgrInitialParams.InitCustomMaker maker)` Deprecated. please using `setupOnApplicationOnCreate(Application)` instead.
`FileDownloadLine`	`insureServiceBind()` If the FileDownloader service is not started and connected, FileDownloader will try to start it and try to bind with it.
`FileDownloadLineAsync`	`insureServiceBindAsync()` If the FileDownloader service is not started and connected will return `false` immediately, and meanwhile FileDownloader will try to start FileDownloader service and try to bind with it, and after it is bound successfully the request you invoke in `FileDownloadLineAsync` will be executed automatically.
`static boolean`	`isEnabledAvoidDropFrame()`
`boolean`	`isServiceConnected()`
`void`	`pause(FileDownloadListener listener)` Pause the download queue by the same `listener`.
`int`	`pause(int id)` Pause downloading tasks with the `id`.
`void`	`pauseAll()` Pause all tasks running in FileDownloader.
`void`	`removeServiceConnectListener(FileDownloadConnectListener listener)` Remove the listener for listening when the status of connection with the downloader service is changed.
`int`	`replaceListener(int id, FileDownloadListener listener)` Find the running task by `id`, and replace its listener width the new one `listener`.
`int`	`replaceListener(String url, FileDownloadListener listener)` Find the running task by `url` and default path, and replace its listener with the new one `listener`.
`int`	`replaceListener(String url, String path, FileDownloadListener listener)` Find the running task by `url` and `path`, and replace its listener with the new one `listener`.
`static void`	`setGlobalHandleSubPackageSize(int packageSize)` For avoiding missing screen frames.
`static void`	`setGlobalPost2UIInterval(int intervalMillisecond)` For avoiding missing screen frames.
`boolean`	`setMaxNetworkThreadCount(int count)` Set the maximum count of the network thread, what is the number of simultaneous downloads in FileDownloader.
`boolean`	`setTaskCompleted(List<FileDownloadTaskAtom> taskAtomList)` Deprecated. If you invoked this method, please remove the code directly feel free, it doesn't need any longer. In new mechanism(filedownloader 0.3.3 or higher), FileDownloader doesn't store completed tasks in Database anymore, because all downloading files have temp a file name.
`boolean`	`setTaskCompleted(String url, String path, long totalBytes)` Deprecated. If you invoked this method, please remove the code directly feel free, it doesn't need any longer. In new mechanism(filedownloader 0.3.3 or higher), FileDownloader doesn't store completed tasks in Database anymore, because all downloading files have temp a file name.
`static void`	`setup(Context context)` You can invoke this method anytime before you using the FileDownloader.
`static DownloadMgrInitialParams.InitCustomMaker`	`setupOnApplicationOnCreate(Application application)` Using this method to setup the FileDownloader only you want to register your own customize components for Filedownloader, otherwise just using `setup(Context)` instead.
`boolean`	`start(FileDownloadListener listener, boolean isSerial)` Start the download queue by the same listener.
`void`	`startForeground(int id, Notification notification)` Start the `notification` with the `id`.
`void`	`stopForeground(boolean removeNotification)` Remove the downloader service from the foreground state, allowing it to be killed if more memory is needed.
`void`	`unBindService()` Unbind and stop the downloader service.
`boolean`	`unBindServiceIfIdle()` Unbind and stop the downloader service when there is no task running in the FileDownloader.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FileDownloader
```
public FileDownloader()
```
- Method Detail
  - setup
```
public static void setup(Context context)
```
    You can invoke this method anytime before you using the FileDownloader.
    If you want to register your own customize components please using setupOnApplicationOnCreate(Application) on the Application.onCreate() instead.
    
    Parameters:
    
    context - the context of Application or Activity etc..
  - setupOnApplicationOnCreate
```
public static DownloadMgrInitialParams.InitCustomMaker setupOnApplicationOnCreate(Application application)
```
    Using this method to setup the FileDownloader only you want to register your own customize components for Filedownloader, otherwise just using setup(Context) instead.
    Please invoke this method on the Application.onCreate() because of the customize components must be assigned before FileDownloader is running.
    Such as:
    class MyApplication extends Application { ... public void onCreate() { ... FileDownloader.setupOnApplicationOnCreate(this) .idGenerator(new MyIdGenerator()) .database(new MyDatabase()) ... .commit(); ... } ... }
    
    Parameters:
    
    application - the application.
    
    Returns:
    
    the customize components maker.
  - init
```
public static void init(Context context)
```
    Deprecated. please use setup(Context) instead.
  - init
```
public static void init(Context context,
                        DownloadMgrInitialParams.InitCustomMaker maker)
```
    Deprecated. please using setupOnApplicationOnCreate(Application) instead.
  - getImpl
```
public static FileDownloader getImpl()
```
  - setGlobalPost2UIInterval
```
public static void setGlobalPost2UIInterval(int intervalMillisecond)
```
    For avoiding missing screen frames.
    This mechanism is used for avoid methods in FileDownloadListener is invoked too frequent in result the system missing screen frames in the main thread.
    We wrap the message package which size is FileDownloadMessageStation.SUB_PACKAGE_SIZE and post the package to the main thread with the interval: FileDownloadMessageStation.INTERVAL milliseconds.
    The default interval is 10ms, if intervalMillisecond equal to or less than 0, each callback in FileDownloadListener will be posted to the main thread immediately.
    
    Parameters:
    
    intervalMillisecond - The time interval between posting two message packages.
    
    See Also:
    
    enableAvoidDropFrame(), disableAvoidDropFrame(), setGlobalHandleSubPackageSize(int)
  - setGlobalHandleSubPackageSize
```
public static void setGlobalHandleSubPackageSize(int packageSize)
```
    For avoiding missing screen frames.
    This mechanism is used for avoid methods in FileDownloadListener is invoked too frequent in result the system missing screen frames in the main thread.
    We wrap the message package which size is FileDownloadMessageStation.SUB_PACKAGE_SIZE and post the package to the main thread with the interval: FileDownloadMessageStation.INTERVAL milliseconds.
    The default count of message for a message package is 5.
    
    Parameters:
    
    packageSize - The count of message for a message package.
    
    See Also:
    
    setGlobalPost2UIInterval(int)
  - enableAvoidDropFrame
```
public static void enableAvoidDropFrame()
```
    Avoid missing screen frames, this leads to all callbacks in FileDownloadListener do not be invoked at once when it has already achieved to ensure callbacks don't be too frequent
    
    See Also:
    
    isEnabledAvoidDropFrame(), setGlobalPost2UIInterval(int)
  - disableAvoidDropFrame
```
public static void disableAvoidDropFrame()
```
    Disable avoiding missing screen frames, let all callbacks in FileDownloadListener can be invoked at once when it achieve.
    
    See Also:
    
    isEnabledAvoidDropFrame(), setGlobalPost2UIInterval(int)
  - isEnabledAvoidDropFrame
```
public static boolean isEnabledAvoidDropFrame()
```
    Returns:
    
    true if enabled the function of avoiding missing screen frames.
    
    See Also:
    
    enableAvoidDropFrame(), disableAvoidDropFrame(), setGlobalPost2UIInterval(int)
  - create
```
public BaseDownloadTask create(String url)
```
    Create a download task.
  - start
```
public boolean start(FileDownloadListener listener,
                     boolean isSerial)
```
    Start the download queue by the same listener.
    
    Parameters:
    
    listener - Used to assemble tasks which is bound by the same listener
    
    isSerial - Whether start tasks one by one rather than parallel.
    
    Returns:
    
    true if start tasks successfully.
  - pause
```
public void pause(FileDownloadListener listener)
```
    Pause the download queue by the same listener.
    
    Parameters:
    
    listener - the listener.
    
    See Also:
    
    pause(int)
  - pauseAll
```
public void pauseAll()
```
    Pause all tasks running in FileDownloader.
  - pause
```
public int pause(int id)
```
    Pause downloading tasks with the id.
    
    Parameters:
    
    id - the id .
    
    Returns:
    
    The size of tasks has been paused.
    
    See Also:
    
    pause(FileDownloadListener)
  - clear
```
public boolean clear(int id,
                     String targetFilePath)
```
    Clear the data with the provided id. Normally used to deleting the data in filedownloader database, when it is paused or in downloading status. If you want to re-download it clearly.
    Note: YOU NO NEED to clear the data when it is already completed downloading because the data would be deleted when it completed downloading automatically by FileDownloader.
    If there are tasks with the id in downloading, will be paused first; If delete the data with the id in the filedownloader database successfully, will try to delete its intermediate downloading file and downloaded file.
    
    Parameters:
    
    id - the download id.
    
    targetFilePath - the target path.
    
    Returns:
    
    true if the data with the id in filedownloader database was deleted, and tasks with the id was paused; false otherwise.
  - clearAllTaskData
```
public void clearAllTaskData()
```
    Clear all data in the filedownloader database.
    Note: Normally, YOU NO NEED to clearAllTaskData manually, because the FileDownloader will maintain those data to ensure only if the data available for resuming can be kept automatically.
    
    See Also:
    
    clear(int, String)
  - getSoFar
```
public long getSoFar(int downloadId)
```
    Get downloaded bytes so far by the downloadId.
  - getTotal
```
public long getTotal(int id)
```
    Get the total bytes of the target file for the task with the {code id}.
  - getStatusIgnoreCompleted
```
public byte getStatusIgnoreCompleted(int id)
```
    Parameters:
    
    id - The downloadId.
    
    Returns:
    
    The downloading status without cover the completed status (if completed you will receive FileDownloadStatus.INVALID_STATUS ).
    
    See Also:
    
    getStatus(String, String), getStatus(int, String)
  - getStatus
```
public byte getStatus(String url,
                      String path)
```
    Parameters:
    
    url - The downloading URL.
    
    path - The downloading file's path.
    
    Returns:
    
    The downloading status.
    
    See Also:
    
    getStatus(int, String), getStatusIgnoreCompleted(int)
  - getStatus
```
public byte getStatus(int id,
                      String path)
```
    Parameters:
    
    id - The downloadId.
    
    path - The target file path.
    
    Returns:
    
    the downloading status.
    
    See Also:
    
    FileDownloadStatus, getStatus(String, String), getStatusIgnoreCompleted(int)
  - replaceListener
```
public int replaceListener(String url,
                           FileDownloadListener listener)
```
    Find the running task by url and default path, and replace its listener with the new one listener.
    
    Returns:
    
    The target task's DownloadId, if not exist target task, and replace failed, will be 0
    
    See Also:
    
    replaceListener(int, FileDownloadListener), replaceListener(String, String, FileDownloadListener)
  - replaceListener
```
public int replaceListener(String url,
                           String path,
                           FileDownloadListener listener)
```
    Find the running task by url and path, and replace its listener with the new one listener.
    
    Returns:
    
    The target task's DownloadId, if not exist target task, and replace failed, will be 0
    
    See Also:
    
    replaceListener(String, FileDownloadListener), replaceListener(int, FileDownloadListener)
  - replaceListener
```
public int replaceListener(int id,
                           FileDownloadListener listener)
```
    Find the running task by id, and replace its listener width the new one listener.
    
    Returns:
    
    The target task's DownloadId, if not exist target task, and replace failed, will be 0
    
    See Also:
    
    replaceListener(String, FileDownloadListener), replaceListener(String, String, FileDownloadListener)
  - bindService
```
public void bindService()
```
    Start and bind the FileDownloader service.
    Tips: The FileDownloader service will start and bind automatically when any task is request to start.
    
    See Also:
    
    bindService(Runnable), isServiceConnected(), addServiceConnectListener(FileDownloadConnectListener)
  - bindService
```
public void bindService(Runnable runnable)
```
    Start and bind the FileDownloader service and run runnable as soon as the binding is successful.
    Tips: The FileDownloader service will start and bind automatically when any task is request to start.
    
    Parameters:
    
    runnable - the command will be executed as soon as the FileDownloader Service is successfully bound.
    
    See Also:
    
    isServiceConnected(), bindService(), addServiceConnectListener(FileDownloadConnectListener)
  - unBindService
```
public void unBindService()
```
    Unbind and stop the downloader service.
  - unBindServiceIfIdle
```
public boolean unBindServiceIfIdle()
```
    Unbind and stop the downloader service when there is no task running in the FileDownloader.
    
    Returns:
    
    true if unbind and stop the downloader service successfully, false there are some tasks running in the FileDownloader.
  - isServiceConnected
```
public boolean isServiceConnected()
```
    Returns:
    
    true if the downloader service has been started and connected.
  - addServiceConnectListener
```
public void addServiceConnectListener(FileDownloadConnectListener listener)
```
    Add the listener for listening when the status of connection with the downloader service is changed.
    
    Parameters:
    
    listener - The downloader service connection listener.
    
    See Also:
    
    removeServiceConnectListener(FileDownloadConnectListener)
  - removeServiceConnectListener
```
public void removeServiceConnectListener(FileDownloadConnectListener listener)
```
    Remove the listener for listening when the status of connection with the downloader service is changed.
    
    Parameters:
    
    listener - The downloader service connection listener.
    
    See Also:
    
    addServiceConnectListener(FileDownloadConnectListener)
  - startForeground
```
public void startForeground(int id,
                            Notification notification)
```
    Start the notification with the id. This will let the downloader service change to a foreground service.
    In foreground status, will save the FileDownloader alive, even user kill the application from recent apps.
    Make FileDownloader service run in the foreground, supplying the ongoing notification to be shown to the user while in this state. By default FileDownloader services are background, meaning that if the system needs to kill them to reclaim more memory (such as to display a large page in a web browser), they can be killed without too much harm. You can set this flag if killing your service would be disruptive to the user, such as if your service is performing background downloading, so the user would notice if their app stopped downloading.
    
    Parameters:
    
    id - The identifier for this notification as per NotificationManager.notify(int, Notification); must not be 0.
    
    notification - The notification to be displayed.
    
    See Also:
    
    stopForeground(boolean)
  - stopForeground
```
public void stopForeground(boolean removeNotification)
```
    Remove the downloader service from the foreground state, allowing it to be killed if more memory is needed.
    
    Parameters:
    
    removeNotification - true if the notification previously provided to startForeground(int, android.app.Notification) will be removed. false it will be remained until a later call removes it (or the service is destroyed).
    
    See Also:
    
    startForeground(int, Notification)
  - setTaskCompleted
```
public boolean setTaskCompleted(String url,
                                String path,
                                long totalBytes)
```
    Deprecated. If you invoked this method, please remove the code directly feel free, it doesn't need any longer. In new mechanism(filedownloader 0.3.3 or higher), FileDownloader doesn't store completed tasks in Database anymore, because all downloading files have temp a file name.
    
    Parameters:
    
    url - The url of the completed task.
    
    path - The absolute path of the completed task's save file.
    
    totalBytes - The content-length of the completed task, the length of the file in the path must be equal to this value.
    
    Returns:
    
    Whether is successful to set the task completed. If the path not exist will be false; If the length of the file in path is not equal to totalBytes will be false; If the task with url and path is downloading will be false. Otherwise will be true.
    
    See Also:
    
    Recommend used to telling the FileDownloader Engine that the task with the {@code url} and the {@code path} has already completed downloading, in case of your task has already downloaded by other ways(not by FileDownloader Engine), and after success to set the task completed, FileDownloader will check the task with {@code url} and the {@code path} whether completed by {@code totalBytes}.
    Otherwise, If FileDownloader Engine isn't know your task's status, whatever your task with the {@code url} and the {@code path} has already downloaded in other way, FileDownloader Engine will ignore the exist file and redownload it, because FileDownloader Engine don't know the exist file whether it is valid., setTaskCompleted(List)
  - setTaskCompleted
```
public boolean setTaskCompleted(List<FileDownloadTaskAtom> taskAtomList)
```
    Deprecated. If you invoked this method, please remove the code directly feel free, it doesn't need any longer. In new mechanism(filedownloader 0.3.3 or higher), FileDownloader doesn't store completed tasks in Database anymore, because all downloading files have temp a file name.
    
    Recommend used to telling the FileDownloader Engine that a bulk of tasks have already downloaded by other ways(not by the FileDownloader Engine).
    The FileDownloader Engine need to know the status of completed, because if you want to download any tasks, FileDownloader Engine judges whether the task need downloads or not according its status which existed in DB.
    
    Parameters:
    
    taskAtomList - The bulk of tasks.
    
    Returns:
    
    Whether is successful to update all tasks' status to the Filedownloader Engine. If one task atom among them is not match the Rules in FileDownloadMgr#obtainCompletedTaskShelfModel(String, String, long) will receive false, and non of them would be updated to DB.
    
    See Also:
    
    setTaskCompleted(String, String, long)
  - setMaxNetworkThreadCount
```
public boolean setMaxNetworkThreadCount(int count)
```
    Set the maximum count of the network thread, what is the number of simultaneous downloads in FileDownloader.
    
    Parameters:
    
    count - the number of simultaneous downloads, scope: [1, 12].
    
    Returns:
    
    whether is successful to set the max network thread count. If there are any actively executing tasks in FileDownloader, you will receive a warn priority log int the logcat and this operation would be failed.
  - insureServiceBind
```
public FileDownloadLine insureServiceBind()
```
    If the FileDownloader service is not started and connected, FileDownloader will try to start it and try to bind with it. The current thread will also be blocked until the FileDownloader service is started and a connection is established, and then the request you invoke in FileDownloadLine will be executed.
    If the FileDownloader service has been started and connected, the request you invoke in FileDownloadLine will be executed immediately.
    Note: FileDownloader can not block the main thread, because the system is also call-backs the ServiceConnection.onServiceConnected(ComponentName, IBinder) method in the main thread.
    Tips: The FileDownloader service will start and bind automatically when any task is request to start.
    
    See Also:
    
    FileDownloadLine, bindService(Runnable)
  - insureServiceBindAsync
```
public FileDownloadLineAsync insureServiceBindAsync()
```
    If the FileDownloader service is not started and connected will return false immediately, and meanwhile FileDownloader will try to start FileDownloader service and try to bind with it, and after it is bound successfully the request you invoke in FileDownloadLineAsync will be executed automatically.
    If the FileDownloader service has been started and connected, the request you invoke in FileDownloadLineAsync will be executed immediately.
    
    See Also:
    
    FileDownloadLineAsync, bindService(Runnable)

Class FileDownloader

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FileDownloader

Method Detail

setup

setupOnApplicationOnCreate

init

init

getImpl

setGlobalPost2UIInterval

setGlobalHandleSubPackageSize

enableAvoidDropFrame

disableAvoidDropFrame

isEnabledAvoidDropFrame

create

start

pause

pauseAll

pause

clear

clearAllTaskData

getSoFar

getTotal

getStatusIgnoreCompleted

getStatus

getStatus

replaceListener

replaceListener

replaceListener

bindService

bindService

unBindService

unBindServiceIfIdle

isServiceConnected

addServiceConnectListener

removeServiceConnectListener

startForeground

stopForeground

setTaskCompleted

setTaskCompleted

setMaxNetworkThreadCount

insureServiceBind

insureServiceBindAsync