{"id":13710185,"url":"https://github.com/path/android-priority-jobqueue","last_synced_at":"2025-05-15T01:09:17.925Z","repository":{"id":7928526,"uuid":"9316799","full_name":"path/android-priority-jobqueue","owner":"path","description":"A Job Queue specifically written for Android to easily schedule jobs (tasks) that run in the background, improving UX and application stability.","archived":false,"fork":false,"pushed_at":"2022-02-24T12:15:03.000Z","size":13597,"stargazers_count":2401,"open_issues_count":34,"forks_count":377,"subscribers_count":167,"default_branch":"master","last_synced_at":"2025-04-13T23:53:52.025Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/path.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-09T08:43:00.000Z","updated_at":"2025-04-02T08:21:37.000Z","dependencies_parsed_at":"2022-09-15T21:42:30.043Z","dependency_job_id":null,"html_url":"https://github.com/path/android-priority-jobqueue","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/path%2Fandroid-priority-jobqueue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/path%2Fandroid-priority-jobqueue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/path%2Fandroid-priority-jobqueue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/path%2Fandroid-priority-jobqueue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/path","download_url":"https://codeload.github.com/path/android-priority-jobqueue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254043,"owners_count":22039792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T23:00:52.837Z","updated_at":"2025-05-15T01:09:12.915Z","avatar_url":"https://github.com/path.png","language":"Java","funding_links":[],"categories":["Index","[Java](#java)","Java","库","Background Processing","Libraries","Uncategorized"],"sub_categories":["Background Processing","[](https://github.com/JStumpp/awesome-android/blob/master/readme.md#other)其他","Other","Uncategorized"],"readme":"### Development in this repository is stopped. Future development continues on https://github.com/yigit/android-priority-jobqueue\n==========================\n\n![logo](http://downloads.path.com/logo.png)\n\nAndroid Priority Job Queue (Job Manager)\n==========================\n\nPriority Job Queue is an implementation of a [Job Queue](http://en.wikipedia.org/wiki/Job_queue) specifically written for Android to easily schedule jobs (tasks) that run in the background, improving UX and application stability.\n\nIt is written primarily with [flexibility][10] \u0026 [functionality][11] in mind. This is an ongoing project, which we will continue to add stability and performance improvements.\n\n  - [Why ?](#why-)\n   - [The Problem](#the-problem)\n   - [Our Solution](#our-solution)\n  - [Show me the code](#show-me-the-code)\n  - [What's happening under the hood?](#under-the-hood)\n  - [Advantages](#advantages)\n  - [Getting Started](#getting-started)\n  - [Version History](#version-history)\n  - [Building](#building)\n   - [Running Tests](#running-tests)\n  - [wiki][9]\n  - [Dependencies](#dependencies)\n  - [License](#license)\n\n\n### Why ?\n#### The Problem\nAlmost every application does work in a background thread. These \"background tasks\" are expected to keep the application responsive and robust, especially during unfavorable situations (e.g. limited network connectivity). In Android applications, there are several ways to implement background work:\n\n * **Async Task:** Using an async task is the simplest approach, but it is tightly coupled with the activity lifecycle. If the activity dies (or is re-created), any ongoing async task will become wasted cycles or otherwise create unexpected behavior upon returning to the main thread. In addition, it is a terrible idea to drop a response from a network request just because a user rotated his/her phone.\n * **Loaders:** Loaders are a better option, as they recover themselves after a configuration change. On the other hand, they are designed to load data from disk and are not well suited for long-running network requests.\n * **Service with a Thread Pool:** Using a service is a much better solution, as it de-couples business logic from your UI. However, you will need a thread pool (e.g. ThreadPoolExecutor) to process requests in parallel, broadcast events to update the UI, and write additional code to persist queued requests to disk. As your application grows, the number of background operations grows, which force you to consider task prioritization and often-complicated concurrency problems.\n\n#### Our Solution\nJob Queue provides you a nice framework to do all of the above and more. You define your background tasks as [Jobs][11] and enqueue them to your [JobManager][10] instance. Job Manager will take care of prioritization, persistence, load balancing, delaying, network control, grouping etc. It also provides a nice lifecycle for your jobs to provide a better, consistent user experience.\n\nAlthough not required, it is most useful when used with an event bus. It also supports dependency injection.\n\n* Job Queue was inspired by a [Google I/O 2010 talk on REST client applications][8].\n\n### Show me the code\n\nSince a code example is worth thousands of documentation pages, here it is.\n\nFile: [PostTweetJob.java](https://github.com/path/android-priority-jobqueue/blob/master/examples/twitter/TwitterClient/src/com/path/android/jobqueue/examples/twitter/jobs/PostTweetJob.java)\n``` java\n// A job to send a tweet\npublic class PostTweetJob extends Job {\n    public static final int PRIORITY = 1;\n    private String text;\n    public PostTweetJob(String text) {\n        // This job requires network connectivity,\n        // and should be persisted in case the application exits before job is completed.\n        super(new Params(PRIORITY).requireNetwork().persist());\n    }\n    @Override\n    public void onAdded() {\n        // Job has been saved to disk.\n        // This is a good place to dispatch a UI event to indicate the job will eventually run.\n        // In this example, it would be good to update the UI with the newly posted tweet.\n    }\n    @Override\n    public void onRun() throws Throwable {\n        // Job logic goes here. In this example, the network call to post to Twitter is done here.\n        webservice.postTweet(text);\n    }\n    @Override\n    protected boolean shouldReRunOnThrowable(Throwable throwable) {\n        // An error occurred in onRun.\n        // Return value determines whether this job should retry running (true) or abort (false).\n    }\n    @Override\n    protected void onCancel() {\n        // Job has exceeded retry attempts or shouldReRunOnThrowable() has returned false.\n    }\n}\n\n\n```\n\nFile: [TweetActivity.java](https://github.com/path/android-priority-jobqueue/blob/master/examples/twitter/TwitterClient/src/com/path/android/jobqueue/examples/twitter/SampleTwitterClient.java#L53)\n``` java\n//...\npublic void onSendClick() {\n    final String status = editText.getText().toString();\n    if(status.trim().length() \u003e 0) {\n      jobManager.addJobInBackground(new PostTweetJob(status));\n      editText.setText(\"\");\n    }\n}\n...\n```\n\n\nThat's it. :) Job Manager allows you to enjoy:\n\n* No network calls in activity-bound async tasks\n* No serialization mess for important requests\n* No \"manual\" implementation of network connectivity checks or retry logic\n\n### Under the hood\n* When user clicked the send button, `onSendClick()` was called, which creates a `PostTweetJob` and adds it to Job Queue for execution.\nIt runs on a background thread because Job Queue will make a disk access to persist the job.\n\n* Right after `PostTweetJob` is synchronized to disk, Job Queue calls `DependencyInjector` (if provided) which will [inject fields](http://en.wikipedia.org/wiki/Dependency_injection) into our job instance.\nAt `PostTweetJob.onAdded()` callback, we saved `PostTweetJob` to disk. Since there has been no network access up to this point, the time between clicking the send button and reaching `onAdded()` is within fracions of a second. This allows the implementation of `onAdded()` to inform UI to display the newly sent tweet almost instantly, creating a \"fast\" user experience. Beware, `onAdded()` is called on the thread job was added.\n\n* When it's time for `PostTweetJob` to run, Job Queue will call `onRun()` (and it will only be called if there is an active network connection, as dictated at the job's constructor).\nBy default, Job Queue uses a simple connection utility that checks `ConnectivityManager` (ensure you have `ACCESS_NETWORK_STATE` permission in your manifest). You can provide a [custom implementation][1] which can\nadd additional checks (e.g. your server stability). You should also provide a [`NetworkUtil`][1] which can notify Job Queue when network\nis recovered so that Job Queue will avoid a busy loop and decrease # of consumers(default configuration does it for you).\n\n* Job Queue will keep calling `onRun()` until it succeeds (or reaches a retry limit). If `onRun()` throws an exception,\nJob Queue will call `shouldReRunOnThrowable()` to allow you to handle the exception and decide whether to retry job execution or abort.\n\n* If all retry attempts fail (or when `shouldReRunOnThrowable()` returns false), Job Queue will call `onCancel()` to allow you to clean\nyour database, inform the user, etc.\n\n### Advantages\n* It is very easy to de-couple application logic from your activites, making your code more robust, easy to refactor, and easy to **test**.\n* You don't have to deal with `AsyncTask` lifecycles. This is true assuming you use an event bus to update your UI (you should).\nAt Path, we use [greenrobot's EventBus](https://github.com/greenrobot/EventBus); however, you can also go with your favorite. (e.g. [Square's Otto] (https://github.com/square/otto))\n* Job Queue takes care of prioritizing jobs, checking network connection, running them in parallel, etc. Job prioritization is especially indispensable when you have a resource-heavy app like ours.\n* You can delay jobs. This is helpful in cases like sending a GCM token to your server. It is very common to acquire a GCM token and send it to your server when a user logs in to your app, but you don't want it to interfere with critical network operations (e.g. fetching user-facing content).\n* You can group jobs to ensure their serial execution, if necessary. For example, assume you have a messaging client and your user sent a bunch of messages when their phone had no network coverage. When creating these `SendMessageToNetwork` jobs, you can group them by conversation ID. Through this approach, messages in the same conversation will send in the order they were enqueued, while messages between different conversations are still sent in parallel. This lets you effortlessly maximize network utilization and ensure data integrity.\n* By default, Job Queue monitors network connectivity (so you don't need to worry about it). When a device is operating offline, jobs that require the network won't run until connectivity is restored. You can even provide a custom [`NetworkUtil`][1] if you need custom logic (e.g. you can create another instance of Job Queue which runs only if there is a wireless connection).\n* It is unit tested and mostly documented. You can check our [code coverage report][3] and [Javadoc][4].\n\n\n### Getting Started\nWe distribute artifacts through maven central repository.\n\nGradle: `compile 'com.path:android-priority-jobqueue:1.1.2'`\n\nMaven:\n\n``` xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.path\u003c/groupId\u003e\n    \u003cartifactId\u003eandroid-priority-jobqueue\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYou can also [download][5] library jar, sources and javadoc from Maven Central.\n\nWe highly recommend checking how you can configure job manager and individual jobs.\n* [Configure job manager][10]\n* [Configure individual jobs][11]\n* [Review sample app][6]\n* [Review sample configuration][7]\n\n### Version History\n  - 1.1.2 (Feb 18, 2014)\n   - Report exceptions to logger if addInBackground fails. (#31)\n  - 1.1.1 (Feb 8, 2014)\n   - Fixed an important bug (#35) where jobs in the same group may run in parallel if many of them become available at the same time while multiple consumer threads are waiting for a new job. \n  - 1.1 (Jan 30, 2014)\n   - Job Status query API (#18)\n   - Fixed a stackoverflow bug when network status changes after a long time. (#21) \n  - 1.0 (Jan 14, 2014):\n   - Added [parameterized][12] constructor for Job for more readable code.\n   - Deprecated `BaseJob` in favor of a more complete `Job` class.\n  - 0.9.9 (Dec 16, 2013):\n   - First public release.\n\n\n### [Wiki][9]\n\n### Dependencies\n- Job Queue does not depend on any other libraries other than Android SDK.\n- For testing, we use:\n- - [Junit 4](http://junit.org/) ([license](https://github.com/junit-team/junit/blob/master/LICENSE.txt))\n- - [Robolectric](http://robolectric.org/) ([license](https://github.com/robolectric/robolectric/blob/master/LICENSE.txt))\n- - [Fest Util](http://easytesting.org/) ([license](http://www.apache.org/licenses/LICENSE-2.0))\n- - [Hamcrest](https://code.google.com/p/hamcrest/) ([license](http://opensource.org/licenses/BSD-3-Clause))\n- For code coverage report, we use:\n- - [Cobertura](http://cobertura.github.io/cobertura/) ([license](https://github.com/cobertura/cobertura/blob/master/LICENSE.txt/))\n- Sample Twitter client uses:\n- - [Twitter4j](http://twitter4j.org/en)\n- - [EventBus](https://github.com/greenrobot/EventBus)\n- - [Path's fork of greenDAO](https://github.com/path/greenDAO) . ([original repo](https://github.com/greenrobot/greenDAO))\n\n### Building\nWe are in the process of moving build system from ant to gradle. Right now, you can build with gradle but if you want to run tests, you'll need ant.\n\n* Clone the repo\n* `\u003e cd jobqueue`\n* `\u003e ant clean build-jar`\n*\nThis will create a jar file under _release_ folder.\n\n#### Running Tests\n* \u003e `cd jobqueue`\n* \u003e `ant clean test`\n\n\n## License\n\nAndroid Priority Jobqueue is made available under the [MIT license](http://opensource.org/licenses/MIT):\n\n\u003cpre\u003e\nThe MIT License (MIT)\n\nCopyright (c) 2013 Path, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\u003c/pre\u003e\n\n\n[1]: https://github.com/path/android-priority-jobqueue/blob/master/jobqueue/src/com/path/android/jobqueue/network/NetworkUtil.java\n[2]: https://github.com/path/android-priority-jobqueue/blob/master/jobqueue/src/com/path/android/jobqueue/network/NetworkEventProvider.java\n[3]: http://path.github.io/android-priority-jobqueue/coverage-report/index.html\n[4]: http://path.github.io/android-priority-jobqueue/javadoc/index.html\n[5]: http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22android-priority-jobqueue%22\n[6]: https://github.com/path/android-priority-jobqueue/tree/master/examples\n[7]: https://github.com/path/android-priority-jobqueue/blob/master/examples/twitter/TwitterClient/src/com/path/android/jobqueue/examples/twitter/TwitterApplication.java#L26\n[8]: http://www.youtube.com/watch?v=xHXn3Kg2IQE\n[9]: https://github.com/path/android-priority-jobqueue/wiki\n[10]: https://github.com/path/android-priority-jobqueue/wiki/Job-Manager-Configuration\n[11]: https://github.com/path/android-priority-jobqueue/wiki/Job-Configuration\n[12]: https://github.com/path/android-priority-jobqueue/blob/master/jobqueue/src/com/path/android/jobqueue/Params.java\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpath%2Fandroid-priority-jobqueue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpath%2Fandroid-priority-jobqueue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpath%2Fandroid-priority-jobqueue/lists"}