diff --git a/website/index.html b/website/index.html index 8c44e9e..61cdd35 100644 --- a/website/index.html +++ b/website/index.html @@ -24,88 +24,82 @@

An enhanced Guava-based event bus with emphasis on Android support.

Introduction

-

Otto is an event bus designed to decouple different parts of your application while still allowing them - to communicate efficiently.

-

Forked from Guava, Otto adds unique functionality to an already refined event bus as well as specializing - it to the Android platform.

- +

Otto is an Android-optimized event bus forked from Guava that helps discrete parts of your + application communicate efficiently.

+

Usage

-

Otto is designed with Android-specific use cases in mind and is intended for use as a singleton - (though that is not required). These examples assume you have an - instance in the variable bus obtained through injection or another appropriate mechanism.

- +

Otto is intended for use as a singleton (although this is not required). These examples assume you have an + instance of the Bus class in the variable bus obtained through injection or + another appropriate mechanism.

+
Publishing
-

Event publishing is the most important part of the bus as it allows you to tell subscribers that an - action has occurred. An instance of any class may be published on the bus and it will only be dispatched to - subscribers for that type.

-

To publish a new event, call the post method:

+

To publish a new event, call the post method, providing an instance of any class:

bus.post(new AnswerAvailableEvent(42));
-

Posting to the bus is a synchronous action so when program execution continues it is guaranteed that all - subscribers have been called.

+

The bus calls every method that subscribes to events of the argument's type, passing along the + argument itself. In most cases, this is a synchronous action—when program execution continues, it's + guaranteed that all subscribing methods have been called. This is not a synchronous + action, however, if it's called during the execution of another bus method. In that case, the event + is enqueued for publication after the current bus method returns.

Subscribing
-

Subscription is the complement to event publishing—it lets you receive notification that an event - has occurred. To subscribe to an event, annotate a method with @Subscribe. The method should - take only a single parameter, the type of which will be the event you wish to subscribe to.

-

To listen for the event published in the previous section we would need the following:

+

To subscribe to events of a particular type, annotate a method with @Subscribe. + The method should take only a single parameter: the event type you want to subscribe to.

+

To receive the event published in the previous example, you need the following:

@Subscribe public void answerAvailable(AnswerAvailableEvent event) {
     // TODO: React to the event somehow!
 }
-

The name of the method can be anything you like. The annotation, single argument, and public accessor - are all that is required.

-

In order to receive events, a class instance needs to register with the bus. If this refers - to an instance of the class in which the previous method was present, we can register using the - following:

+

The name of the method can be anything you like. The annotation, argument type, and public + accessor are required.

+

Additionally, a class instance needs to register with the bus before its methods (such as + answerAvailable) can receive events:

bus.register(this);
-

Registering will only find methods on the immediate class type. Unlike the Guava event - bus, Otto will not traverse the class hierarchy and add methods from base classes or interfaces that are - annotated. This is an explicit design decision to improve performance of the library as well as keep your +

A class instance can call the unregister method to stop receiving events. See the + sample application included in the download for a complete example.

+

Note: Registering only applies to methods of the immediate class type. Unlike the Guava event + bus, Otto does not traverse the class hierarchy and add annotated methods from base classes or interfaces. + This is an explicit design decision to improve performance of the library and keep your code simple and unambiguous.

-

Remember to also call the unregister method when appropriate. See the sample application - included in the download for a complete example.

Producing
-

When subscribing to events it is often desired to also fetch the current known value for specific events - (e.g., current location, active user, etc.). To address this common paradigm, Otto adds the concept of - 'Producers' which provide an immediate callback to any subscribers upon their registration.

-

To create a producer, annotate a method with @Produce. The method should take no parameters - and its return type will be used as the type of event for which it can produce initial values. If we are - keeping track of the last answer event somewhere from above we can register to produce its initial - value:

+

When you first subscribe to an event type, you often want to know something about the current state of + the world (e.g., the most recently published event). To address this, Otto adds the concept of + producers, methods that provide an immediate callback to subscribers as soon as they've + registered with the bus.

+

To create a producer, annotate a method with @Produce. The method should take no parameters, + and its return type should be the event type it's associated with. If you're keeping track of the most recent + AnswerAvailableEvent, you can register a producer to provide it to newly registered subscribers:

@Produce public AnswerAvailableEvent produceAnswer() {
     // Assuming 'lastAnswer' exists.
     return new AnswerAvailableEvent(this.lastAnswer);
 }
-

Producers, like subscribers, must also be registered:

+

Producers, like subscribers, must be registered:

bus.register(this);
-

When registering, the producer method will be called once for each subscriber previously registered for - the same type. The producer method will also be called once for each new method that subscribes to an event - of the same type.

-

You may only have one producer per event type registered at a time on a bus.

+

When it's registered, the producer is called once for each existing subscriber of + the same type. Thereafter, it's called once for each new subscriber of the same type.

+

Note: You can have only one producer per event type registered at a time on a bus.

Thread Enforcement
-

Since at times it may be ambiguous on which thread you are receiving callbacks, Otto provides an - enforcement mechanism to ensure you are always called on the thread you desire. By default, all interaction - with an instance is confined to the main thread.

- 
// Both of these are functionally equivalent.
+            
Otto provides an enforcement mechanism to ensure you always receive callbacks on the thread you want.
+            By default, all interaction with an instance is confined to the main thread.

+            
// These are functionally equivalent.
 Bus bus1 = new Bus();
 Bus bus2 = new Bus(ThreadEnforcer.MAIN);

-            
If you are not concerned on which thread interaction is occurring, instantiate a bus instance with
+            
If you don't care which thread interactions happen on, instantiate a bus instance with
             ThreadEnforcer.ANY. You can also provide your own implementation of the
             ThreadEnforcer interface if you need additional functionality or validation.

 
             
Including In Your Application

-            
Otto is packaged as a standalone .jar file which you can place in the libs/ folder of your
+            
Otto is packaged as a standalone .jar file that you can place in the libs/ folder
             of your application. It is compatible with all versions of Android and has no minimum SDK requirement. You
-            can download the latest .jar on the GitHub project by clicking the "Download" button.

-            
If you are a Maven user, you can also fetch Otto from the central repositories by including the following
+            can download the latest .jar on the GitHub project by clicking the Download button.

+            
If you're a Maven user, you can also fetch Otto from the central repositories by including the following
             dependnecy in your application's pom.xml:

             
<dependency>
     <groupId>com.squareup</groupId>
     <artifactId>otto</artifactId>
     <version>(insert latest version)</version>
 </dependency>

-            
Once you've installed Otto, add the following lines to your proguard-project.txt file:

+            
After you've installed Otto, add the following lines to your proguard-project.txt file:

             
-keepclassmembers class ** {
     @com.squareup.otto.Subscribe public *;
     @com.squareup.otto.Produce public *;
@@ -113,7 +107,7 @@ 
Including In Your Application

             
This ensures your annotated methods aren't removed by ProGuard.

 
             
Contributing

-            
If you would like to contribute code to Otto you can do so through GitHub by forking the repository and
+            
If you'd like to contribute code to Otto, you can do so through GitHub by forking the repository and
             sending a pull request.

             
When submitting code, please make every effort to follow existing conventions and style in order to keep
             the code as readable as possible. Please also make sure your code compiles by running mvn clean