LightCycle

Self-contained components that helps break logic out of Activity and Fragment

Introduction

LightCycle is an Android library that helps break logic out of Activity and Fragment classes into small, self-contained components called LightCycles.

Fields that are annotated @LightCycle and implement the LightCycle API within a LightCycleActivity or LightCycleFragment will be bound to that Activity or Fragment lifecycle.

LightCycle lets self-contained classes respond to Android’s lifecycle events. This supports composition over inheritance and promotes components that follow the single responsibility principle. We believe it helps us write more readable, maintainable and testable code. It works particularly well alongside dependency injection.

● Activity and Fragment classes:
    ○ Inflate layouts and configure Android specifics
    ○ Declare LightCycles
● A LightCycle component is responsible for an isolated chunk of logic (such as presentation, tracking etc.)

A LightCycle doesn't know about other LightCycles. There is no guarantee for ordering when multiple LightCycles receive the same lifecycle callback.

Usage

Do your view initialization in your Activity

public class MyActivity extends LightCycleAppCompatActivity {
    @LightCycle MyController controller = new MyController();

    @Override
    protected void setActivityContentView() {
        setContentView(R.layout.main);
    }
}

And put your logic inside your LightCycle

public class MyController extends DefaultActivityLightCycle {

    @Override
    public void onPause(MyActivity activity) {
        // MyActivity was paused
    }

    [...]

    @Override
    public void onResume(MyActivity activity) {
        // MyActivity was resumed
    }
}

Examples

Basic

"Real World"

Documentation

LightCycle

There are 3 types of LightCycles - the API is comparable to the ActivityLifecycleCallbacks from the Android SDK:

ActivityLightCycle
FragmentLightCycle
SupportFragmentLightCycle

For convenience, default implementations are provided:

DefaultActivityLightCycle
DefaultFragmentLightCycle
DefaultSupportFragmentLightCycle

Dispatcher

This dispatches an Activity or Fragment lifecycle callback to attached LightCycles. The API defines a single bind method. See the LightCycleDispatcher interface.

Built-in dispatchers

Three types of dispatchers are provided:

ActivityLightCycleDispatcher
FragmentLightCycleDispatcher
SupportFragmentLightCycleDispatcher

Note: these built-in classes are both dispatchers and LightCycles, meaning that you can nest LightCycles.

Do your view initialization in your activity as usual

public class MyActivity extends LightCycleAppCompatActivity {
    @LightCycle MyController controller = new MyController();

    @Override
    protected void setActivityContentView() {
        setContentView(R.layout.main);
    }
}

Extend your logic class to matching Dispatcher class based on the type (Activity with ActivityLightCycleDispatcher, Fragment with FragmentLightCycleDispatcher, etc) and then you can nest another LightCycles too inside your Dispatcher

public class MyController extends ActivityLightCycleDispatcher {
    @LightCycle MySubController1 controller = new MyController1();
    @LightCycle MySubController2 controller = new MyController2();

    @Override
    public void onCreate(Bundle savedInstanceState) {
        [...] // <- specific init
        super.onCreate(savedInstanceState) // <- call super to dispatch.
    }
}
Provided base dispatcher classes

The following base dispatcher classes are provided so far:

LightCycleActivity
LightCycleAppCompatActivity
LightCycleActionBarActivity
LightCycleFragment
LightCycleSupportFragment
LightCycleSupportDialogFragment
LightCyclePreferenceFragmentCompat

Known Limitation

Creating your own base dispatcher class

⚠ Please, read carefully the following steps (item 2 in particular). ⚠

To add LightCycles to your MyBaseActivity, your Activity must:

● Implement the LightCycleDispatcher interface. Note: The processor needs to know the exact type being dispatched, so if your base activity is templated then the activities inheriting from it must explicitly implements LightCycleDispatcher> (for more details, refer to this issue)
● Dispatch all the lifecycle methods
● Bind fields annotated @LightCycle with LightCycles.bind(this)

The same technique applies for Fragment.

Example

public class MyBaseActivity extends Activity implements LightCycleDispatcher> {

    private final ActivityLightCycleDispatcher lightCycleDispatcher;

    @Override
    public void bind(ActivityLightCycle lightCycle) {
        lightCycleDispatcher.bind(lightCycle);
    }

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        LightCycles.bind(this);
        lightCycleDispatcher.onCreate((MyBaseActivity) this, savedInstanceState);
    }

    [...]

    @Override
    protected void onDestroy() {
        lightCycleDispatcher.onDestroy((MyBaseActivity) this);
        super.onDestroy();
    }
}

See LightCycleActionBarActivity and LightCycleSupportFragment for example

Download

You can check full source code of LightCycle on GitHub.

Gradle

dependencies {
  compile 'com.soundcloud.lightcycle:lightcycle-lib:(insert latest version)'
  annotationProcessor 'com.soundcloud.lightcycle:lightcycle-processor:(insert latest version)'
}

Or if you're using a version of the Android gradle plugin below 2.2.0

buildscript {
  dependencies {
    classpath 'com.neenbedankt.gradle.plugins:android-apt:1.8'
  }
}

apply plugin: 'com.neenbedankt.android-apt'

ext.lightCycleVersion=

  dependencies {
  compile 'com.soundcloud.lightcycle:lightcycle-lib:(insert latest version)'
  apt 'com.soundcloud.lightcycle:lightcycle-processor:(insert latest version)'
}

License

Copyright 2016 SoundCloud Limited

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.