EventBus

https://greenrobot.org/eventbus/documentation
Admin
EventBus is an open-source library by greenrobot for Android and Java that simplifies event...
Tokens:14,589
Snippets:84
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### greenDAO - How to Get Started

Source: https://greenrobot.org/eventbus/documentation/index

Guides users through the initial setup of greenDAO, including adding the Gradle plugin, defining entities, and generating the DAOs and model classes.

```java
// build.gradle (app level)
apply plugin: 'greenrobot'

// Define your entity
@Entity
public class User {
    @Id
    private Long id;
    private String name;
    // ... getters and setters ...
}
```

--------------------------------

### EventBus - How to Get Started

Source: https://greenrobot.org/eventbus/documentation/index

Provides instructions on how to integrate and start using the EventBus library in your Android or Java project. Covers basic setup and usage patterns.

```java
EventBus.getDefault().register(this);
// ...
EventBus.getDefault().post(new MessageEvent("Hello EventBus!"));
// ...
@Subscribe(threadMode = ThreadMode.MAIN) public void onMessageEvent(MessageEvent event) {
    System.out.println("Received event: " + event.message);
}
```

--------------------------------

### EventBus Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Provides access to EventBus documentation, including getting started guides, delivery threads, configuration options, sticky events, priorities, event cancellation, subscriber index, ProGuard, AsyncExecutor, and FAQs.

```java
EventBus Documentation:
  - How to get started
  - Delivery Threads (ThreadMode)
  - Configuration
  - Sticky Events
  - Priorities and Event Cancellation
  - Subscriber Index
  - ProGuard
  - AsyncExecutor
  - FAQ
  - Javadoc (API Reference)
```

--------------------------------

### EventBus Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/proguard

Provides links to various sections of the EventBus documentation, covering getting started, delivery threads, configuration, sticky events, priorities, subscriber index, ProGuard, AsyncExecutor, and FAQs.

```markdown
- [EventBus](https://greenrobot.org/eventbus/)
  * [Features](https://greenrobot.org/eventbus/features/)
  * [Documentation](https://greenrobot.org/eventbus/documentation/)
    * [How to get started](https://greenrobot.org/eventbus/documentation/how-to-get-started/)
    * [Delivery Threads (ThreadMode)](https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode/)
    * [Configuration](https://greenrobot.org/eventbus/documentation/configuration/)
    * [Sticky Events](https://greenrobot.org/eventbus/documentation/configuration/sticky-events/)
    * [Priorities and Event Cancellation](https://greenrobot.org/eventbus/documentation/priorities-and-event-cancellation/)
    * [Subscriber Index](https://greenrobot.org/eventbus/documentation/subscriber-index/)
    * [ProGuard](https://greenrobot.org/eventbus/documentation/proguard/)
    * [AsyncExecutor](https://greenrobot.org/eventbus/documentation/asyncexecutor/)
    * [FAQ](https://greenrobot.org/eventbus/documentation/faq/)
    * [](https://greenrobot.org/files/eventbus/javadoc/current/)
  * [License](https://greenrobot.org/eventbus/license/)
  * [Changelog](https://greenrobot.org/eventbus/changelog/)
```

--------------------------------

### greenDAO Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/proguard

Links to the comprehensive documentation for greenDAO, including ObjectBox compatibility, updating to greenDAO 3, getting started, entity modeling, sessions, queries, joins, relations, custom types, database encryption, and FAQs.

```markdown
* [greenDAO](https://greenrobot.org/greendao/)
    * [Features](https://greenrobot.org/greendao/features/)
    * [Documentation](https://greenrobot.org/greendao/documentation/)
      * [ObjectBox DaoCompat](https://greenrobot.org/greendao/documentation/objectbox-compat/)
      * [greenDAO 3](https://greenrobot.org/greendao/documentation/updating-to-greendao-3-and-annotations/)
      * [How to get started](https://greenrobot.org/greendao/documentation/how-to-get-started/)
      * [Introduction](https://greenrobot.org/greendao/documentation/introduction/)
      * [Modelling entities](https://greenrobot.org/greendao/documentation/modelling-entities/)
      * [Sessions](https://greenrobot.org/greendao/documentation/sessions/)
      * [Queries](https://greenrobot.org/greendao/documentation/queries/)
      * [Joins](https://greenrobot.org/greendao/documentation/joins/)
      * [Relations](https://greenrobot.org/greendao/documentation/relations/)
      * [Custom Types](https://greenrobot.org/greendao/documentation/custom-types/)
      * [Database Encryption](https://greenrobot.org/greendao/documentation/database-encryption/)
      * [Technical FAQ](https://greenrobot.org/greendao/documentation/technical-faq/)
      * [Non-technical FAQ](https://greenrobot.org/greendao/documentation/faq/)
      * [JavaDoc (API Reference)](https://greenrobot.org/greendao/documentation/javadoc/)
    * [Changelog](https://greenrobot.org/greendao/changelog/)
```

--------------------------------

### greenDAO Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Offers comprehensive documentation for greenDAO, including ObjectBox DaoCompat, updates to greenDAO 3, getting started, entity modeling, sessions, queries, joins, relations, custom types, database encryption, and technical/non-technical FAQs.

```java
greenDAO Documentation:
  - ObjectBox DaoCompat
  - greenDAO 3 Updates
  - How to get started
  - Introduction
  - Modelling entities
  - Sessions
  - Queries
  - Joins
  - Relations
  - Custom Types
  - Database Encryption
  - Technical FAQ
  - Non-technical FAQ
  - JavaDoc (API Reference)
```

--------------------------------

### EventBus Default Instance with Index

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Shows how to install the EventBus with a generated index as the default instance. This allows subsequent calls to EventBus.getDefault() to return the configured EventBus instance.

```java
EventBus.builder().addIndex(new MyEventBusIndex()).installDefaultEventBus(); // Now the default instance uses the given index. Use it like this: EventBus eventBus = EventBus.getDefault();
```

--------------------------------

### AsyncExecutor Execution Example

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Demonstrates how to create an AsyncExecutor instance and execute a RunnableEx task. The RunnableEx can throw exceptions, which AsyncExecutor catches and posts as ThrowableFailureEvents.

```java
AsyncExecutor.create().execute( new AsyncExecutor.RunnableEx() { @Override public void run() throws LoginException { // No need to catch any Exception (here: LoginException) remote.login(); EventBus.getDefault().postSticky(new LoggedInEvent()); } } );
```

--------------------------------

### Configure EventBus to throw subscriber exceptions

Source: https://greenrobot.org/eventbus/documentation/configuration

This example shows how to configure EventBus to throw exceptions directly from subscriber methods. By setting throwSubscriberException to true, any exceptions thrown by subscribers will propagate.

```java
EventBus eventBus = EventBus.builder().throwSubscriberException(true).build();
```

--------------------------------

### EventBus Subscriber for LoggedInEvent

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

An example of an EventBus subscriber method that handles LoggedInEvent, typically posted from a background task executed by AsyncExecutor.

```java
@Subscribe(threadMode = ThreadMode.MAIN) public void handleLoginEvent(LoggedInEvent event) { // do something }
```

--------------------------------

### EventBus Subscriber for ThrowableFailureEvent

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

An example of an EventBus subscriber method that handles ThrowableFailureEvent, which is posted by AsyncExecutor when a background task throws an exception.

```java
@Subscribe(threadMode = ThreadMode.MAIN) public void handleFailureEvent(ThrowableFailureEvent event) { // do something }
```

--------------------------------

### EventBus POSTING ThreadMode Example

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

Demonstrates how to use the POSTING ThreadMode for an event handler. This is the default mode where subscribers are called in the same thread that posts the event. It's recommended for quick tasks to avoid blocking the posting thread.

```java
import org.greenrobot.eventbus.Subscribe;
import org.greenrobot.eventbus.ThreadMode;

// ... other imports and class definition

@Subscribe(threadMode = ThreadMode.POSTING)
public void onMessage(MessageEvent event) {
    log(event.message);
}
```

```java
// Called in the same thread (default)
// ThreadMode is optional here
@Subscribe(threadMode=ThreadMode.POSTING) public void onMessage(MessageEvent event) {
    log(event.message);
}
```

--------------------------------

### ASYNC ThreadMode Example

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

Demonstrates an event handler method annotated with @Subscribe and configured to use ThreadMode.ASYNC. This handler will be executed in a separate thread, making it suitable for potentially time-consuming operations like network requests.

```java
@Subscribe(threadMode = ThreadMode.ASYNC) public void onMessage(MessageEvent event){ backend.send(event.message); }
```

--------------------------------

### Subscriber Priority Example

Source: https://greenrobot.org/eventbus/documentation/priorities-and-event-cancellation

Demonstrates how to assign a priority to an EventBus subscriber using the @Subscribe annotation. Higher priority values result in earlier event delivery within the same thread mode.

```java
@Subscribe(priority = 1); public void onEvent(MessageEvent event) { ... }
```

--------------------------------

### Getting a Sticky Event Manually

Source: https://greenrobot.org/eventbus/documentation/configuration/sticky-events

Retrieves a sticky event of a specific class without consuming it. It's recommended to check if the event is not null before processing.

```Java
MessageEvent stickyEvent = EventBus.getDefault().getStickyEvent(MessageEvent.class);
if(stickyEvent != null) {
  // Now do something with it
}
```

--------------------------------

### ThreadMode.MAIN Example

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

Subscribers are called in Android's main (UI) thread. If the posting thread is the main thread, event handlers are called directly. Event handlers must return quickly to avoid blocking the main thread. If not on Android, it behaves like ThreadMode.POSTING.

```java
@Subscribe(threadMode = ThreadMode.MAIN) public void onMessage(MessageEvent event) {
    textField.setText(event.message);
}
```

--------------------------------

### ThreadMode.MAIN_ORDERED Example

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

Subscribers are called in Android's main thread, with events enqueued for later delivery. This ensures a stricter, more consistent order of event processing. Event handlers must return quickly to avoid blocking the main thread. If not on Android, it behaves like ThreadMode.POSTING.

```java
@Subscribe(threadMode = ThreadMode.MAIN_ORDERED) public void onMessage(MessageEvent event) {
    textField.setText(event.message);
}
```

--------------------------------

### ThreadMode.BACKGROUND Example

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

Subscribers are called in a background thread. On Android, if the posting thread is not the main thread, handlers are called directly. If the posting thread is the main thread, EventBus uses a single background thread for sequential delivery. Event handlers should return quickly to avoid blocking the background thread. If not on Android, it always uses a background thread.

```java
@Subscribe(threadMode = ThreadMode.BACKGROUND) public void onMessage(MessageEvent event) {
    saveToDisk(event.message);
}
```

--------------------------------

### Essentials Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/proguard

Details on the greenrobot Essentials library, focusing on performant hash functions for Java, including a comparison of different hash functions.

```markdown
* [Essentials](https://greenrobot.org/essentials/)
    * [Features](https://greenrobot.org/essentials/features/)
      * [Essentials hash functions](https://greenrobot.org/essentials/features/performant-hash-functions-for-java/)
      * [Hash Comparison](https://greenrobot.org/essentials/features/performant-hash-functions-for-java/comparison-of-hash-functions/)
    * [Changelog](https://greenrobot.org/essentials/changelog/)
```

--------------------------------

### Essentials Documentation Overview

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Details the greenrobot Essentials library, focusing on performant hash functions for Java, including a comparison of hash functions.

```java
Essentials Documentation:
  - Performant hash functions for Java
  - Hash Comparison
```

--------------------------------

### Kotlin Configuration with kapt

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Sets up the EventBus annotation processor for Kotlin projects using the kapt plugin. It includes applying the kapt plugin and configuring the index class generation via kapt arguments.

```gradle
apply plugin: 'kotlin-kapt' // ensure kapt plugin is applied

dependencies {
    def eventbus_version = '3.2.0'
    implementation "org.greenrobot:eventbus:$eventbus_version"
    kapt "org.greenrobot:eventbus-annotation-processor:$eventbus_version"
}

kapt {
    arguments {
        arg('eventBusIndex', 'com.example.myapp.MyEventBusIndex')
    }
}
```

--------------------------------

### Related greenrobot Projects

Source: https://greenrobot.org/eventbus/documentation/index

Links to the GitHub repositories for several related projects developed by greenrobot, including EventBus, greenDAO, Essentials, and ObjectBox.

```Markdown
[EventBus](https://github.com/greenrobot/EventBus)
[greenDAO](https://github.com/greenrobot/greenDAO)
[Essentials](https://github.com/greenrobot/essentials)
[ObjectBox](https://github.com/objectbox/)
```

--------------------------------

### EventBus Initialization with Index

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Demonstrates how to initialize EventBus with a generated index class. This involves building the project first to generate the index, then providing an instance of the index to EventBus.builder().

```java
EventBus eventBus = EventBus.builder().addIndex(new MyEventBusIndex()).build();
```

--------------------------------

### EventBus Basics

Source: https://greenrobot.org/eventbus/documentation/faq

Demonstrates the fundamental usage of EventBus for posting and subscribing to events. This includes registering subscribers, posting events, and handling events on different thread modes.

```Java
public class MyEvent {
    private String message;

    public MyEvent(String message) {
        this.message = message;
    }

    public String getMessage() {
        return message;
    }
}

public class MySubscriber {
    @Subscribe(threadMode = ThreadMode.MAIN) 
    public void onMessageEvent(MyEvent event) {
        System.out.println("Received event: " + event.getMessage());
    }
}

// In your Activity or Service:
EventBus.getDefault().register(new MySubscriber());
EventBus.getDefault().post(new MyEvent("Hello EventBus!"));
EventBus.getDefault().unregister(new MySubscriber());
```

--------------------------------

### EventBus Basics

Source: https://greenrobot.org/eventbus/documentation/index

Demonstrates the fundamental usage of EventBus for posting and subscribing to events. This includes registering subscribers, posting events, and handling events on different thread modes.

```Java
public class MyEvent {
    public final String message;

    public MyEvent(String message) {
        this.message = message;
    }
}

// In your Activity or Fragment:
@Override
protected void onResume() {
    super.onResume();
    EventBus.getDefault().register(this);
}

@Override
protected void onPause() {
    super.onPause();
    EventBus.getDefault().unregister(this);
}

// Subscriber method
@Subscribe(threadMode = ThreadMode.MAIN)
public void onMessageEvent(MyEvent event) {
    // Do something with the event
    Log.d("EventBus", "Received event: " + event.message);
}

// Posting an event
public void postEvent(View view) {
    EventBus.getDefault().post(new MyEvent("Hello EventBus!"));
}
```

--------------------------------

### Java Configuration with annotationProcessor

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Configures the EventBus annotation processor for plain Java projects using Gradle. It requires Gradle 5.2+ and specifies the index class to be generated.

```gradle
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                arguments = [ eventBusIndex : 'com.example.myapp.MyEventBusIndex' ]
            }
        }
    }
}

dependencies {
    def eventbus_version = '3.2.0'
    implementation "org.greenrobot:eventbus:$eventbus_version"
    annotationProcessor "org.greenrobot:eventbus-annotation-processor:$eventbus_version"
}
```

--------------------------------

### EventBus with Library Indexes

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Demonstrates how to build an EventBus instance and include indexes from different libraries. This is achieved by calling `addIndex()` for each library's index instance.

```java
EventBus eventBus = EventBus.builder()
    .addIndex(new MyEventBusAppIndex())
    .addIndex(new MyEventBusLibIndex())
    .build();
```

--------------------------------

### greenDAO - Queries

Source: https://greenrobot.org/eventbus/documentation/index

Details how to create and execute queries using greenDAO's QueryBuilder API, including filtering, ordering, and limiting results.

```java
Query<User> query = userDao.queryBuilder()
    .where(Properties.Name.eq("Alice"))
    .orderAsc(Properties.Email)
    .build();

List<User> users = query.list();
```

--------------------------------

### EventBus ProGuard Configuration

Source: https://greenrobot.org/eventbus/documentation/proguard

Information on configuring ProGuard for EventBus to ensure proper obfuscation and shrinking without breaking functionality.

```markdown
[](https://greenrobot.org/eventbus/documentation/proguard/)
```

--------------------------------

### Essentials - Performant Hash Functions

Source: https://greenrobot.org/eventbus/documentation/index

Introduces the Essentials library's focus on providing highly performant hash functions for Java, suitable for various data structures and caching mechanisms.

```java
import org.greenrobot.essentials.hash.Hash;

byte[] data = "some data".getBytes();
long hashValue = Hash.longHash(data);
System.out.println("Hash: " + hashValue);
```

--------------------------------

### EventBus 3.1 with Plain Java Support

Source: https://greenrobot.org/eventbus/documentation/how-to-get-started

Details on EventBus version 3.1, which introduced support for plain Java environments, expanding its usability beyond Android. This release allows developers to leverage EventBus in standard Java applications for decoupled communication.

```APIDOC
EventBus 3.1 Release Notes:

Features:
- Plain Java Support: EventBus can now be used in any Java environment without Android dependencies.
- Improved Performance: Optimizations for faster event delivery.
- Enhanced Threading Models: More flexible options for handling event delivery threads.

Usage:
- Add EventBus to your project:
  ```xml
  <dependency>
      <groupId>org.greenrobot</groupId>
      <artifactId>eventbus</artifactId>
      <version>3.1.0</version>
  </dependency>
  ```
- Register an event subscriber:
  ```java
  EventBus.getDefault().register(this);
  ```
- Subscribe to events:
  ```java
  @Subscribe(threadMode = ThreadMode.MAIN) 
  public void onMessageEvent(MessageEvent event) { 
      // Do something with the event
  }
  ```
- Post an event:
  ```java
  EventBus.getDefault().post(new MessageEvent("Hello World"));
  ```

Key Concepts:
- Event: A plain Java object that carries data.
- Subscriber: A class that registers to receive events.
- Poster: A class that posts events to the EventBus.
- ThreadMode: Specifies the thread on which the subscriber method should be executed (e.g., MAIN, POSTING, BACKGROUND, ASYNC).

Related Methods:
- `register(Object subscriber)`: Registers a subscriber with the EventBus.
- `unregister(Object subscriber)`: Unregisters a subscriber.
- `post(Object event)`: Posts an event to the EventBus.
- `hasSubscriberForEvent(Class<?> eventClass)`: Checks if there are any subscribers for a given event class.
- `removeStickyEvent(Object event)`: Removes a sticky event.

Limitations:
- Ensure proper registration and unregistration to avoid memory leaks.
```

--------------------------------

### AsyncExecutor Builder for Customization

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Illustrates how to use the AsyncExecutor.builder() to create a customized AsyncExecutor instance. Customizations can include the EventBus instance, thread pool configuration, and the failure event class.

```java
AsyncExecutor.builder()
    .eventBus(customEventBus)
    .threadPool(customThreadPool)
    .failureEventType(CustomFailureEvent.class)
    .build();
```

--------------------------------

### EventBus vs. BroadcastReceiver

Source: https://greenrobot.org/eventbus/documentation/faq

Compares EventBus to Android's BroadcastReceiver/Intent system, highlighting EventBus's advantages in convenience, API usage, and reduced overhead for various use cases.

```java
EventBus uses standard Java classes as events, offering a more convenient API than Android's BroadcastReceiver/Intent system.
EventBus is suitable for use cases where setting up Intents, preparing extras, implementing receivers, and extracting extras is cumbersome.
EventBus has a lower overhead compared to the Intent system.
```

--------------------------------

### Handling NoClassDefFoundError with Reflection

Source: https://greenrobot.org/eventbus/documentation/faq

Explains how `java.lang.NoClassDefFoundError` can occur due to Android reflection bugs with API levels and unavailable classes. It offers solutions like using a subscriber index, avoiding offending methods, or adjusting method visibility.

```java
// Solution 2: Use EventBus 3 with a subscriber index
// Add this to your build.gradle (app level):
// annotationProcessor 'org.greenrobot:eventbus-annotation-processor:3.3.1'

// Then, generate the index:
// In your main application class or a dedicated initialization method:
// EventBus.builder().addIndex(new MyEventBusIndex()).installDefaultEventBus();

// Solution 3 & 4: Modify subscriber methods
// If an offending method like this exists:
// public void onEvent(PersistableBundle bundle) { ... }
// Consider:
// 1. Changing to a method without PersistableBundle if it's a lifecycle method.
// 2. Moving the event handling logic to a different class.
// 3. Making the method non-public (e.g., private or protected) if it's public.
```

--------------------------------

### EventBus - Configuration

Source: https://greenrobot.org/eventbus/documentation/index

Details how to configure EventBus, including options for enabling/disabling logging, setting default thread modes, and managing event delivery.

```java
EventBus.builder().logNoSubscriberMessages(false).sendNoSubscriberEvent(true).installDefaultEventBus();
```

--------------------------------

### EventBus with Sticky Events

Source: https://greenrobot.org/eventbus/documentation/faq

Demonstrates the use of sticky events in EventBus, which allows events to be held by the bus and delivered to subscribers that join later. This is useful for events that should be delivered even if no subscriber is immediately available.

```Java
// Posting a sticky event:
EventBus.getDefault().postSticky(new MyStickyEvent("Sticky message"));

// Subscribing to a sticky event:
@Subscribe(sticky = true, threadMode = ThreadMode.MAIN) 
public void onStickyEvent(MyStickyEvent event) {
    System.out.println("Received sticky event: " + event.getMessage());
}

// Removing a sticky event:
EventBus.getDefault().removeStickyEvent(MyStickyEvent.class);
```

--------------------------------

### API Reference - EventBus JavaDocs

Source: https://greenrobot.org/eventbus/documentation/index

Provides a link to the official JavaDocs for EventBus version 3.0.x, offering detailed API information for all classes and methods.

```APIDOC
EventBus 3.0.x JavaDocs:
URL: https://greenrobot.org/files/eventbus/javadoc/3.0/

Key Classes:
- EventBus: The central class for sending and receiving events.
- Subscribe: Annotation to mark subscriber methods.
- ThreadMode: Enum for specifying delivery threads (MAIN, POSTING, BACKGROUND, ASYNC).

Key Methods:
- EventBus.getDefault(): Gets the default singleton EventBus instance.
- register(Object subscriber): Registers a subscriber.
- unregister(Object subscriber): Unregisters a subscriber.
- post(Object event): Posts an event to the bus.
- postSticky(Object event): Posts a sticky event.
- cancelEventDelivery(Object event): Cancels the delivery of an event.

Example Usage:
EventBus.getDefault().register(myObject);
EventBus.getDefault().post(new MyEvent());
@Subscribe(threadMode = ThreadMode.MAIN) public void onEvent(MyEvent event) { ... }
```

--------------------------------

### greenDAO - Sessions

Source: https://greenrobot.org/eventbus/documentation/index

Describes the concept of greenDAO Sessions, which provide access to DAOs and CRUD operations for your entities, and how to manage them.

```java
// Get DaoMaster and DaoSession
DaoMaster.DevOpenHelper helper = new DaoMaster.DevOpenHelper(this, "mydatabase.db");
Database db = helper.getWritableDatabase();
DaoMaster daoMaster = new DaoMaster(db);
DaoSession daoSession = daoMaster.newSession();

// Get DAO for User entity
UserDao userDao = daoSession.getUserDao();
```

--------------------------------

### greenDAO - Joins

Source: https://greenrobot.org/eventbus/documentation/index

Explains how to perform queries involving relationships between entities (joins) using greenDAO's QueryBuilder, including handling one-to-one and one-to-many relationships.

```java
// Query users and their addresses (assuming User has a to-one relationship with Address)
Query<User> query = userDao.queryBuilder()
    .join(UserDao.Properties.AddressId, Address.class)
    .where(AddressDao.Properties.City.eq("New York"))
    .build();

List<User> usersInNewYork = query.list();
```

--------------------------------

### EventBus Thread Modes

Source: https://greenrobot.org/eventbus/documentation/faq

Illustrates the different thread modes available in EventBus for handling event delivery. This includes MAIN, POSTING, BACKGROUND, and ASYNC thread modes, explaining when to use each.

```Java
// Subscriber methods with different thread modes:

@Subscribe(threadMode = ThreadMode.MAIN) 
public void onEventMainThread(MyEvent event) {
    // Handle event on the main thread
}

@Subscribe(threadMode = ThreadMode.POSTING) 
public void onEvent(MyEvent event) {
    // Handle event in the same thread that posted it
}

@Subscribe(threadMode = ThreadMode.BACKGROUND) 
public void onEventBackgroundThread(MyEvent event) {
    // Handle event in a background thread
}

@Subscribe(threadMode = ThreadMode.ASYNC) 
public void onEventAsync(MyEvent event) {
    // Handle event in a separate thread managed by EventBus
}
```

--------------------------------

### EventBus - Delivery Threads (ThreadMode)

Source: https://greenrobot.org/eventbus/documentation/index

Explains the different delivery threads available in EventBus, such as MAIN, BACKGROUND, POSTING, and ASYNC, and how to specify them using the @Subscribe annotation.

```java
@Subscribe(threadMode = ThreadMode.MAIN) public void onEventMainThread(MyEvent event) { ... }
@Subscribe(threadMode = ThreadMode.BACKGROUND) public void onEventBackgroundThread(MyEvent event) { ... }
@Subscribe(threadMode = ThreadMode.POSTING) public void onEvent(MyEvent event) { ... }
@Subscribe(threadMode = ThreadMode.ASYNC) public void onEventAsync(MyEvent event) { ... }
```

--------------------------------

### Subscribing to Events

Source: https://greenrobot.org/eventbus/documentation/configuration

Shows how to subscribe to events using the @Subscribe annotation. Subscribers can specify the thread mode (e.g., POSTING, MAIN, BACKGROUND, ASYNC) to control where the event is delivered.

```Java
public class MyActivity extends Activity {
    @Override
    protected void onResume() {
        super.onResume();
        EventBus.getDefault().register(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        EventBus.getDefault().unregister(this);
    }

    @Subscribe(threadMode = ThreadMode.MAIN) 
    public void onMessageEvent(MessageEvent event) {
        // Do something with the event
    }
}
```

--------------------------------

### AsyncExecutor Documentation

Source: https://greenrobot.org/eventbus/documentation/asyncexecutor

Documentation for the AsyncExecutor component of EventBus, likely used for managing asynchronous event delivery.

```APIDOC
AsyncExecutor:
  Purpose: Manages asynchronous execution of event handlers.
  Usage: Used by EventBus to deliver events to subscribers on background threads.
  Dependencies: None explicitly mentioned, but relies on Java's concurrency utilities.
  Methods:
    - execute(Runnable runnable): Executes a given Runnable task asynchronously.
    - shutdown(): Shuts down the executor, releasing resources.
  Limitations: Specific thread pool configuration or customization options are not detailed here.
```

--------------------------------

### Subscriber Index Generation

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Details the process of generating a subscriber index to improve startup performance by avoiding reflection. This is particularly useful for large applications.

```Java
// Add the EventBus annotation processor to your build.gradle:
// annotationProcessor 'org.greenrobot:eventbus-annotation-processor:3.3.1'

// Then, EventBus will automatically generate the index.
```

--------------------------------

### EventBus Configuration

Source: https://greenrobot.org/eventbus/documentation/configuration

This section details how to configure EventBus, including options for enabling or disabling features like logging and background thread handling. Proper configuration is essential for optimizing event delivery and performance.

```Java
EventBus.builder().logNoSubscriberMessages(false).sendNoSubscriberEvent(true).build();
```

--------------------------------

### greenDAO - Modelling Entities

Source: https://greenrobot.org/eventbus/documentation/index

Explains how to define data models using greenDAO annotations like @Entity, @Id, @Property, @NotNull, and relationships like @ToMany and @ToOne.

```java
@Entity(nameInDb = "users")
public class User {
    @Id(autoincrement = true)
    private Long userId;

    @Property(nameInDb = "user_name")
    private String name;

    @NotNull
    private String email;

    @ToOne(joinProperty = "addressId")
    private Address address;
    private Long addressId;

    // ... getters and setters ...
}
```

--------------------------------

### EventBus - Subscriber Index

Source: https://greenrobot.org/eventbus/documentation/index

Explains how to use the subscriber index feature to improve performance by pre-calculating subscriber methods, especially useful for ProGuard/R8 obfuscation.

```java
// Generated Subscriber Index implementation
public class MyEventBusIndex implements SubscriberInfoIndex {
    // ... implementation details ...
}

// In your Application class:
EventBus.builder().subscriberInfoIndexes(new MyEventBusIndex()).installDefaultEventBus();
```

--------------------------------

### Posting Events

Source: https://greenrobot.org/eventbus/documentation/how-to-get-started

Events are posted to the EventBus using the post() method. Any registered subscribers that match the posted event's type will receive it. This allows for decoupled communication between different parts of an application.

```Java
EventBus.getDefault().post(new MessageEvent("Hello everyone!"));
```

--------------------------------

### EventBus Build Warning: Unrecognized Options

Source: https://greenrobot.org/eventbus/documentation/faq

This snippet explains a common build warning in EventBus: 'The following options were not recognized by any processor: [eventBusIndex]'. It clarifies that this warning appears when no @Subscribe annotations are present in the code, preventing the annotation processor from consuming the 'eventBusIndex' option. The solution is to add @Subscribe annotations to the code.

```java
/**
 * This warning occurs when the build script is set up, but no @Subscribe annotations
 * have been added to the code yet. Without any @Subscribe annotations, the annotation
 * processor for indexing will not be triggered to consume the 'eventBusIndex' option.
 *
 * To resolve this, simply add some @Subscribe annotations to your code.
 *
 * Example:
 * @Subscribe(threadMode = ThreadMode.MAIN)
 * public void onMessageEvent(MessageEvent event) { ... }
 */
```

--------------------------------

### EventBus Thread Modes

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Explains the different thread modes available for event delivery in EventBus: POSTING, MAIN, BACKGROUND, and ASYNCHRONOUS. Each mode dictates the execution context of the subscriber method.

```APIDOC
ThreadMode:
  POSTING: Subscriber methods are called in the same thread that posted the event. This is the default.
  MAIN: Subscriber methods are called on the Android main thread (UI thread). If the event is posted from the main thread, the subscriber is called immediately. Otherwise, the event is posted to the main thread's event queue.
  BACKGROUND: Subscriber methods are called in a background thread. If the event is posted from a background thread, the subscriber is called immediately. Otherwise, the event is posted to a background thread pool.
  ASYNCHRONOUS: Subscriber methods are always called in a separate background thread, regardless of the posting thread. A thread pool is used for these calls.
```

--------------------------------

### Define Events in EventBus

Source: https://greenrobot.org/eventbus/documentation/how-to-get-started

This snippet shows how to define a simple event class for use with EventBus. Events are plain Java objects (POJOs) with no special requirements.

```java
public class MessageEvent { 
    public final String message; 
    public MessageEvent(String message) { 
        this.message = message; 
    } 
}
```

--------------------------------

### Posting Events

Source: https://greenrobot.org/eventbus/documentation/configuration

Demonstrates how to post events to the EventBus. Events are objects that carry data. Subscribers registered with the EventBus will receive these events based on their subscription methods.

```Java
EventBus.getDefault().post(new MessageEvent("Hello everyone!"));
```

--------------------------------

### Posting an Event to the EventBus

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Shows how to post an event to the EventBus. Any registered subscribers that have a method annotated with @Subscribe and matching the event type will receive the event.

```Java
MyEvent event = new MyEvent("Hello EventBus!");
EventBus.getDefault().post(event);
```

--------------------------------

### EventBus 2.4 Documentation Access

Source: https://greenrobot.org/eventbus/documentation/index

Provides access to the documentation and JavaDocs for EventBus version 2.4. This is useful for users who have not yet upgraded to EventBus 3.

```Markdown
[EventBus 2.4 How-To](https://github.com/greenrobot/EventBus/blob/v2/HOWTO.md)
[EventBus 2.4.x Java Docs](http://greenrobot.org/files/eventbus/javadoc/2.4/)
```

--------------------------------

### EventBus - ProGuard

Source: https://greenrobot.org/eventbus/documentation/index

Provides ProGuard rules necessary to ensure EventBus functions correctly after code shrinking and obfuscation, preventing issues with reflection.

```java
-keep class org.greenrobot.eventbus.** { *; }
-keep class **.MyEventBusIndex { *; }
-keep @org.greenrobot.eventbus.Subscribe class * { *; }
-keepclassmembers class * { @org.greenrobot.eventbus.Subscribe *;
}
```

--------------------------------

### EventBus ProGuard Configuration

Source: https://greenrobot.org/eventbus/documentation/proguard

This snippet provides the necessary ProGuard rules to ensure EventBus functions correctly after code obfuscation. It prevents issues with reflection-based event delivery.

```Java
-keepclassmembers class ** { 
    void onEvent*(**); 
}
```

--------------------------------

### Registering an EventBus Subscriber

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Demonstrates how to register an object as a subscriber to receive events from the EventBus. Subscribers must be registered before they can receive events. Unregistering is also crucial to prevent memory leaks.

```Java
EventBus.getDefault().register(subscriber);
// ... later ...
EventBus.getDefault().unregister(subscriber);
```

--------------------------------

### EventBus - Priorities and Event Cancellation

Source: https://greenrobot.org/eventbus/documentation/index

Describes how to set priorities for subscribers to control the order of event delivery and how to cancel events to prevent them from being delivered to subsequent subscribers.

```java
@Subscribe(priority = 10) public void onEventPriority(MyEvent event) { ... }
@Subscribe public void onEventCancel(MyEvent event) {
    EventBus.getDefault().cancelEventDelivery(event);
}
```

--------------------------------

### greenDAO - Database Encryption

Source: https://greenrobot.org/eventbus/documentation/index

Explains how to encrypt the greenDAO database using SQLCipher for enhanced security.

```java
// Add SQLCipher dependency
// Initialize DaoMaster with encryption key
DaoMaster.OpenHelper helper = new DaoMaster.EncryptedDaoMaster(this, "encrypted.db", "your-secret-key".getBytes());
Database db = helper.getWritableDatabase();
DaoMaster daoMaster = new DaoMaster(db);
DaoSession daoSession = daoMaster.newSession();
```

--------------------------------

### greenDAO - Relations

Source: https://greenrobot.org/eventbus/documentation/index

Covers the definition and querying of relationships between entities in greenDAO, including one-to-one, one-to-many, and many-to-many relationships.

```java
// Example: User has many Orders
@Entity
public class User {
    // ...
    @ToMany(referencedJoinProperty = "userId")
    @Relation(backend = Relation.RelationType.SHARED_IN_CHILD)
    private List<Order> orders;
    // ...
}

// Accessing relations:
User user = userDao.load(1L);
List<Order> userOrders = user.getOrders(); // Lazy loading
```

--------------------------------

### EventBus Subscriber Registration Issues

Source: https://greenrobot.org/eventbus/documentation/faq

Addresses scenarios where events are received multiple times due to incorrect subscriber registration. It suggests checking for multiple registrations, unregistering properly, and verifying registration/unregistration call counts.

```java
// Example of checking registration/unregistration counts
// In your Activity or Fragment:

private int registrationCount = 0;

@Override
protected void onResume() {
    super.onResume();
    EventBus.getDefault().register(this);
    registrationCount++;
    Log.d("EventBus", "Registered. Count: " + registrationCount);
}

@Override
protected void onPause() {
    super.onPause();
    if (EventBus.getDefault().isRegistered(this)) {
        EventBus.getDefault().unregister(this);
        registrationCount--;
        Log.d("EventBus", "Unregistered. Count: " + registrationCount);
    }
}

// Ensure unregister is called in onDestroy or onPause as appropriate for your lifecycle.
```

--------------------------------

### EventBus Delivery Threads and ThreadMode

Source: https://greenrobot.org/eventbus/documentation/delivery-threads-threadmode

This section details how EventBus handles event delivery across different threads using various ThreadMode annotations. It explains the behavior of each mode, such as POSTING, MAIN, BACKGROUND, and ASYNC, and their implications for application performance and responsiveness.

```Java
public class MyActivity extends Activity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        EventBus.getDefault().register(this);
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        EventBus.getDefault().unregister(this);
    }

    @Subscribe(threadMode = ThreadMode.MAIN) // Or POSTING, BACKGROUND, ASYNC
    public void onMessageEvent(MessageEvent event) {
        // Do something with the event on the main thread
        Log.d("EventBus", "Received message: " + event.message);
    }
}

public class MessageEvent {
    public final String message;

    public MessageEvent(String message) {
        this.message = message;
    }
}
```

--------------------------------

### Posting a Sticky Event

Source: https://greenrobot.org/eventbus/documentation/configuration/sticky-events

Posts a sticky event using EventBus. Sticky events are retained by the bus and delivered to new subscribers that register later.

```Java
EventBus.getDefault().postSticky(new MessageEvent("Hello everyone!"));
```

--------------------------------

### EventBus Sticky Events Configuration

Source: https://greenrobot.org/eventbus/documentation/configuration/sticky-events

This section details the configuration of sticky events within the EventBus library. Sticky events are events that remain in the EventBus after they have been posted, allowing subscribers to receive them even if they subscribe after the event was posted. This is useful for scenarios where a subscriber needs to immediately receive the latest state upon subscription.

```Java
EventBus.getDefault().postSticky(new MessageEvent("Hello World"));

// Subscribe to sticky events
EventBus.getDefault().register(this);

@Subscribe(sticky = true)
public void onEvent(MessageEvent event) {
    // Handle the sticky event
}
```

--------------------------------

### Thread Modes

Source: https://greenrobot.org/eventbus/documentation/configuration

Details the different thread modes available for event delivery: POSTING (same thread as the poster), MAIN (Android main UI thread), BACKGROUND (a background thread), and ASYNC (a new background thread for each event).

--------------------------------

### EventBus with Annotations

Source: https://greenrobot.org/eventbus/documentation/index

Illustrates how annotations are used with EventBus to define subscriber methods and their behavior. This includes the `@Subscribe` annotation and its parameters like `threadMode`.

```Java
import org.greenrobot.eventbus.Subscribe;
import org.greenrobot.eventbus.ThreadMode;

public class MySubscriber {

    // Subscribe to MyEvent, delivered on the main thread
    @Subscribe(threadMode = ThreadMode.MAIN, sticky = true)
    public void onMyEvent(MyEvent event) {
        System.out.println("Received sticky event: " + event.message);
    }

    // Subscribe to another event type
    @Subscribe(threadMode = ThreadMode.POSTING)
    public void onAnotherEvent(AnotherEvent event) {
        System.out.println("Received another event.");
    }
}
```

--------------------------------

### EventBus - AsyncExecutor

Source: https://greenrobot.org/eventbus/documentation/index

Details the configuration and usage of AsyncExecutor for handling asynchronous event delivery in EventBus, allowing custom thread pool management.

```java
ExecutorService executorService = Executors.newFixedThreadPool(5);
EventBus.builder().asyncExecutor(executorService).installDefaultEventBus();
```

--------------------------------

### EventBus - Sticky Events

Source: https://greenrobot.org/eventbus/documentation/index

Explains the concept of sticky events in EventBus, which are events that remain in the bus after delivery and can be received by subscribers that subscribe later.

```java
EventBus.getDefault().postSticky(new StickyEvent("Sticky data"));
// ... later ...
EventBus.getDefault().register(this);
// Subscribers annotated with @Subscribe(sticky = true) will receive the sticky event.
```

--------------------------------

### ProGuard/R8 Rules for EventBus Subscribers

Source: https://greenrobot.org/eventbus/documentation/proguard

These rules are essential for ProGuard or R8 to correctly identify and preserve EventBus subscriber methods. Without them, minification processes might remove these methods, leading to runtime errors. This configuration is necessary regardless of whether a subscriber index is used.

```proguard
# Keep EventBus subscriber methods
-keepclassmembers class * {
    void *(org.greenrobot.eventbus.Subscribe);
}
```

--------------------------------

### EventBus Subscriber Index Requirements

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Specifies the requirements for methods and classes to be included in the EventBus subscriber index. These include being public and not being used within anonymous classes.

```java
/**
 * The @Subscribe method and its class must be public.
 */
public class MySubscriber {
    @Subscribe
    public void onEvent(MyEvent event) {
        // Handle event
    }
}

/**
 * The event class must be public.
 */
public class MyEvent {
    // Event data
}

// @Subscribe cannot be used inside of anonymous classes.
// Example of what NOT to do:
// new MyClass() {
//     @Subscribe
//     public void onEvent(MyEvent event) {
//         // This will not be indexed
//     }
// };
```

--------------------------------

### Subscriber Registration and Unregistration

Source: https://greenrobot.org/eventbus/documentation/how-to-get-started

Subscribers must register themselves with the EventBus to receive events and unregister when they are no longer needed. In Android activities and fragments, it's common practice to register and unregister according to the component's lifecycle, typically using onStart() and onStop().

```Java
@Override
public void onStart() {
    super.onStart();
    EventBus.getDefault().register(this);
}

@Override
public void onStop() {
    EventBus.getDefault().unregister(this);
    super.onStop();
}
```

--------------------------------

### Subscribing to a Sticky Event

Source: https://greenrobot.org/eventbus/documentation/configuration/sticky-events

Subscribes to sticky events and receives them on the main thread. The @Subscribe annotation with sticky=true ensures that any previously posted sticky event of the specified type is delivered immediately upon registration.

```Java
@Override public void onStart() {
  super.onStart();
  EventBus.getDefault().register(this);
}

// UI updates must run on MainThread
@Subscribe(sticky = true, threadMode = ThreadMode.MAIN)
public void onEvent(MessageEvent event) {
  textField.setText(event.message);
}

@Override public void onStop() {
  EventBus.getDefault().unregister(this);
  super.onStop();
}
```

--------------------------------

### greenDAO - Custom Types

Source: https://greenrobot.org/eventbus/documentation/index

Details how to handle custom data types that are not directly supported by SQLite by implementing PropertyConverter.

```java
// Define a custom type
public class MyCustomType { ... }

// Implement PropertyConverter
public class MyCustomTypeConverter implements PropertyConverter<MyCustomType, String> {
    @Override
    public MyCustomType convertToEntityProperty(String databaseValue) {
        // Convert String from DB to MyCustomType
    }

    @Override
    public String convertToDatabaseValue(MyCustomType entityProperty) {
        // Convert MyCustomType to String for DB
    }
}

// Annotate entity property
@Convert(converter = MyCustomTypeConverter.class, columnType = String.class)
private MyCustomType customData;
```

--------------------------------

### Configure Default EventBus with Exception Rethrow

Source: https://greenrobot.org/eventbus/documentation/configuration

Configures the default EventBus instance to rethrow exceptions that occur in subscriber methods. This is typically done for debug builds to aid in debugging. The configuration should only be performed once before the default instance is accessed.

```java
EventBus.builder().throwSubscriberException(BuildConfig.DEBUG).installDefaultEventBus();
```

--------------------------------

### Defining an Event Subscriber Method

Source: https://greenrobot.org/eventbus/documentation/subscriber-index

Illustrates how to define a method within a subscriber class that will receive events. The @Subscribe annotation marks the method, and the thread mode determines on which thread the method will be executed.

```Java
public class MySubscriber {
    @Subscribe(threadMode = ThreadMode.MAIN) 
    public void onMessageEvent(MyEvent event) {
        // Handle the event on the main thread
        System.out.println("Received event: " + event.message);
    }
}
```

--------------------------------

### Thread Modes

Source: https://greenrobot.org/eventbus/documentation/index

Explains the different thread modes available in EventBus for handling event delivery. This allows developers to control where subscriber methods are executed, such as on the main thread, a background thread, or the posting thread.

```Java
// Subscriber methods with different thread modes:

// Executes in the same thread that posted the event
@Subscribe(threadMode = ThreadMode.POSTING)
public void onPostingThreadEvent(MyEvent event) {
    Log.d("EventBus", "On posting thread: " + Thread.currentThread().getName());
}

// Executes on the main thread (UI thread)
@Subscribe(threadMode = ThreadMode.MAIN)
public void onMainThreadEvent(MyEvent event) {
    Log.d("EventBus", "On main thread: " + Thread.currentThread().getName());
}

// Executes on a background thread managed by EventBus
@Subscribe(threadMode = ThreadMode.BACKGROUND)
public void onBackgroundThreadEvent(MyEvent event) {
    Log.d("EventBus", "On background thread: " + Thread.currentThread().getName());
}

// Executes on a background thread, but only if the event was posted from a different thread
@Subscribe(threadMode = ThreadMode.ASYNC)
public void onAsyncThreadEvent(MyEvent event) {
    Log.d("EventBus", "On async thread: " + Thread.currentThread().getName());
}
```
Tokens:
Raw