Fork me on GitHub

Wave Layer

Allow asynchronous communication between components

Wave Overview

What's a Wave

A Wave is a temporary object created to carry data througt CS-MVC components.

They allow JRebirth to handle application internal events asynchronously between each components, at the opposite you can use getModel, getCommand and getService method to perform synchronous operations.

Waves are handled by the notifier engine which are running within the JRebirthThread .

Short UML Diagram:

Wave Group

There are 4 main group of waves :

  1. Call Command : used to trigger a command action
  2. Call Service : used to call a service, later another wave will be used
  3. Attach Ui : used to link two JavaFX nodes
  4. Undefined : to handle all other waves, the wave type must be defined

Wave ItemType

A wave item designate a Java type (precisely a generic type that can be for example: List<String>). It could be used with a custom name or as a parameter.

Don't forget the opening and closing braces used { } to allow anonymous class to define the super generic type !

Wave items are used by Wave Type to describe an api contract.

67
68
69
70
71
72
73
/** The file containing all events serialized. */
WaveItemBase<File> EVENTS_FILE = new WaveItemBase<File>() {
};
 
/** The name of the events. */
WaveItemBase<List<JRebirthEvent>> EVENTS = new WaveItemBase<List<JRebirthEvent>>() {
};

Wave items can also be used to define the unique identifier of a value wrapped into a WaveData wrapper stored into a wave.

86
87
88
89
90
91
/** This wave item will be used only into a WaveData to pass the current Service task handled by the wave. */
WaveItem<ServiceTaskBase<?>> SERVICE_TASK = new WaveItemBase<ServiceTaskBase<?>>(false) {
};
 
/** This wave item will be used only into a WaveData to pass the right progress bar used by service task. */
WaveItem<ProgressBar> PROGRESS_BAR = new WaveItemBase<ProgressBar>(false) {
154
155
// Attach ServiceTask to the source wave
sourceWave.addDatas(Builders.waveData(JRebirthWaves.SERVICE_TASK, task));

Wave Type

The wave type is where black magic resides. It defines a contract between the emitter (the one who creates the wave) and the receiver (the one who handles the waves).

This contract is dynamic because it relies on a String and WaveItem objects.

A WaveType has a unique name and a set of WaveItem objects. It must be created and stored like this:

    • Into an Interface to define wave contract (here without argument)
39
40
41
42
43
/** Trigger a Unload wave. */
WaveType DO_UNLOAD = Builders.waveType("UNLOAD");
 
/** Trigger a Play wave. */
WaveType DO_PLAY = Builders.waveType("PLAY");
    • Into a service class (here with on argument) :
41
42
43
44
45
46
47
48
/** Wave type use to load events. */
WaveType DO_LOAD_EVENTS = Builders.waveType("LOAD_EVENTS")
                                  .items(EditorWaves.EVENTS_FILE)
                                  .returnAction("EVENTS_LOADED")
                                  .returnItem(EditorWaves.EVENTS);
 
/**
 * Parse the event file.

WaveType name

This string is used to link to a component method , this call is made by reflection when the wave is processed.

WaveItem List

Each WaveItem will be passed to the method as an argument

Wave argument

Each wave procesing method must add a least argument : the source wave, thus it will be possible to know the handling context for this method call.

The wave argument is useful to access to wave bean or other information like source wave.

Wave Lifecycle

Wave lifecycle are defined by the Status enumeration:

  1. Created : The Wave object has just been built by someone.
  2. Sent : The wave has been sent to the JRebirth Notifier Engine
  3. Processing : The wave is being dispatched
  4. Cancelled : The wave has been cancelled by an user action
  5. Consumed : All Wave Handlers have been called, or the Service Method or the Command has been called
  6. Handled : All Wave Handlers are terminated
  7. Failed : The wave process has generated an error
  8. Destroyed : the wave is available for garbage collection

How they are consumed

Chained Wave

It's possible to chain command by using the ChainWaveCommand class. A sample is used into the JRebirthThread.bootUp() method.