Skip to content

Flexible background processing library for Android made with respect to the app lifecycle

License

Notifications You must be signed in to change notification settings

Dzhey/DroidWorker

Repository files navigation

Download

DroidWorker

Flexible background processing library for Android made with respect to the app lifecycle

Features

  • Serial or Asynchronous kind of execution for your Jobs (and more)
  • Simple Job lifecycle to better structure your Job code and handle errors
  • Cancellation available at any time
  • Pause/Resume feature
  • Single entry point to access and manage submitted Jobs using JobSelectors
  • Prioritization to neatly influence execution order
  • ForkJoinJob allowing to reuse and combine previously written Jobs in different ways
  • Activity/Fragment bindings with annotation-styled subscription: you determine when it's time to subscribe or remove subscription for your component
  • Job parameteres injection powered by code generation and annotations
  • Job reset feature combined with builder-styled initializer to reuse Job instance

Hello World

Most-common Job use case is Loader replacement, but you can use Job for any purpose (networking, database operations, data processing, etc)

UI code

public class DemoUserViewFragment extends BaseFragment {

      // Tag to associate with the Job
      private static final String TAG_LOAD_JOB = "DemoUserViewFragment_User_Loader";

      ...

      @Override
      public void onResume() {
        super.onResume();

        // requestLoad() will start our Job only if there are
        // no any running or queued Job instance with specified tag
        requestLoad(TAG_LOAD_JOB);
      }

      @Override
      public Job onCreateJob(String attachTag) {
        // attachTag will be TAG_LOAD_JOB
        // you may switch between tags to distinct separate load
        // requests and return different Jobs when needed

        return new LoadUserJob()
                .setup()
                .configure(DemoUserViewFragment.captureExtras()
                        .setUserId(mUserId)
                        .apply())
                .getJob();
      }

      @OnJobSuccess(DemoUserViewFragment.class)
      public void onUserLoaded(LoadJobResult<User> result) {
        final User user = result.getData();
        // do everything you need to display user data
      }

      @OnJobFailure(DemoUserViewFragment.class)
      public void onUserLoadFailure(JobEvent event) {
        // display error (event argument is optional and it can contain detailed error info)
      }
}

Please note that some common code including event subscription is moved to the base class (see demo sample for details).

Job code

public class LoadUserJob extends LoadJob {

    @JobExtra
    long mUserId;

    ...

    @Override
    protected void onPreExecute() throws Exception {
        super.onPreExecute();

        // LoadUserJobJobExtras is generated from Job annotations
        // From this point mUserId will contain actual value
        // previously specified in onCreateJob() callback
        LoadUserJobJobExtras.injectExtras(this);

        if (mUserId == 0) {
            // It is safe to throw exception from any callback method
            // UI will receive regular failure event
            throw new IllegalArgumentException("user id is not specified");
        }
    }

    @Override
    protected LoadJobResult<User> performLoad() throws Exception {
        final Response<User> response = mRestClient.getUser(mUserId).execute();

        if (!response.isSuccessful()) {
            // return regular load failure event
            return LoadJobResult.loadFailure();
        }

        return new LoadJobResult<>(response.body());
      }
}

Setup

dependencies {
    // main dependency
    compile 'com.github.dzhey:droidworker:0.3.1'
    
    // annotations are optional unless you use @JobExtra or @JobFlag
    compile 'com.github.dzhey:droidworker-annotations:0.3.1'
    apt 'com.github.dzhey:droidworker-annotations-compiler:0.3.1'
    
    // optional RxJava wrappers (see demo)
    compile 'com.github.dzhey:droidworker-rxbindings:0.3.1'
}

For details on using the apt scope see the android-apt project.

ProGuard

Add these lines to your ProGuard configuration:

-keepclassmembers class * {
    @com.be.android.library.worker.annotations.* *;
}
-keepclasseswithmembers public class **Extras { *; }

Debug

run command ./gradlew --no-daemon -Dorg.gradle.debug=true :demo:clean :demo:compileDebugJavaWithJavac add remote debug jvm configuration to run configurations, run it to debug

License

MIT License

Copyright (c) 2016 Eugene Byzov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

About

Flexible background processing library for Android made with respect to the app lifecycle

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages