DOCSEARCHbyAlgolia
Submit Docs

HermesEventBus Documentation

repository·master·Indexed 23 days ago

https://github.com/xiaofei-it/hermeseventbus

An Android library that extends GreenRobot's EventBus to support Inter-Process Communication (IPC). It enables posting and receiving events between different processes within a single app or between distinct applications. Compatible with EventBus 3.0.0, it utilizes a main process and sub-process architecture to route events across process boundaries.

Tokens
1K
Snippets
1
Records
4
Agent score
32%

What's inside HermesEventBus

  1. How HermesEventBus works

    master

    HermesEventBus is an Inter-Process Communication (IPC) library for Android that extends the functionality of GreenRobot's EventBus. While standard EventBus only supports communication within a single process, HermesEventBus enables event posting between multiple processes or even distinct apps.

    Architecture Model

    The library designates one process as the main process and all others as sub-processes. When an event is posted, the following flow occurs:

    1. The event is sent via the Hermes IPC framework to the main process.
    2. The main process uses standard EventBus to post the event locally.
    3. The main process sends the event via Hermes to all registered sub-processes.
    4. Each sub-process uses EventBus to post the event locally within itself.

    To prevent concurrency issues like deadlocks and race conditions, the library utilizes the Concurrent-Utils library.

  2. Setup HermesEventBus within a single app (multi-process)

    master

    To use HermesEventBus for communication between different processes within the same application, follow these steps:

    1. Add Dependency

    Add the following to your build.gradle file:

    dependencies {
    compile 'xiaofei.library:hermes-eventbus:0.3.0'
}

    Or via Maven:

    <dependency>
  <groupId>xiaofei.library</groupId>
  <artifactId>hermes-eventbus</artifactId>
  <version>0.3.0</version>
  <type>pom</type>
</dependency>

    2. Initialize in Application

    In your Application.onCreate() method, initialize the bus:

    HermesEventBus.getDefault().init(this);

    3. Register and Post

    Replace standard EventBus calls with HermesEventBus. You can use it for both intra-process and inter-process communication:

    HermesEventBus.getDefault().register(this);
HermesEventBus.getDefault().post(new Event());

    4. Cleanup

    When a process no longer needs to participate in event bus communication, call destroy() to avoid android.os.DeadObjectException:

    HermesEventBus.getDefault().destroy();

  3. Setup HermesEventBus between distinct apps

    master

    To enable communication between two different Android applications, follow these steps:

    1. Add Dependency

    Add the hermes-eventbus:0.3.0 dependency to the build.gradle of every participating app.

    2. Configure the Main App

    Choose one app to act as the main app (preferably a long-lived one). In its AndroidManifest.xml, register the following service:

    <service android:name="xiaofei.library.hermes.HermesService$HermesService0"/>

    In the main app's Application.onCreate(), initialize it:

    HermesEventBus.getDefault().init(this);

    3. Configure Sub-Apps

    In the Application.onCreate() of all other participating apps, connect to the main app using its package name:

    HermesEventBus.getDefault().connectApp(this, "com.example.mainapp");

    4. Requirements for Events

    For events to be successfully transmitted between apps:

    • The event classes must have the same package name.
    • The event classes must have the same class name.
    • The receiving methods must have the same signatures.
    • Important: You must add your event classes and their @Subscribe methods to your Proguard rules to prevent obfuscation from breaking the IPC.

    5. Usage and Cleanup

    Use HermesEventBus.getDefault().register(this) and .post(event) as usual. When an app no longer needs to communicate, call HermesEventBus.getDefault().destroy() to prevent android.os.DeadObjectException.

  4. Subscribe to events using @Subscribe

    master

    HermesEventBus follows the EventBus 3.0.0 API. To receive events, you must annotate your receiving method with @Subscribe. Simply naming a method onEventXXX is insufficient.

    Note: This library is specifically compatible with EventBus 3.0.0. If you are using an earlier version of EventBus, you must update your code to ensure events are received correctly.

    @Subscribe(threadMode = ThreadMode.MAIN)
public void showText(String text) {
    textView.setText(text);
}