Counter
The Substrates API has two basic categories of Instrument interfaces. The first category includes Instrument interfaces that offer a direct means of interaction by a caller, resulting in an emittance of a value, becoming an Event if Subscribers are present. An example of this type of Instrument would be the calling of the inc method on a Counter interface. With such an Instrument type, the Conduit interface is used to look up by name an instance of the Instrument before interaction. Below is an example of such.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
// a named event queue/executor var circuit = cortex.circuit ( "name" ); // a fabricator of counter instruments var cartridge = Counters.counters (); // a container/channel for counters var counters = circuit.conduit ( cartridge ); // a named instance of a counter var counter = counters.instrument ( "name" ); // an interaction with a counter counter.inc (); |
Observer
The second type of Instrument is one with no direct means of triggering Event publishing in the interface. The interface merely distinguishes the Instrument type of the publisher, a Subject in the Substrates API. An example is the Observer interface.
|
1 2 3 4 5 6 7 8 9 10 |
/** * An interface that represents an instrument * that observes an aspect of an observable. */ @Provided public interface Observer < E > extends Instrument< E > { } |
Because there is no utility in looking up such an Instrument, a different means is employed in adding such Instruments into a Circuit. Instead of creating a Conduit, an Adjunct is created from a Cartridge. An Adjunct is a Component that offers access to a Source, allowing for subscribing to Events but not offering access to the Instruments that are the Subjects of the Events.
|
1 2 3 4 5 6 7 8 9 10 11 |
var cartridge = Observers.observers ( /* define an optic */ ); var observers = circuit.adjunct ( cartridge ); |
With an Adjunct, the triggering mechanism (sensor stimulus) is opaque, even though it might be sourced from a Circuit, which will be the case for an Observer as it consumes Events from other Instruments. An Adjunct Component is the means of integration with other Systems partially managed by the Substrates API, with the Component interface being an extension of the Resource interface.
The following circuitry setup defines an Observer Instrument that will emit the cumulative value for value emissions from a Counter Instrument. First, a Context, which the Conduit interface extends, is passed to the Cartridge function to allow access to a Source. The Source will be used to register a Subscriber to consume Events from Counters and map them into Events emitted by Observers.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
final var observers = circuit.adjunct ( Observers.observers ( counters, Selector.emission (), Bootstrap.of ( 0L ), Operant.of ( ( state, increment ) -> state + increment ) ) ); |
The second parameter selects the emission value, the increment, from the Event sourced from a Counter. The third parameter initializes the state maintained and published by the Observer. The final parameter is the Operant that is applied on each receipt of an Event and its selection. The value returned from the Operant function is kept in the state field across Event interceptions.
Outlet
With the above circuitry code in place, all that is left to test the Event pipeline processing is to hook up an Outlet that prints the cumulative value emitted by an Observer and to create a Counter that is incremented several times, as coded below.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
cortex.scope ( observers .source () .consume ( Outlet.of ( event -> System.out.printf ( "%s : %d%n", event .subject () .reference () .name (), event .emission () ) ) ) ).run ( () -> { final var counter = counters.instrument ( "name" ); for ( int i = 10; i > 0; i-- ) counter.inc (); circuit .current () .await (); } ) |
Running the above code, the following is printed to a terminal.
>_
name : 1
name : 2
name : 3
name : 4
name : 5
name : 6
name : 7
name : 8
name : 9
name : 10