Handle
Handler-based Eventbus for Android
Features
- No Reflection during runtime
- Reusable Event-handlers
- Sticky events with controllable lifetime
- android.os.Handler underneath
- Extremely fast and lightweight
- Ability to generate event handlers with
apt
Basic usage
compile 'ru.noties.handle:core:x.x.x'
Introduction
The Handle library revolves around event handlers. To start using Handle one must create an implementation of the ru.noties.handle.IEventHandler
public interface IEventHandler {
void onEvent(Object event);
boolean isEventRegistered(Class<?> cl);
}
Then, as usual
Handle.register(IEventHandler);
Handle.unregister(IEventHandler);
Simple Posting
As long as Handle hides android.os.Handler
posting could be done with these methods:
Handle.post(Object); // simple
Handle.postDelayed(Object, long); // with delay
Handle.postAtTime(Object, SystemUptimeMillis + delay); // posting at specific time in the future
Also, there is a possibility to cancel every enqueued simple event:
Handle.cancel(Object)
Sticky posting
Handle gives an ability to post sticky events and control its' lifetime
Handle.postSticky(Object); // simple with default lifetime (currently 30 seconds)
Handle.postSticky(Object, long validMillis); // with custom lifetime
Every posted sticky event is intended to be cancelled at some point, that's why after sticky event is recieved one should cancel its delivery
Handle.cancelSticky(Object);
If sticky event is not cancelled after it's specified duration of lifetime ru.noties.handle.events.StickyEventNotUsedEvent
is fired, which gives an ability to cancel it.
If you wish to cancel all pending events (including sticky) call:
Handle.cancelAll();
Special events
ru.noties.handle.events.StickyEventNotUsedEvent
is fired when StickyEvent is not cancelled after its lifetimeru.noties.handle.events.OnDispatchExceptionEvent
is fired when an Exception was thrown during event deliveryru.noties.handle.events.NoEventHandlerEvent
is fired when posted Event has no IEventHandler which can receive it
Code generation (apt)
Handle also comes with processor
and annotations
modules
apt 'ru.noties.handle:processor:x.x.x'
compile 'ru.noties.handle:annotations:x.x.x'
Annotate the class, which would receive events with @ru.noties.handle.annotations.EventHandler
, for example (from sample application)
@EventHandler({ OnDispatchExceptionEvent.class, NoEventHandlerEvent.class, StickyEventNotUsedEvent.class})
public class BaseActivity extends Activity { }
After build
there will be a generated IEventHandler in the package of annotated class with the name *EventHandler
(continued from sample application):
private final IEventHandler mHandler = new BaseActivityEventHandler() {
@Override
public void onEvent(OnDispatchExceptionEvent event) {
Debug.e(event.getThrowable(), "Handler: %s, event: %s", event.getEventHandler(), event.getEvent());
}
@Override
public void onEvent(NoEventHandlerEvent event) {
Debug.i("noEventHandler: %s", event.getEvent());
}
@Override
public void onEvent(StickyEventNotUsedEvent event) {
final Object sticky = event.getStickyEvent();
Debug.i("sticky no used, removing, sticky: %s", sticky);
Handle.cancelSticky(sticky);
}
};
License
Copyright 2015 Dimitry Ivanov (mail@dimitryivanov.ru)
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.