efs v. 0.5.0
API Specification
Introduction
efs - Event File System is envisioned as a reliable, robust, and low-latency event persistence and delivery API from publishing agent to subscribing agent.
"Envision" means that efs is not yet implemented to this point - but enough is implemented to warrant an initial release. The first is the dispatcher framework used to deliver events to agents in a virtual single-threaded manner. Virtual single-threading means that while an agent may run on different threads over its lifespan it is guaranteed to be accessed by only one thread at any given moment. This means there is no need for synchronization/locks which can lead to a thread losing core while waiting to acquire a lock.
The second component is the activator which uses dispatcher
to start and activate
activate agents
(an interface extension to
IEfsAgent)
Activator solves the problem where an agent is activated
on one thread where it connects into a reactive framework
but receives events on dispatcher threads
while still activating on the original thread.
The virtual single-threading guarantee provided by
dispatcher is lost in this scenario. Activator has agent
activation performed by the agent's dispatcher. Any events
posted to the agent while activating are delivered
after activation is completed.
Learning efs
efs package javadocs explain how to use the package together with example code. You are encourged to explore the javadoc packages in the following order:
-
dispatcher: explains dispatcher architecture and how to use. Compares efs dispatcher with LMAX Disruptor and SEDA (staged event driven architecture). -
dispatcher configuration: explains how to configure dispatchers using typesafe configuration bean classes stored in a JSON file format.Please note that efs uses typesafe for all its configuration.
-
timer: contains the {link org.efs.timer.EfsScheduledExecutor} which somewhat follows theScheduledExecutorServiceinterface but does not implement that interface because it does not deliver expired timers using aScheduledFuturebut instead usesEfsDispatcherfor delivery.An efs scheduled executor may be created either programmatically or by typesafe configuration file.
-
activator: this service steps efs agents through stopped, stand by, active states in a thread-safe manner using efs dispatcher's virtual single-thread environment. User definedworkflowsprovide the order in which efs agents are stepped through their states. -
activator configuration: explains how to define one or more activation workflows using a typesafe configuration file. -
logging: implements slf4jLoggerandLoggerFactorywithAsyncLoggerandAsyncLoggerFactory. This logging uses efs dispatcher to perform the actual logging on a dispatcher thread rather than inline with application code.
efs Background
efs is a direct descendent of the 25 year old eBus project. The goal here is to tease out the best of that work, forming a better API using Java 21 features. This work is not a re-implementation of eBus but a step beyond. efs is based on the oberservation that applications require:
- historic events,
- live events, and
- combination of historic and live events.
eBus started with live event distribution only. A later attempt to add historic events to eBus designed to fit into the eBus framework was less than satisfactory. Hence, a need for a new framework supporting both historic and live event distribution from the start.
Designing a new efs event persistence and distribution API is on-going. This initial release 0.1.0 provides the event delivery and processing API known as Dispatcher. It is similar to Disruptor and SEDA (staged event-driven architecture) but simpler. Dispatcher is designed to be a stand-alone API and useful in its own right.
- Author:
- Charles Rapp
EfsEventLayout class which provides a
reflective definition of an IEfsEvent
class.EfsScheduledExecutor
which encapsulates a
ScheduledExecutorService.