Skip navigation links
eBus
4.5.0

Package net.sf.eBus.client

This package contains the top-level eBus API which applications use to interact with eBus.

See: Description

Package net.sf.eBus.client Description

This package contains the top-level eBus API which applications use to interact with eBus. This interaction is done through EFeed objects. All feed objects are associated with a unique type+topic message key.

Message Key Dictionary

eBus v. 4.5.0 added the ability to directly add messages keys to the eBus message key dictionary and retrieve keys from said dictionary. Prior to this version, message keys were indirectly added to the dictionary when opening feeds. This feature added to support the new multikey feeds. Multi-key feeds may use a query to match a variable number of keys. This is why EFeed#addKey(net.sf.eBus.messages.EMessageKey), EFeed#addAllKeys(java.util.Collection) and EFeed#loadKeys(java.io.ObjectInputStream) methods are provided: unless the message key dictionary is populated with keys prior to creating a multi-key query feed, the query would find no matching keys.

Simple Feeds

A simple feed is associated with a single message key and messages are sent to or received from the feed only after the feed is opened and advertised/subscribed. Simple feeds provide no value added capabilities beyond this.

  1. EPublishFeed: Publishers advertise and publish notification messages via a publish feed instance.
  2. ESubscribeFeed: Subscribers hook into this feed to receive notification messages.
  3. EReplyFeed: Repliers advertise their ability to send reply messages in response to a request messages.
    Note that replies are sent back using a EReplyFeed.ERequest and not the EReplyFeed.
  4. ERequestFeed: Requestors place request messages and receive replies using the request feed.

Multi-Key Feeds

eBus v. 4.5.0 introduced multi-key feeds, one for each of the above four simple feeds. A multi-key feed is not a true EFeed subclass but acts as a proxy between an application object and multiple subordinate feeds. The multi-key feed is responsible for keeping the subordinate feeds in the same state (opened, advertised/subscribed, un-advertised/un-subscribed, closed), configuring the subordinate feeds with the same callbacks.

A multi-key feed is configured to work with a single notification/request message class and multiple message subjects. An application object needing a multi-key feed for multiple message classes must open a different multi-key feed for each message class.

The supported multi-key feeds are:
  1. EMultiKeyPublishFeed: uses EPublishFeed subordinate feeds.
  2. EMultiKeySubscribeFeed: uses ESubscribeFeed subordinate feeds.
  3. EMultiKeyRequestFeed: uses ERequestFeed subordinate feeds.
  4. EMultiKeyReplyFeed: uses EReplyFeed subordinate feeds.

Roles

Each of the above feeds has a matching interface which an application class must implement if it is to work with that feed type:

eBus v. 4.2.0 added support for using Java lambda expressions as a callback target. An application still must implement the matching role interface for a given feed but is not required to override interface methods. Instead, an application uses Java lambda expressions to define the callback target. See FeedStatusCallback, NotifyCallback, ReplyCallback, and RequestCallback for more information.

Remote Communication

eBus applications may communicate with one another by establishing TCP connections between them. This is done by having one eBus application open a EServer on a configurable port and the other eBus application open a ERemoteApp to the first application's host address and server port. Note that only one connection is allowed between eBus applications. eBus applications are not allowed to both open server ports and both establish a remote connection to the other.

(Note that all eBus applications are allowed to open an EServer port. But if an eBus application attempts to connect to another application and a connection already exists, then the second connection will be automatically closed.)

An application can monitor eBus connections by creating an ESubscriber which subscribes to ServerMessage.MESSAGE_KEY for EServer events and ConnectionMessage.MESSAGE_KEY for ERemoteApp events.

Applications may configure eBus using EConfigure. This can be done programmatically, using a properties file, or user preference. See EConfigure document for a detailed explanation.

Skip navigation links
eBus
4.5.0