EventBus
Simple event bus.
How to add
Gradle
Step 1. Add the JitPack repository in your root build.gradle at the end of repositories:
allprojects {
repositories {
maven { url "https://jitpack.io" }
}
}
Step 2. Add the dependency in the app's build.gradle:
dependencies {
compile 'com.github.edeqa:eventbus:3'
}
Maven
Step 1. Add the JitPack repository to your build file:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Step 2. Add the dependency:
<dependency>
<groupId>com.github.edeqa</groupId>
<artifactId>eventbus</artifactId>
<version>3</version>
</dependency>
How to use
First, create event bus:
eventBus1 = new EventBus("first");
eventBus2 = new EventBus("second");
or just using DEFAULT_NAME
:
eventBus = new EventBus();
or as a singleton:
eventBusDefault = EventBus.getOrCreate(); // uses DEFAULT_NAME
eventBus1 = EventBus.getOrCreate("first");
Make the class implementing EntityHolder
:
public class SampleHolder implements EntityHolder {
...
}
But much better is to inherit the class from AbstractEntityHolder
and implement onEvent
for handle events and make some logic.
public class SampleHolder extends AbstractEntityHolder {
@Override
public boolean onEvent(String eventName, Object eventObject) {
switch(eventName) {
case "event1":
System.out.println("EntityHolder name: " + getType());
break;
case "event2":
System.out.println("Event with argument: " + eventObject);
break;
case "event3":
case "event4":
break;
}
return true; // if returns false then chain will be interrupted
}
}
Register it in the bus:
eventBus.register(new SampleHolder());
Posting event
Post event:
eventBus.post("event1");
eventBus.post("event2", "argument2");
Post event to all registered buses:
EventBus.postAll("event3");
EventBus.postAll("event4", "argument4");
Event will be posted to all holders in the order that holders were registered.
Specific task in queue
If you want to run some specific task in the same queue as events then use post#Runnable
:
eventBus.post(new Runnable() {
@Override
public void run() {
LOGGER.severe("EventBus specific task.");
}
});
Limit events spreading
If some AbstractEntityHolder#onEvent
returns false
then next holders in the queue will not be called.
You can also limit the spreading of events using AbstractEntityHolder#events
:
@Override
public List<String> events() {
List<String> list = new ArrayList<>();
list.add("event1");
list.add("event2");
return list;
}
Events event1
and event2
will be posted only to specific holder (or holders).
Updating holder
You can update the holder without losing its position in the queue:
eventBus.update(new SampleHolder());
Runner
Methods start
, finish
and onEvent
are processing through the same Runner
. Runner
is a simple class that wraps the Runnable
into a specific mode. There are two runners predefined in the package: RUNNER_MULTI_THREAD
and RUNNER_SINGLE_THREAD
. The DEFAULT_RUNNER
is the same as the RUNNER_MULTI_THREAD
. If your environment doesn't allow to use multiple threads then accept for each event bus:
eventBus.setRunner(EventBus.RUNNER_SINGLE_THREAD);
Or, commonly:
EventBus.setMainRunner(EventBus.RUNNER_SINGLE_THREAD);
Note that EventBus.setMainRunner
overrides all previously defined runners.
Android UI specific
Some of Android tasks (i.e UI interaction) require fulfillment in the main thread. Then, set specific runner for all buses by following code:
final Handler handler = new Handler(Looper.getMainLooper());
EventBus.Runner runner = new EventBus.Runner() {
@Override
public void post(Runnable runnable) {
handler.post(runnable);
}
};
EventBus.setMainRunner(runner);
Or, separately:
eventBus1.setRunner(runner);
eventBus2.setRunner(runner);
eventBus3.setRunner(EventBus.RUNNER_SINGLE_THREAD);
Note that EventBus.setMainRunner
overrides all previously defined runners.
Troubleshooting
You can switch log details:
EventBus.LOGGING_LEVEL = Level.ALL;
Possible values: ALL
, FINE
, CONFIG
, INFO
, WARNING
, SEVERE
. Default is WARNING
.
Inspect events
Deep inspection for specific events can be set next way:
EventBus.inspect("event1");
EventBus.inspect("event2");
This will throw the stacktrace when these events happen.
Cancel inspection:
EventBus.inspect(null);
Javadoc
See the Javadoc for more details on API.
History
3 - eventBus#registerIfAbsent
2 - throwing exceptions for EntityHolder#start, EntityHolder#finish, EntityHolder#onEvent; EventBus.RUNNER_MULTI_THREAD, EventBus.RUNNER_SINGLE_THREAD; -entityHolder#setContext; -EntityHolder(Context); removed T from EntityHolder, so now it's just EntityHolder; EventBus#getOrCreateEventBus renamed to EventBus#getOrCreate
1.0 - EventBus#getEventBuses; EventBus#getEventBus; EventBus#getOrCreateEventBus; eventBus#getEventBusName; EventBus#setLoggingLevel; -EventBus#postSync; tests
0.8 - eventBus#registerOrUpdate; eventBus#unregister; javadoc
0.7 - refactoring to interface
0.6 - eventBus#postRunnable; docs
0.5 - update#holder; post#Runnable; EventBus#inspect; debug
0.4 - limit events
0.1 - initial
License
EventBus is licensed under an MIT license. See the LICENSE
file for specifics.