Package nl.tudelft.simulation.naming.context.event

Class ContextEventProducerImpl

  • All Implemented Interfaces:
    Serializable, Remote, EventListener, EventListener, EventProducer
    public class ContextEventProducerImpl
extends LocalEventProducer
implements EventListener
    ContextEventProducerImpl carries out the implementation for the EventContext classes. The class registers as a listener on the root of the InitialEventContext or the RemoteEventContext. Whenever sub-contexts are added (these will typically not be of type EventContext, but rather of type JVMContext, FileContext, RemoteContext, or other), this class also registers as a listener on these sub-contexts. Thereby, it remains aware of all changes happening in the sub-contexts of which it may be notified.

    For listening, four different ContextScope options exist:
    • OBJECT_SCOPE: listen to the changes in the object. OBJECT_SCOPE can be applied to regular objects and to context objects. When the object is at a leaf position in the tree, OBJECT_CHANGED events will be fired to the listener(s) on a change of the leaf object, and OBJECT_REMOVED events when the leaf is removed from the context. When the object is a context, OBJECT_REMOVED is fired when the sub-context is removed from its parent context.
    • LEVEL_SCOPE: fires events when changes happen in the provided context. LEVEL_SCOPE can only be applied to context objects. OBJECT_ADDED is fired when an object (context or leaf) is added to the context; OBJECT_REMOVED when an object (context or leaf) is removed from the context; OBJECT_CHANGED when one of the leaf objects present in the provided context had changes in its content. OBJECT_REMOVED is not fired when the sub-context is removed from the parent context.
    • LEVEL_OBJECT_SCOPE: fires events when changes happen in the provided context. LEVEL_OBJECT_SCOPE can only be applied to context objects. OBJECT_ADDED is fired when an object (context or leaf) is added to the context; OBJECT_REMOVED when an object (context or leaf) is removed from the context; OBJECT_CHANGED when one of the leaf objects present in the provided context had changes in its content. OBJECT_REMOVED is also fired when the sub-context is removed from the parent context.
    • SUBTREE_SCOPE: fires events when changes happen in the provided context, and any context deeper in the tree descending from the provided context. SUBTREE_SCOPE can only be applied to context objects. OBJECT_ADDED is fired when an object (context or leaf) is added to the context, or any of its descendant contexts; OBJECT_REMOVED when an object (context or leaf) is removed from the context or a descendant context; OBJECT_CHANGED when one of the leaf objects present in the provided context or any descendant context had changes in its content. OBJECT_REMOVED is also fired when the sub-context is removed from the parent context.
    The listeners to be notified are determined with a regular expression. Examples of this regular expression are given below.
    • OBJECT_SCOPE: Suppose we are interested in changes to the object registered under "/simulation1/sub1/myobject". In that case, the regular expression is "/simulation1/sub1/myobject" as we are only interested in changes to the object registered under this key.
    • LEVEL_SCOPE: Suppose we are interested in changes to the objects registered directly under "/simulation1/sub1", excluding the sub1 context itself. In that case, the regular expression is "/simulation1/sub1/[^/]+$" as we are only interested in changes to the objects registered under this key, so minimally one character after the key that cannot be a forward slash, as that would indicate a subcontext.
    • LEVEL_OBJECT_SCOPE: Suppose we are interested in changes to the objects registered directly under "/simulation1/sub1", including the "/simulation1/sub1" context itself. In that case, the regular expression is "/simulation1/sub1(/[^/]*$)?" as we are interested in changes to the objects directly registered under this key, so minimally one character after the key that cannot be a forward slash. The context "sub1" itself is also included, with or without a forward slash at the end.
    • SUBTREE_SCOPE: Suppose we are interested in changes to the objects registered in the total subtree under "/simulation1/sub1", including the "/simulation1/sub1" context itself. In that case, the regular expression is "/simulation1/sub1(/.*)?". The context "sub1" itself is also included, with or without a forward slash at the end.

    Copyright (c) 2020-2023 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://simulation.tudelft.nl. The DSOL project is distributed under a three-clause BSD-style license, which can be found at https://https://simulation.tudelft.nl/dsol/docs/latest/license.html.

    Author:
    Alexander Verbraeck
    See Also:
    Serialized Form

    • Constructor Detail

      • ContextEventProducerImpl

        public ContextEventProducerImpl​(EventContext parent)
                         throws RemoteException
        Create the ContextEventProducerImpl and link to the parent class.
        Parameters:
        parent - EventContext; the EventContext for which we do the work
        Throws:
        RemoteException - on network error

    • Method Detail

      • makeRegistryKey

        protected String makeRegistryKey​(String absolutePath,
                                 ContextScope contextScope)
        Make a key consisting of the full path of the subcontext (without the trailing slash) or object in the context tree, followed by a hash code (#) and the context scope string (OBJECT_SCOPE, LEVEL_SCOPE, LEVEL_OBJECT_SCOPE, or SUBTREE_SCOPE).
        Parameters:
        absolutePath - String; the path for which the key has to be made. The path can point to an object or a subcontext
        contextScope - ContextScope; the scope for which the key has to be made
        Returns:
        a concatenation of the path, a hash (#) and the context scope

      • makeRegex

        protected String makeRegex​(String absolutePath,
                           ContextScope contextScope)
        Make a regular expression that matches the right paths to be matched. The regular expression per scope is:
        • OBJECT_SCOPE: Suppose we are interested in changes to the object registered under "/simulation1/sub1/myobject". In that case, the regular expression is "/simulation1/sub1/myobject" as we are only interested in changes to the object registered under this key.
        • LEVEL_SCOPE: Suppose we are interested in changes to the objects registered directly under "/simulation1/sub1", excluding the sub1 context itself. In that case, the regular expression is "/simulation1/sub1/[^/]+$" as we are only interested in changes to the objects registered under this key, so minimally one character after the key that cannot be a forward slash, as that would indicate a subcontext.
        • LEVEL_OBJECT_SCOPE: Suppose we are interested in changes to the objects registered directly under "/simulation1/sub1", including the "/simulation1/sub1" context itself. In that case, the regular expression is "/simulation1/sub1(/[^/]*$)?" as we are interested in changes to the objects directly registered under this key, so minimally one character after the key that cannot be a forward slash. The context "sub1" itself is also included, with or without a forward slash at the end.
        • SUBTREE_SCOPE: Suppose we are interested in changes to the objects registered in the total subtree under "/simulation1/sub1", including the "/simulation1/sub1" context itself. In that case, the regular expression is "/simulation1/sub1(/.*)?". The context "sub1" itself is also included, with or without a forward slash at the end.
        Parameters:
        absolutePath - String; the path for which the key has to be made. The path can point to an object or a subcontext
        contextScope - ContextScope; the scope for which the key has to be made
        Returns:
        a concatenation of the path, a hash (#) and the context scope

      • addListener

        public boolean addListener​(EventListener listener,
                           String absolutePath,
                           ContextScope contextScope)
                    throws RemoteException,
                           NameNotFoundException,
                           InvalidNameException,
                           NotContextException,
                           NamingException,
                           NullPointerException
        Add a listener for the provided scope as strong reference to the BEGINNING of a queue of listeners.
        Parameters:
        listener - EventListener; the listener which is interested at events of eventType.
        absolutePath - String; the absolute path of the context or object to subscribe to
        contextScope - ContextScope; the part of the tree that the listener is aimed at (current node, current node and keys, subtree).
        Returns:
        the success of adding the listener. If a listener was already added false is returned.
        Throws:
        NameNotFoundException - when the absolutePath could not be found in the parent context, or when an intermediate context does not exist
        InvalidNameException - when the scope is OBJECT_SCOPE, but the key points to a (sub)context
        NotContextException - when the scope is LEVEL_SCOPE, OBJECT_LEVEL_SCOPE or SUBTREE_SCOPE, and the key points to an ordinary object
        NamingException - as an overarching exception for context errors
        NullPointerException - when one of the arguments is null
        RemoteException - if a network connection failure occurs.

      • addListener

        public boolean addListener​(EventListener listener,
                           String absolutePath,
                           ContextScope contextScope,
                           ReferenceType referenceType)
                    throws RemoteException,
                           NameNotFoundException,
                           InvalidNameException,
                           NotContextException,
                           NamingException,
                           NullPointerException
        Add a listener for the provided scope to the BEGINNING of a queue of listeners.
        Parameters:
        listener - EventListener; the listener which is interested at events of eventType.
        absolutePath - String; the absolute path of the context or object to subscribe to
        contextScope - ContextScope; the part of the tree that the listener is aimed at (current node, current node and keys, subtree).
        referenceType - ReferenceType; whether the listener is added as a strong or as a weak reference.
        Returns:
        the success of adding the listener. If a listener was already added false is returned.
        Throws:
        NameNotFoundException - when the absolutePath could not be found in the parent context, or when an intermediate context does not exist
        InvalidNameException - when the scope is OBJECT_SCOPE, but the key points to a (sub)context
        NotContextException - when the scope is LEVEL_SCOPE, OBJECT_LEVEL_SCOPE or SUBTREE_SCOPE, and the key points to an ordinary object
        NamingException - as an overarching exception for context errors
        NullPointerException - when one of the arguments is null
        RemoteException - if a network connection failure occurs.

      • addListener

        public boolean addListener​(EventListener listener,
                           String absolutePath,
                           ContextScope contextScope,
                           int position)
                    throws RemoteException,
                           NameNotFoundException,
                           InvalidNameException,
                           NotContextException,
                           NamingException,
                           NullPointerException
        Add a listener for the provided scope as strong reference to the specified position of a queue of listeners.
        Parameters:
        listener - EventListener; the listener which is interested at events of eventType.
        absolutePath - String; the absolute path of the context or object to subscribe to
        contextScope - ContextScope; the part of the tree that the listener is aimed at (current node, current node and keys, subtree).
        position - int; the position of the listener in the queue.
        Returns:
        the success of adding the listener. If a listener was already added, or an illegal position is provided false is returned.
        Throws:
        NameNotFoundException - when the absolutePath could not be found in the parent context, or when an intermediate context does not exist
        InvalidNameException - when the scope is OBJECT_SCOPE, but the key points to a (sub)context
        NotContextException - when the scope is LEVEL_SCOPE, OBJECT_LEVEL_SCOPE or SUBTREE_SCOPE, and the key points to an ordinary object
        NamingException - as an overarching exception for context errors
        NullPointerException - when one of the arguments is null
        RemoteException - if a network connection failure occurs.

      • addListener

        public boolean addListener​(EventListener listener,
                           String absolutePath,
                           ContextScope contextScope,
                           int position,
                           ReferenceType referenceType)
                    throws RemoteException,
                           InvalidNameException,
                           NullPointerException
        Add a listener for the provided scope to the specified position of a queue of listeners.
        Parameters:
        listener - EventListener; which is interested at certain events,
        absolutePath - String; the absolute path of the context or object to subscribe to
        contextScope - ContextScope; the part of the tree that the listener is aimed at (current node, current node and keys, subtree).
        position - int; the position of the listener in the queue
        referenceType - ReferenceType; whether the listener is added as a strong or as a weak reference.
        Returns:
        the success of adding the listener. If a listener was already added or an illegal position is provided false is returned.
        Throws:
        InvalidNameException - when the path does not start with a slash
        NullPointerException - when one of the arguments is null
        RemoteException - if a network connection failure occurs

      • removeListener

        public boolean removeListener​(EventListener listener,
                              String absolutePath,
                              ContextScope contextScope)
                       throws RemoteException,
                              InvalidNameException,
                              NullPointerException
        Remove the subscription of a listener for the provided scope for a specific event.
        Parameters:
        listener - EventListener; which is no longer interested.
        absolutePath - String; the absolute path of the context or object to subscribe to
        contextScope - ContextScope;the scope which is of no interest any more.
        Returns:
        the success of removing the listener. If a listener was not subscribed false is returned.
        Throws:
        InvalidNameException - when the path does not start with a slash
        NullPointerException - when one of the arguments is null
        RemoteException - if a network connection failure occurs