RXBus

RX based bus with lifecycle based queuing support

2 years after

RXBus Release Android Arsenal

What does it do?

  • it allows you to post events to a bus
  • it allows you to subscribe to special events whereever you want
  • it allows you to queue events until an activity is resumed (to make sure views are accessable for example)
  • it allows you to queue events as soon as activity is paused and emit events as soon soon as it is resumed
  • it's very lightweight

Gradle (via JitPack.io)

  1. add jitpack to your project's build.gradle:
    repositories {
    maven { url "https://jitpack.io" }
    }
  2. add the compile statement to your module's build.gradle:
    dependencies {
    compile 'com.github.MFlisar:RXBus:0.8'
    }

Migration

If you update from version <0.5, follow this short migration guide: MIGRATION GUIDE

Usage

Content

Demo

Just check out the DemoActivity, it will show the base usage and the difference between the default and the queued RXBus

Simple usage

Just use the RXBus class and subscribe to a special event, that's it. Or use the RXBusBuilder for more flexible usage. Just like following:

// Variant 1 - create observable only:
Observable<TestEvent> simpleObservable1 = RXBus.get().observeEvent(TestEvent.class);

// Variant 2 - create observable with the BUILDER:
Observable<TestEvent> simpleObservable2 = RXBusBuilder.create(TestEvent.class).buildObservable();

// Variant 3 - subscribe with the BUILDER:
Subscription simpleSubscription1 = RXBusBuilder.create(TestEvent.class)
    .withOnNext(new Action1<TestEvent>() {
        @Override
        public void call(TestEvent event) {
            // handle event...

            // event MUST have been send with either of following:
            // RXBus.get().sendEvent(new TestEvent()); => class bound bus usage
            // RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1, true); => key bound bus usage, with sendToDefaultBusAsWell = true, which will result in that all class bound observers (like this one) retrieve this event as well
        }
    })
    .buildSubscription();
Sending an event
// Send an event to the bus - all observers that observe this class WITHOUT a key will receive this event
RXBus.get().sendEvent(new TestEvent());
// Send an event to the bus - only observers that observe the class AND key will receive this event
RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1);
// Send an event to the bus - all observers that either observe the class or the class AND key will receive this event
RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1, true);
Advanced usage - QUEUING

You can use this library to subscribe to events and only get them when your activity is resumed, so that you can be sure views are available, for example. Just like following:

Subscription queuedSubscription = RXBusBuilder.create(TestEvent.class)
    // this enables the queuing mode! Passed object must implement IRXBusQueue interface, see the demo app for an example
    .queue(rxBusQueue)
    .withOnNext(new Action1<TestEvent>() {
        @Override
        public void call(TestEvent s) {
            // activity IS resumed, you can safely update your UI for example

            // event MUST have been send with either of following:
            // RXBus.get().sendEvent(new TestEvent()); => class bound bus usage
            // RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1, true); => key bound bus usage, with sendToDefaultBusAsWell = true, which will result in that all class bound observers (like this one) retrieve this event as well
        }
    })
    .buildSubscription();
Advanced usage - KEYS

You can use this library to subscribe to events of a typ and ONLY get them when it was send to the bus with a special key (and only when your activity is resumed, as this example shows via .queue()), so that you can distinct event subscriptions of the same class based on a key (the key can be an Integer or a String). Just like following:

Subscription queuedSubscription = RXBusBuilder.create(String.class)
    // this enables the binding to the key
    .withKey(R.id.observer_key_1) // you can provide multiple keys as well
    .queue(rxBusQueue)
    .withOnNext(new Action1<String>() {
        @Override
        public void call(String s) {
            // activity IS resumed, you can safely update your UI for example

            // event MUST have been with either of those:
            // RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1); => key bound bus usage, class bound observers WON't retrieve this event as well!
            // RXBus.get().sendEvent(new TestEvent(), R.id.observer_key_1, true); => key bound bus usage, with sendToDefaultBusAsWell = true, resulting in class bound observers WILL retrieve this event as well!
        }
    })
    .buildSubscription();
Advanced usage - bus observable processor (this does not look very nice and does not follow the rx base rule of never breaking the chain, so it's likely to be removed and replaced by something better!)

Use this if you want to process the observed event before you emit it.

// for example, instead of observing a string, you observe the hash of the string
IRXBusObservableProcessor observableProcessor = new IRXBusObservableProcessor<String, Integer>()
{
    @Override
    public Observable<Integer> onObservableReady(Observable<String> observable)
    {
        // do anything with the observable and return on of the processed type in the end
        return observable.map(new Func1<String, Integer>()
        {
            @Override
            public Integer call(String s)
            {
                    return s.hashCode();
            }
        });
    }
};
RXBusBuilder.create(String.class, Integer.class, observableProcessor)
    .withOnNext(new Action1<Integer>()
    {
        @Override
        public void call(Integer integer)
        {
            // here you get the hash instead of the string
        }
    })
    .buildSubscription();
Helper class - RXSubscriptionManager

This class helps to bind subscriptions to objects and offers an easy way to unsubscribe all subscriptions that are bound to an object at once.

Subscription subscription = RXBusBuilder.create(...).buildSubscription();
RXSubscriptionManager.addSubscription(activity, subscription);

Now you only have to make sure to unsubscribe again like following:

RXSubscriptionManager.unsubscribe(activity);

This will remove ANY subscription that is bound to activity and therefore this can be used in your activity's onDestroy method to make sure ALL subscriptions are unsubscribed at once and that you don't leak the activity.

Credits

The RxValve class is from this gist: https://gist.github.com/akarnokd/1c54e5a4f64f9b1e46bdcf62b4222f08

Related Repositories

RxJava-Android-Samples

RxJava-Android-Samples

Learning RxJava for Android by example ...

kotgo

kotgo

...

XDroidMvp

XDroidMvp

轻量级的Android MVP快速开发框架 ...

NoRxJava

NoRxJava

Everything about Rxjava:Thinking like a Rxjava library creator,Why we need use R ...

Apollo

Apollo

Compile-time Event Bus by RxJava (RxBus) ...


Top Contributors

MFlisar

Releases

-   1.0 zip tar
-   0.9 zip tar
-   0.8 zip tar
-   0.7 zip tar
-   0.6 zip tar
-   0.5 zip tar
-   0.4 zip tar
-   0.3 zip tar
-   0.2 zip tar
-   0.1 zip tar