Tide

Event based publisher-subscriber framework for java. Create and raise custom events in your Java code.

Getting Started

Gradle

Add tide as a jave dependency

        apply plugin: 'java'

        repositories { 
          mavenCentral()
        }

        dependencies {
          compile group: 'com.github.abyu', name: 'tide', version: '1.0.0'
        }
      

Maven

Add tide as a dependency in your pom.xml

      
        ...
        
          
            com.github.abyu
            tide
            1.0.0
          
          ...
        
      
      

Usage

Start by creating a singleton instance of EventBus, if you are using a DependencyInjection framework make sure the instance of EventBus in singleton scope. To obtain an instance of EventBus manually, use EventBus's getInstance method, that will make sure that you use the same instance across your code. Do not create a new instance of EventBus yourself, the event model will not work as intended.

Create events by extending Event class.

        /* DownloadComplete.java */
        package com.example;

        import org.skk.tide.Event;

        public class DownloadComplete extends Event {

          public DownloadComplete() {
              super();
          }
        }
      

All your event handlers should implement the interface EventHandler

          /* DownloadMachine.java */
          package com.example;
          
          import org.skk.tide.EventHandler;

          public class DownloadMachine implements EventHandler {

            /* rest of class code goes here */
          }
       

Your handle will handle particular events, create a method to handle each type of the event.

Use the annotation HandleEvent, to specify what event your method handles.

          /* DownloadMachine.java */
          package com.example;

          import org.skk.tide.EventHandler;

          public class DownloadMachine implements EventHandler {

            /* rest of class code goes here */

            @HandleEvent(eventType = DownloadComplete.class)
            public void downloadCompleted(){

              /* Handle code goes here */
            }
          }
       

Now that we have an event to raise and a handler to handle it, we will have to tell tide to call this handler when the event is raised

We do that by registering the handler to EventBus, specifying the event name

          /* Application.java */
          package com.example;

          import org.skk.tide.EventBus;

          public class Application {

            private EventBus eventBus;

            public void init(){

              eventBus.register(new DownloadMachine(), DownloadComplete.class);
            }
          }
       

Raise the event using the EventBus's raiseEvent method, passing in a new instance of the event.

        /* ActionMachine.java */
        package com.example;

        import org.skk.tide.EventBus;

        public class ActionMachine {

          public ActionMachine(EventBus eventBus){
          
            this.eventBus = eventBus;
          }

          public void orchestrate(){

            eventBus.raiseEvent(new DownloadComplete());
          }
        }
       

If you need to pass any data to your handler, create an object of type Eventdata.

        /* DownloadData.java */
        package com.example;

        import org.skk.tide.EventData;

        public class DownloadData implements EventData{

          /* rest of the class */
        }
       

Pass the instance of data while raising the event.

        /* ActionMachine.java */
        public class ActionMachine {

          public void orchestrate(){

            eventBus.raiseEvent(new DownloadComplete().withData(new DownloadData()));
          }
        }
       

In order for the handler method to receive this data, the handler method must take a parameter of this type.

          /* DownloadMachine.java */
          package com.example;

          import org.skk.tide.EventHandler;

          public class DownloadMachine implements EventHandler {

            /* rest of class code goes here */

            @HandleEvent(eventType = DownloadComplete.class)
            public void downloadCompleted(EventData data){
              /* Cast to the required type */
              DownloadData downloadData = (DownloadData) data;
              /* Handle code goes here */
            }
          }
        

The handle method should be either zero parameter or one parameter of type EventData.

If an event was raised with some data and the registed handler method does not take in data as the parameter, the handler method will be invoked without any data.

EventBus uses reflection to find out the corresponding handler method for an event, hence the method should be annotated properly as mentioned above. If not MethodNotFound exception is thrown at run time