JarCastingRxBus: a Java EventBus using ReactiveX
Download
The distribution is hosted on Bintray. To include the package in your projects, you can add the jCenter repository.
Gradle
Add jCenter to your repositories block:
repositories {
jcenter()
}
and add the project to the dependencies block in your build.gradle:
dependencies {
compile 'com.cookingfox:rxbus-eventbus-java:0.1.1'
}
Maven
Add jCenter to your repositories in pom.xml or settings.xml:
<repositories>
<repository>
<id>jcenter</id>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
and add the project declaration to your pom.xml:
<dependency>
<groupId>com.cookingfox</groupId>
<artifactId>rxbus-eventbus-java</artifactId>
<version>0.1.1</version>
</dependency>
Features
- Simple methods for subscribing to and dispatching events
- Helper method for converting ("forwarding") an existing stream to the event bus
- Based on interfaces to make custom implementations and mocking possible.
Usage
Create an RxBus instance
The default implementation is called DefaultRxBus:
RxBus rxBus = new DefaultRxBus();
The DefaultRxBus uses a serialized PublishSubject, but you can also provide your own Subject implementation:
RxBus rxBus = new DefaultRxBus(BehaviorSubject.create());
Emit (dispatch / post) an event
rxBus.emit(new MyEvent());
Aliases: RxBus#dispatch(), RxBus#post().
Subscribing to events
You can subscribe to all events that are posted on the RxBus:
rxBus.subscribe(observer);
But you're probably only interested in events of a certain type:
rxBus.subscribe(MyEvent.class, observer);
RxBus#subscribe() copies the Observable#subscribe() methods and, likewise, returns a Subscription reference.
Observing event streams
Directly subscribing to events is nice, but the cool thing about Rx is its operators! To get an Observable instance, use RxBus.observe().
You can observe all events that are posted on the RxBus:
rxBus.observe().subscribe(observer);
But you're probably only interested in events of a certain type:
rxBus.observe(MyEvent.class).subscribe(observer);
Alias: RxBus#on().
'Forwarding' observable streams to events
A common pattern when working with an EventBus is observing one stream and emitting 'global' events in response. This could be achieved as follows:
Observable<String> exampleStream = Observable.just("example");
exampleStream.map(new Func1<String, ExampleStringEvent>() {
@Override
public ExampleStringEvent call(String value) {
return new ExampleStringEvent(value);
}
}).subscribe(new Action1<ExampleStringEvent>() {
@Override
public void call(ExampleStringEvent event) {
rxBus.emit(event);
}
});
To apply this pattern more comfortably, RxBus provides the RxBus#forward() methods:
rxBus.forward(exampleStream, new Func1<String, ExampleStringEvent>() {
@Override
public ExampleStringEvent call(String value) {
return new ExampleStringEvent(value);
}
});
This becomes even more readable when using a lambda:
rxBus.forward(exampleStream, value -> new ExampleStringEvent(value));
Or even a method reference:
rxBus.forward(exampleStream, ExampleStringEvent::new);
F.A.Q.
Why does this exist? Aren't there enough other EventBus implementations using Rx?
Yes, there are many other implementations available, but I wanted a simple RxJava library that
- is not just targeted at Android
- does not rely on extending a custom Event class
- is available on jCenter and / or Maven Central
- is not part of some huge library
- does not rely on extra dependencies
- is easy to extend and use.
Copyright and license
Code and documentation copyright 2016 Cooking Fox. Code released under the MIT license.