Package net.sf.eBus.client

Class EFeed

  • All Implemented Interfaces:
    IEFeed
    Direct Known Subclasses:
    EMultiFeed, ENotifyFeed, EPatternFeed, EReplyFeed, EReplyFeed.ERequest, ERequestFeed, ERequestFeed.ERequest, ERequestMonitorFeed
    public abstract class EFeed
extends java.lang.Object
implements IEFeed
    Applications interface with eBus through feed instances. An application class implements the eBus interface associated with the feed (for example, EPublisher for EPublishFeed), opens a feed instance, and then activates the feed. The feed can be activated, deactivated multiple times. Once the feed is closed, the feed instance cannot be used again. A new feed instance must be opened again.

    An application defines a feed's scope when opening the feed. This scope defines the feed's visibility. That feed may be visible only within the local JVM, within both local and remote JVMs, and in remote JVMs only. For example, if a subscription feed has local-only scope, then it will receive notifications from local publisher feeds only. Notifications from remote publishers will not be forwarded to the local-only subscriber. The following table shows the interface between feed scopes:

    Feed Scope
    Local Only Local & Remote Remote Only
    Local Only Match Match No match
    Local & Remote Match Match Match
    Remote Only No match Match No match

    (Notice that a remote feed may only support a local & remote feed and not other remote only feeds.)

    Feed scope gives the application developer control over how "far" a message will go. If a notification message is intended to stay within a JVM, both the publish and subscribe feeds may be set to a local only scope. If a notification is meant for remote access only, the the publish feed is set to remote only scope. These examples also apply to request/reply feeds.

    eBus calls an application instance back from only one thread at any given time. While that thread may change over time, only one eBus thread will callback the application instance at any given time. The eBus API is thread-safe and an application may call eBus methods from multiple, simultaneous threads. The benefit of this model is that if an application instance is accessed only by eBus only and not by any other non-eBus thread, then the application instance is effectively single-threaded. Such an application instance does not need to use synchronized keyword or locks, simplifying the application class implementation.

    A feed maintains a weak reference to the application instance. If the application is finalized while still owning open feeds, those feeds will be automatically closed when eBus detects this finalization.

    Each feed is assigned a identifier that is unique within the application instance scope and feed lifespan. Once a feed is closed, its identifier is recycled. Put in another way: an application instance's active feeds all have unique integer identifiers. These identifiers are not unique across different application instances. These identifiers are not unique across an application instance lifespan if that instance opens and closes feeds multiple times. It is likely that newly opened feed will have the same identifier as a previously closed feed.

    The eBus API is intended to be extended with new feed subclasses. These extensions would provide more sophisticated notification and request/reply types. One example is a notification feed that combines historical and live updates or just historical, depending on what the subscriber requests. This allows a subscriber to join the feed at any time, not missing any previously posted notifications.

    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 EMultiPublishFeed, EMultiSubscribeFeed, and EMultiReplyFeed. Multi-subject feeds may use a query to match a variable number of keys. This is why addKey(EMessageKey), addAllKeys(java.util.Collection) and loadKeys(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.

    Multi-subject feeds act as proxies between the application client and the individual EPublishFeed, ESubscribeFeed, ERequestFeed and EReplyFeed in the multi-subject feed. The multi-subject feed opens, advertises/subscribes, and closes all subordinate feeds in unison. The individual feeds all reference the same client and client callback methods. If a multi-subject feed is for 100 subjects, then the client receives callbacks from all 100 subordinate feed and not for the single multi-subject feed.

    Note: a multi-subject feed is not EFeed subclass. However, multi-subject feed behavior is the same as an EFeed and may be treated by the application as if it were an EFeed.

    Author:
    Charles W. Rapp
    See Also:
    ESubject, ENotifyFeed, EPublishFeed, ESubscribeFeed, ERequestFeed, EReplyFeed, EMultiPublishFeed, EMultiSubscribeFeed, EMultiRequestFeed, EMultiReplyFeed

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected EFeed​(EClient client, EFeed.FeedScope feedScope)
      Creates an eBus feed for the given client subject, scope, and feed type.
      protected EFeed​(EFeed.Builder<?,​?,​?> builder)
      Creates an eBus feed based on the given builder configuration.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static void addAllKeys​(java.util.Collection<EMessageKey> keys)
      Adds the given message key collection to the message key dictionary if all keys are not null and reference notification and/or request messages.
      static void addKey​(EMessageKey key)
      Adds key to the eBus message key dictionary if key is not already defined.
      static void addListener​(ISubjectListener l)
      Adds the given subject listener to the listeners list.
      protected static void checkScopes​(EMessageKey key, EFeed.FeedScope scope)
      Checks if the message scope and feed scope are in agreement.
      int clientId()
      Returns the feed client identifier.
      java.lang.String clientName()
      Returns feed client name as set by eBus object.
      void close()
      Closes this feed, marking it as inactive.
      static void createDispatcher​(EConfigure.Dispatcher dispatcher)
      Creates a new client dispatcher run queue based on the given configuration.
      static java.lang.String defaultDispatcher()
      Returns the eBus default dispatcher's name.
      EClient eClient()
      Returns the eBus client referenced by this feed.
      boolean equals​(java.lang.Object o)
      Returns true if o is a non-null EFeed instance with equal client and feed identifiers.
      int feedId()
      Returns the unique feed identifier.
      EFeedState feedState()
      Returns the current feed state.
      static java.util.List<EMessageKey> findKeys()
      Returns a non-null, possibly empty, message key list taken from the current message key dictionary entries.
      static java.util.List<EMessageKey> findKeys​(java.lang.Class<? extends EMessage> mc)
      Returns a list containing message keys for the given message class found in the message key dictionary.
      static java.util.List<EMessageKey> findKeys​(java.lang.Class<? extends EMessage> mc, Pattern query)
      Returns a list containing message keys for the given message class and subject pattern found in the message key dictionary.
      int hashCode()
      Returns the hash of the client and feed identifiers.
      protected abstract void inactivate()
      Closes the feed.
      boolean inPlace()
      Returns true if this feed is "in place" (subscribed or advertised) and false otherwise.
      boolean isActive()
      Returns true if this feed is still active and false if inactive.
      boolean isFeedUp()
      Returns true if the feed state is EFeedState.UP; otherwise, returns false.
      protected boolean isOverridden​(java.lang.String methodName, java.lang.Class<?>... params)
      Returns true if the application object stored in EClient defines a method with the given name and parameters.
      static void loadKeys​(java.io.ObjectInputStream ois)
      Reads the message keys contained in the given object input stream and loads them back into the eBus message key dictionary.
      EClient.ClientLocation location()
      Returns the feed client JVM location: local to this JVM or in a remote JVM.
      static void register​(EObject client)
      Registers the application object client with eBus, assigning the client to the dispatcher configured for the client's class, and using the defined EObject.startup() and EObject.shutdown() methods.
      static void register​(EObject client, java.lang.String dispatcherName)
      Registers the application object client with eBus, assigning client to the named dispatcher.
      static void register​(EObject client, java.lang.String dispatcherName, java.lang.Runnable startCb, java.lang.Runnable shutdownCb)
      Registers the application object client with eBus, assigning client to the named dispatcher.
      static void removeListener​(ISubjectListener l)
      Removes subject listener from the listeners list.
      EFeed.FeedScope scope()
      Returns the feed scope: local only, local & remote, or remote only.
      static void setExhaust​(IMessageExhaust exhaust)
      Sets the message exhaust to the given instance.
      static void shutdown​(java.util.List<? extends EObject> clients)
      Call the registered shutdown method for each of the application objects in clients if-and-only-if the application object is currently started.
      static void shutdown​(EObject client)
      Calls the shutdown method registered with eBus if-and-only-if the application object is currently started.
      static void shutdownAll()
      Calls the shutdown method for all currently registered application objects which are currently started. This method is generally called by an application just prior to shutting down.
      static void startup​(java.util.List<? extends EObject> clients)
      Call the registered start-up method for each of the application objects in clients if-and-only-if the application object is not currently started.
      static void startup​(EObject client)
      Calls the start-up method registered with eBus if-and-only-if the application object is not currently started.
      static void startupAll()
      Calls the start-up method for all currently registered application objects which are not currently started. This method is generally called from an application's static main method after having created and registered the application's eBus objects.
      static void storeKeys​(java.io.ObjectOutputStream oos)
      Writes the entire message key dictionary to the given object output stream.
      static void storeKeys​(java.lang.Class<? extends EMessage> mc, java.io.ObjectOutputStream oos)
      Write those message keys associated with the given message class to the object output stream.
      static void storeKeys​(java.lang.Class<? extends EMessage> mc, Pattern query, java.io.ObjectOutputStream oos)
      Write those message keys associated with the given message class and a subject matching the regular expression to the object output stream.
      protected static int subclassDistance​(java.lang.Class<?> subclass, java.lang.Class<?> bc)
      Returns the distance between the given subclass and base class.
      java.lang.String toString()
      Returns a containing the feed message key and data member values.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface net.sf.eBus.client.IEFeed

        key

    • Field Detail

      • NO_CONDITION

        public static final ECondition NO_CONDITION
        The default condition always returns true. This default is used so that a notification subscription and request advertisement always have a non-null condition, removing the need for a if condition in message routing code, which improves JIT performance.

      • FEED_IS_INACTIVE

        public static final java.lang.String FEED_IS_INACTIVE
        Message associated with attempting to use an inactive message feed.
        See Also:
        Constant Field Values

      • FEED_NOT_ADVERTISED

        public static final java.lang.String FEED_NOT_ADVERTISED
        Message associated with attempting to use an unadvertised message feed.
        See Also:
        Constant Field Values

      • NULL_CLIENT

        public static final java.lang.String NULL_CLIENT
        Message associated with using a null EClient .
        See Also:
        Constant Field Values

      • mEClient

        protected final EClient mEClient
        The client owning this feed. EClient maintains a weak reference to the application instance.

      • mScope

        protected final EFeed.FeedScope mScope
        The feed scope is either limited to this local JVM only, remote JVMs only, and both local and remote JVMs.

      • mIsActive

        protected final java.util.concurrent.atomic.AtomicBoolean mIsActive
        Returns true if this feed is active, meaning that it can still be used by the client. Returns false if this feed is inactive and cannot be used by the client again. Once a feed is made inactive, it cannot become active again.

      • mInPlace

        protected boolean mInPlace
        Set to true when this feed is connected to its subject. Initialized to false.

      • mFeedId

        protected final int mFeedId
        Immutable identifier unique within the client. In other words, two feeds for two different EClient instances may have the same mFeedId.

      • mFeedState

        protected EFeedState mFeedState
        Tracks whether this feed is active or inactive. Feed state is independent of being in place. Whether a feed is in place or not, this feed may or may not be active.

    • Constructor Detail

      • EFeed

        protected EFeed​(EClient client,
                EFeed.FeedScope feedScope)
        Creates an eBus feed for the given client subject, scope, and feed type. All callback tasks are posted to client's run queue.
        Parameters:
        client - post eBus tasks to this client.
        feedScope - this feed supports either local, local & remote, or just remote feeds.

      • EFeed

        protected EFeed​(EFeed.Builder<?,​?,​?> builder)
        Creates an eBus feed based on the given builder configuration.
        Parameters:
        builder - contains feed configuration.

    • Method Detail

      • inactivate

        protected abstract void inactivate()
        Closes the feed. Performs all necessary work to clean up this feed.

      • feedId

        public final int feedId()
        Returns the unique feed identifier. The uniqueness is limited to within the client and for the feed lifespan only. When a feed is closed, the feed identifier may be reused.
        Specified by:
        feedId in interface IEFeed
        Returns:
        the feed identifier.

      • scope

        public final EFeed.FeedScope scope()
        Returns the feed scope: local only, local & remote, or remote only.
        Specified by:
        scope in interface IEFeed
        Returns:
        feed scope.

      • eClient

        public final EClient eClient()
        Returns the eBus client referenced by this feed.
        Specified by:
        eClient in interface IEFeed
        Returns:
        eBus client.

      • isActive

        public final boolean isActive()
        Returns true if this feed is still active and false if inactive. Clients may only use active feeds. Once a feed is closed, it is marked inactive and may not be used by the client again.

        Once a feed is closed, the unique feed identifier may be reused by a newly opened feed.

        Specified by:
        isActive in interface IEFeed
        Returns:
        true if this feed is active.
        See Also:
        close()

      • inPlace

        public final boolean inPlace()
        Returns true if this feed is "in place" (subscribed or advertised) and false otherwise.
        Specified by:
        inPlace in interface IEFeed
        Returns:
        true if the feed is in place.

      • isFeedUp

        public boolean isFeedUp()
        Returns true if the feed state is EFeedState.UP; otherwise, returns false.
        Specified by:
        isFeedUp in interface IEFeed
        Returns:
        true if the feed state is up.

      • feedState

        public final EFeedState feedState()
        Returns the current feed state. A down state means that messages may not be sent on or received from this feed. An up state means that messages may possibly be sent on or received from this feed.
        Specified by:
        feedState in interface IEFeed
        Returns:
        current feed state.

      • close

        public void close()
        Closes this feed, marking it as inactive. If this feed is activated, then the feed is de-activated first. The feed unique identifier is returned to the available feed identifier pool and may be assigned to a newly opened feed.

        If this feed is already inactive, then does nothing.

        Specified by:
        close in interface IEFeed

      • equals

        public boolean equals​(java.lang.Object o)
        Returns true if o is a non-null EFeed instance with equal client and feed identifiers. Otherwise returns false.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - comparison object.
        Returns:
        true if o is a non-null EFeed instance with equal client and feed identifiers.

      • hashCode

        public int hashCode()
        Returns the hash of the client and feed identifiers.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        hash based on the client and feed identifiers.

      • toString

        public java.lang.String toString()
        Returns a containing the feed message key and data member values.
        Overrides:
        toString in class java.lang.Object
        Returns:
        textual representation of this feed.

      • clientId

        public final int clientId()
        Returns the feed client identifier. This identifier is guaranteed unique for the application instance's lifespan. The identifier is re-used once eBus detects that the application instance is finalized. This integer identifier may be used by two different application instances over the application run time but only if the two instances do not exist at the same time.
        Returns:
        unique client identifier.

      • clientName

        public final java.lang.String clientName()
        Returns feed client name as set by eBus object.
        Returns:
        feed client name.

      • defaultDispatcher

        public static java.lang.String defaultDispatcher()
        Returns the eBus default dispatcher's name. Used when registering a client to the default dispatcher.
        Returns:
        default dispatcher name.

      • findKeys

        public static java.util.List<EMessageKey> findKeys()
        Returns a non-null, possibly empty, message key list taken from the current message key dictionary entries.
        Returns:
        list message key dictionary entries.

      • findKeys

        public static java.util.List<EMessageKey> findKeys​(java.lang.Class<? extends EMessage> mc)
        Returns a list containing message keys for the given message class found in the message key dictionary. The message class should reference either a notification or request message class since only those classes are stored in the message key dictionary. If this is not the case, then an empty list is returned.
        Parameters:
        mc - message class.
        Returns:
        a non-null and possibly empty message key list.

      • findKeys

        public static java.util.List<EMessageKey> findKeys​(java.lang.Class<? extends EMessage> mc,
                                                   Pattern query)
        Returns a list containing message keys for the given message class and subject pattern found in the message key dictionary. The message class should reference either a notification or request message class since only those classes are stored in the message key dictionary. If this is not the case, then an empty list is returned.
        Parameters:
        mc - message class.
        query - message subject regular expression query.
        Returns:
        a non-null and possibly empty message key list.

      • addListener

        public static void addListener​(ISubjectListener l)
        Adds the given subject listener to the listeners list. Does nothing if the listener is already registered.
        Parameters:
        l - add this subject listener.

      • removeListener

        public static void removeListener​(ISubjectListener l)
        Removes subject listener from the listeners list.
        Parameters:
        l - remove this subject listener.

      • addKey

        public static void addKey​(EMessageKey key)
        Adds key to the eBus message key dictionary if key is not already defined. key must reference either a notification or request message since only those message keys are stored in the message key dictionary.
        Parameters:
        key - add this message key to the subject
        Throws:
        java.lang.IllegalArgumentException - if key is null or does not reference either a ENotificationMessage or ERequestMessage.

      • addAllKeys

        public static void addAllKeys​(java.util.Collection<EMessageKey> keys)
        Adds the given message key collection to the message key dictionary if all keys are not null and reference notification and/or request messages. Put conversely, if keys contains a null or non-notification/ request key, then none of the keys is placed into the message key dictionary.

        The listed keys must reference either a notification or request message since only those message keys are stored in the message key dictionary. The list may consist of a mixture of notification and request message keys.

        Parameters:
        keys - put these notification and/or request message keys into the message key dictionary.
        Throws:
        java.lang.IllegalArgumentException - if keys contains a null or does not reference either a ENotificationMessage or ERequestMessage.

      • setExhaust

        public static void setExhaust​(IMessageExhaust exhaust)
        Sets the message exhaust to the given instance. All notification, request, and reply messages passing through the local eBus are passed to exhaust via a dispatch thread. Caller is responsible for opening and closing the exhaust's underlying persistent store appropriately.

        Note: only one exhaust may be configured at a time. When this method is called, the current exhaust is replace with exhaust. If an application requires messages to be persisted to multiple destinations, then that must be done via the single application exhaust.

        If exhaust is null then the default exhaust is used. This default does nothing with the given message.

        Parameters:
        exhaust - message exhaust message. Passing in null results in the default exhaust being used.

      • createDispatcher

        public static void createDispatcher​(EConfigure.Dispatcher dispatcher)
        Creates a new client dispatcher run queue based on the given configuration. This method allows new dispatcher run queues to be created dynamically post-JVM start. Normally dispatcher configurations are contained in an eBus configuration file and loaded at JVM start using the Java command line option -Dnet.sf.eBus.config.jsonFile=<config file path>. This technique guarantees that eBus Dispatchers are in place prior to assigned eBus clients to a Dispatcher. But if this is not possible, then createDispatcher may be used to create a Dispatcher dynamically. But care must be taken to make sure this is done prior to registering an eBus client to that Dispatcher.

        See EConfigure.Dispatcher and EConfigure.DispatcherBuilder for detailed information on how dispatchers work and how to build a dispatcher configuration.

        Parameters:
        dispatcher - dispatcher configuration.
        Throws:
        java.lang.NullPointerException - if dispatcher is null.
        java.lang.IllegalStateException - if a dispatcher named EConfigure.ThreadConfig.name() already exists.
        See Also:
        EConfigure.Dispatcher, EConfigure.DispatcherBuilder, EConfigure.dispatcherBuilder()

      • register

        public static void register​(EObject client)
        Registers the application object client with eBus, assigning the client to the dispatcher configured for the client's class, and using the defined EObject.startup() and EObject.shutdown() methods. Once registered, client may be started using the startup(EObject) or startup(List) methods.

        Note: this method must be called before client opens any feeds. Failure to do so results in a thrown IllegalStateException.

        Parameters:
        client - register this application object with eBus.
        Throws:
        java.lang.NullPointerException - if client is null.
        java.lang.IllegalStateException - if client is already registered with eBus. This will happen if client has opened any feeds prior to making this call.
        See Also:
        register(EObject, String), register(EObject, String, Runnable, Runnable), startup(EObject), shutdown(EObject)

      • register

        public static void register​(EObject client,
                            java.lang.String dispatcherName)
        Registers the application object client with eBus, assigning client to the named dispatcher. This method allows individual application objects to be assigned to a dispatcher rather than by class. The purpose here is to allow objects within a class to be assigned to different dispatchers based on application need. That is, certain objects may be assigned to a higher priority dispatcher and the rest assigned to a lower priority dispatcher.

        Once registered, client may be started by calling startup(EObject) or startup(List) methods which, in turn, calls the defined EObject.startup() method.

        Note: this method must be called before client opens any feeds. Failure to do so results in a thrown IllegalStateException.

        Parameters:
        client - register this application client with eBus.
        dispatcherName - the dispatcher name.
        Throws:
        java.lang.NullPointerException - if client is null or dispatcherName is null
        java.lang.IllegalArgumentException - if dispatcherName is empty or does not reference a configured dispatcher.
        java.lang.IllegalStateException - if client is already registered with eBus. This will happen if client has opened any feeds prior to making this call.

      • register

        public static void register​(EObject client,
                            java.lang.String dispatcherName,
                            java.lang.Runnable startCb,
                            java.lang.Runnable shutdownCb)
        Registers the application object client with eBus, assigning client to the named dispatcher. This method allows individual application objects to be assigned to a dispatcher rather than by class. The purpose here is to allow objects within a class to be assigned to different dispatchers based on application need. That is, certain objects may be assigned to a higher priority dispatcher and the rest assigned to a lower priority dispatcher.

        Once registered, client may be started by calling startup(EObject) or startup(List) methods which, in turn, calls startCb.

        Note: this method must be called before client opens any feeds. Failure to do so results in a thrown IllegalStateException.

        Parameters:
        client - register this application client with eBus.
        dispatcherName - the dispatcher name.
        startCb - client start-up method callback.
        shutdownCb - client shutdown method callback.
        Throws:
        java.lang.NullPointerException - if any of the arguments is null.
        java.lang.IllegalArgumentException - if dispatcherName is either an empty string or does not reference a known dispatcher.
        java.lang.IllegalStateException - if client is already registered with eBus. This will happen if client has opened any feeds prior to making this call.

      • startup

        public static void startup​(EObject client)
        Calls the start-up method registered with eBus if-and-only-if the application object is not currently started. If application object is started, then the start-up method will not be called again.

        Note: it is possible to start an application object multiple times if that object is shut down between each start.

        The start-up method is called from within the context of the object's run queue. Because the application object is started on an eBus thread, the start-up method will not be run concurrently with any other eBus callback.

        Parameters:
        client - start this eBus client.
        Throws:
        java.lang.NullPointerException - if client is null.
        java.lang.IllegalStateException - if client is not registered with eBus.
        See Also:
        register(EObject), register(EObject, String), register(EObject, String, Runnable, Runnable), startup(List), startupAll(), shutdown(EObject), shutdown(List), shutdownAll()

      • startup

        public static void startup​(java.util.List<? extends EObject> clients)
        Call the registered start-up method for each of the application objects in clients if-and-only-if the application object is not currently started. If any of the applications is currently started, then that objects start-up method will not be called again.

        Note: it is possible to start an application object multiple times if that object is shut down between each start.

        The start-up method is called from within the context of the object's run queue. Because the application object is started on an eBus thread, the start-up method will not be run concurrently with any other eBus callback.

        Parameters:
        clients - start these eBus clients.
        Throws:
        java.lang.NullPointerException - if clients is null or contains a null entry.
        java.lang.IllegalStateException - if clients contains an entry that is not registered with eBus.
        See Also:
        register(EObject), register(EObject, String), register(EObject, String, Runnable, Runnable), startup(EObject), startupAll(), shutdown(EObject), shutdown(List), shutdownAll()

      • startupAll

        public static void startupAll()
        Calls the start-up method for all currently registered application objects which are not currently started. This method is generally called from an application's static main method after having created and registered the application's eBus objects.

        Note: it is possible to start an application object multiple times if that object is shut down between each start.

        The start-up method is called from within the context of the object's run queue. Because the application object is started on an eBus thread, the start-up method will not be run concurrently with any other eBus callback.

        See Also:
        register(EObject), register(EObject, String), register(EObject, String, Runnable, Runnable), startup(EObject), startup(List), shutdown(EObject), shutdown(List), shutdownAll()

      • shutdown

        public static void shutdown​(EObject client)
        Calls the shutdown method registered with eBus if-and-only-if the application object is currently started. If application object is not started, then the shutdown method will not be called again.

        Note: it is possible to shut down an application object multiple times if that object is started up between each shutdown.

        The shutdown method is called from within the context of the object's run queue. Because the application object is stopped on an eBus thread, the shutdown method will not be run concurrently with any other eBus callback.

        Parameters:
        client - stop this eBus client.
        Throws:
        java.lang.NullPointerException - if client is null.
        java.lang.IllegalStateException - if client is not registered with eBus.
        See Also:
        register(EObject), register(EObject, String), register(EObject, String, Runnable, Runnable), startup(EObject), startup(List), startupAll(), shutdown(List), shutdownAll()

      • shutdown

        public static void shutdown​(java.util.List<? extends EObject> clients)
        Call the registered shutdown method for each of the application objects in clients if-and-only-if the application object is currently started. If any of the applications is not currently started, then that objects shutdown method will not be called again.

        Note: it is possible to shut down an application object multiple times if that object is started up between each shutdown.

        The shutdown method is called from within the context of the object's run queue. Because the application object is stopped on an eBus thread, the shutdown method will not be run concurrently with any other eBus callback.

        Parameters:
        clients - stop these eBus clients.
        Throws:
        java.lang.NullPointerException - if clients is null or contains a null entry.
        java.lang.IllegalStateException - if clients contains an entry that is not registered with eBus.
        See Also:
        register(EObject), register(EObject, String), register(EObject, String, Runnable, Runnable), startup(EObject), startup(List), startupAll(), shutdown(EObject), shutdownAll()

      • storeKeys

        public static void storeKeys​(java.io.ObjectOutputStream oos)
                      throws java.io.IOException
        Writes the entire message key dictionary to the given object output stream. Only message keys are written to the object output stream. The associated eBus subjects and their related feeds are not stored. When the message key is re-loaded from the object stream at application start, the eBus subjects are recreated but not the feeds. Feeds must be re-opened by the application upon start.

        Caller is responsible for opening oos prior to calling this method and closing oos after this method returns.

        Parameters:
        oos - load message keys to this object output stream.
        Throws:
        java.io.IOException - if an error occurs writing message keys to oos.
        See Also:
        storeKeys(Class, ObjectOutputStream), storeKeys(Class, Pattern, ObjectOutputStream), loadKeys(ObjectInputStream)

      • storeKeys

        public static void storeKeys​(java.lang.Class<? extends EMessage> mc,
                             java.io.ObjectOutputStream oos)
                      throws java.io.IOException
        Write those message keys associated with the given message class to the object output stream. Only message keys are written to the object output stream. The associated eBus subjects and their related feeds are not stored. When the message key is re-loaded from the object stream at application start, the eBus subjects are recreated but not the feeds. Feeds must be re-opened by the application upon start.

        Caller is responsible for opening oos prior to calling this method and closing oos after this method returns.

        Parameters:
        mc - store message keys with this message class.
        oos - load message keys to this object output stream.
        Throws:
        java.io.IOException - if an error occurs writing message keys to oos.
        See Also:
        storeKeys(ObjectOutputStream), storeKeys(Class, Pattern, ObjectOutputStream), loadKeys(ObjectInputStream)

      • storeKeys

        public static void storeKeys​(java.lang.Class<? extends EMessage> mc,
                             Pattern query,
                             java.io.ObjectOutputStream oos)
                      throws java.io.IOException
        Write those message keys associated with the given message class and a subject matching the regular expression to the object output stream. Only message keys are written to the object output stream. The associated eBus subjects and their related feeds are not stored. When the message key is re-loaded from the object stream at application start, the eBus subjects are recreated but not the feeds. Feeds must be re-opened by the application upon start.

        Caller is responsible for opening oos prior to calling this method and closing oos after this method returns.

        Parameters:
        mc - store message keys with this message class.
        query - store message keys with a subject matching this regular expression.
        oos - load message keys to this object output stream.
        Throws:
        java.io.IOException - if an I/O error occurs when storing the message keys.
        See Also:
        storeKeys(ObjectOutputStream), storeKeys(Class, ObjectOutputStream), loadKeys(ObjectInputStream)

      • loadKeys

        public static void loadKeys​(java.io.ObjectInputStream ois)
                     throws java.io.IOException
        Reads the message keys contained in the given object input stream and loads them back into the eBus message key dictionary. eBus subjects are re-created but not their associated feeds. The application is responsible for re-opening feeds when the application starts.

        Message keys defined prior to calling this method are not overwritten or replaced by duplicates loaded from the object input stream.

        Caller is responsible for opening ois prior to calling this method and closing ois after this method returns.

        Parameters:
        ois - read in message keys from this object input stream.
        Throws:
        java.io.IOException - if an I/O error occurs reading in the

      • isOverridden

        protected final boolean isOverridden​(java.lang.String methodName,
                                     java.lang.Class<?>... params)
        Returns true if the application object stored in EClient defines a method with the given name and parameters. Returns false if the application object does not define the method or inherits a default implementation of the method.
        Parameters:
        methodName - method name.
        params - method parameters.
        Returns:
        true if clazz overrides the method.

      • checkScopes

        protected static void checkScopes​(EMessageKey key,
                                  EFeed.FeedScope scope)
        Checks if the message scope and feed scope are in agreement. That is, if the message scope is local-only but the feed scope is not, then throws an IllegalArgumentException.
        Parameters:
        key - message key.
        scope - feed scope.
        Throws:
        java.lang.IllegalArgumentException - if key scope is local-only and scope is not FeedScope.LOCAL_ONLY.

      • subclassDistance

        protected static int subclassDistance​(java.lang.Class<?> subclass,
                                      java.lang.Class<?> bc)
        Returns the distance between the given subclass and base class. If a direct subclass of base class, then the returned value is one. If not a subclass of base class, then the returned value is < zero.
        Parameters:
        subclass - check if this class is descended from the base class.
        bc - base class.
        Returns:
        distance from subclass to base class or < zero if subclass is not descended from bc.