Skip navigation links
eBus
v. 7.2.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 multi-subject feeds. Multi-subject 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-subject 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-Subject Feeds

eBus v. 4.5.0 introduced multi-subject feeds, one for each of the above four simple feeds. A multi-subject feed is not a true EFeed subclass but acts as a proxy between an application object and multiple subordinate feeds for the same message class. The multi-subject 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-subject feed is configured to work with a single notification/request message class and multiple message subjects. An application object needing a multi-subject feed for multiple message classes must open a different multi-subject feed for each message class.

The supported multi-subject feeds are:
  1. EMultiPublishFeed: uses EPublishFeed subordinate feeds.
  2. EMultiSubscribeFeed: uses ESubscribeFeed subordinate feeds.
  3. EMultiRequestFeed: uses ERequestFeed subordinate feeds.
  4. EMultiReplyFeed: uses EReplyFeed subordinate feeds.
See EMultiFeed for a detailed explanation on how to create and use multi-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 can transmit messages between each other using either TCP, UDP, or multicast connections.

eBus TCP/UDP Connection

TCP and UDP communication is encapsulated in an ERemoteApp instance. This instance is either created by the application direction to initiate a connection to another eBus application or is created by an EServer instance upon accepting a remotely initiated connection. ERemoteApp and EServer instances are created configuring an instance using the appropriate builder. For ERemoteApp the EConfigure.ConnectionBuilder is used (this builder instance is acquired using EConfigure.connectionBuilder()). EServer configuration is created using EConfigure.ServerBuilder (acquired using EConfigure.serverBuilder()). Once the configuration is successfully built then open the remote application or server instance using ERemoteApp.openConnection(net.sf.eBus.config.EConfigure.RemoteConnection) or EServer.openServer(net.sf.eBus.config.EConfigure.Service), respectively.

These instance may be created directly in application code or indirectly at application start using the command line option:

-Dnet.sf.eBus.net.config.jsonFile=<conf file path>

This will automatically open the remote client connections and servers on start up.

As of eBus release 6.0.0 Java properties are no longer supported with respect to eBus configuration. Only typesfafe JSON configuration files may be used.

Aside: it may appear strange the eBus has a EUDPServer since UDP is a session-less protocol. But eBus communication is session-based. So eBus adds a session layer on top of the UDP connection. The UDP connection initiator sends a UDP connect request message to the EUDPServer. A UDP connect reply is sent and, if the UDP connection is accepted, the random UDP port assigned to the connection which the initiating client should use for all further communication.

eBus also supports both secure TCP (using SSL/TLS) and secure UDP (using DTLS) for remote connections. But this option is not supported in configuration file since that would require placing sensitive information into the JSON .conf file in the clear.

eBus UDP Multicast Connection

eBus allows notification messages to be transmitted between applications. Since Multicast is session-less and cannot easily be turned into a session-based protocol eBus handles multicasting differently.

There are two types of multicast connections: multicast publisher and multicast subscriber. The multicast publisher uses an eBus multi-feed subscription to receive the desired notification messages. These notifications must be locally published with either EFeed.FeedScope.LOCAL_AND_REMOTE or EFeed.FeedScope.REMOTE_ONLY feed scope. The multicast publisher multicasts via McastKeyMessage the message key (message class and subject), unique integer message key identifier, and the message feed state (up or down). Locally published notifications are mulicast immediately upon receipt. Note that the multicast publisher does not track whether there are any remote eBus applications joined to the multicast group and subscribed to the message key. Local notifications are sent no matter what.

Multicast subscriber is the opposite: it takes notifications from the multicast group and uses a publisher multi-feed to inject the message into eBus. Upon successfully joining the configured multicast group the multicast subscriber posts a McastSubscribeMessage which causes all the joined multicast publishers to transmit their current feed status messages. Multicast subscriber publish feeds have a EFeed.FeedScope.REMOTE_ONLY scope.

Multicast publishers and subscribers are configured at start to support a defined set of message keys. This set cannot be altered once the multicast instance is created. That said, there is one way to dynamically add new subjects to a multicast instance: by have that instance use a query-based multi-feed. As new subject feeds come on line the multicast instance will either publish or receive the subject feed via the multicast group.

Monitoring eBus Connections

eBus reports the latest connection, server, and multicast status using using the ConnectionMessage, ServerMessage, and MulticastMessage messages, respectively. To track connection status create an ESubscriber which subscribes to the appropriate message key for the desired connection type. Status messages will be sent to the subscribe feed callback method. The status message keys for the supported eBus connection types are:

Exhausting eBus Messages

An application may need to persist all messages passing through a local eBus. It is not feasible to have a persistence mechanism in each application object sending or receiving eBus messages. eBus v. 6.2.0 provides a mechanism to exhaust all local messages to a persistent store via the IMessageExhaust interface.

An application needing to persist all local messages accomplishes this by implementing this interface and registering an IMessageExhaust instance with ESubject.setExhaust(net.sf.eBus.client.IMessageExhaust). This application exhaust is called via an eBus dispatcher thread so as not to interfere with message delivery.

Note that only one exhaust may be registered at a time. If an application needs to persist a message in multiple stores, then that must be done by the single application exhaust. If an application does not want to exhaust all messages, that filtering must be done by the application exhaust. If IMessageExhaust.exhaust(net.sf.eBus.messages.EMessage) should throw an exception (whether deliberate or not), that exception will be caught and logged as a warning.

Note: an application using this exhaust API is responsible for opening and closing the persistent store when appropriate.

The default message exhaust does nothing with the message.

Skip navigation links
eBus
v. 7.2.0

Copyright © 2001 - 2024. Charles W. Rapp. All rights reserved.