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

Class ContextEventProducerImpl

java.lang.Object
org.djutils.event.LocalEventProducer
nl.tudelft.simulation.naming.context.event.ContextEventProducerImpl
All Implemented Interfaces:
Serializable, Remote, EventListener, org.djutils.event.EventListener, org.djutils.event.EventProducer
public class ContextEventProducerImpl extends org.djutils.event.LocalEventProducer implements org.djutils.event.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-2024 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:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    class 
    ContextEventProducerImpl.PatternListener
    Pair of regular expression pattern and event listener.

  • Field Summary

    Fields inherited from interface org.djutils.event.EventProducer

    FIRST_POSITION, LAST_POSITION

  • Constructor Summary

    Constructors
    Constructor
    Description
    ContextEventProducerImpl(EventContext parent)
    Create the ContextEventProducerImpl and link to the parent class.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addListener(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope)
    Add a listener for the provided scope as strong reference to the BEGINNING of a queue of listeners.
    boolean
    addListener(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope, int position)
    Add a listener for the provided scope as strong reference to the specified position of a queue of listeners.
    boolean
    addListener(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope, int position, org.djutils.event.reference.ReferenceType referenceType)
    Add a listener for the provided scope to the specified position of a queue of listeners.
    boolean
    addListener(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope, org.djutils.event.reference.ReferenceType referenceType)
    Add a listener for the provided scope to the BEGINNING of a queue of listeners.
    protected String
    makeRegex(String absolutePath, ContextScope contextScope)
    Make a regular expression that matches the right paths to be matched.
    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).
    void
    notify(org.djutils.event.Event event)
    boolean
    removeListener(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope)
    Remove the subscription of a listener for the provided scope for a specific event.

    Methods inherited from class org.djutils.event.LocalEventProducer

    addListener, addListener, addListener, addListener, fireEvent, fireEvent, fireEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireUnverifiedEvent, fireUnverifiedEvent, fireUnverifiedTimedEvent, fireUnverifiedTimedEvent, getEventListenerMap, getEventTypesWithListeners, getListenerReferences, hasListeners, numberOfListeners, removeAllListeners, removeAllListeners, removeListener

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • 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 Details

    • notify

      public void notify(org.djutils.event.Event event) throws RemoteException
      Specified by:
      notify in interface org.djutils.event.EventListener
      Throws:
      RemoteException

    • 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(org.djutils.event.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(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope, org.djutils.event.reference.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(org.djutils.event.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(org.djutils.event.EventListener listener, String absolutePath, ContextScope contextScope, int position, org.djutils.event.reference.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(org.djutils.event.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