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

Class InitialEventContext

java.lang.Object

nl.tudelft.simulation.naming.context.event.InitialEventContext

All Implemented Interfaces:

Serializable, Remote, ContextInterface, EventContext, EventContextInterface, EventProducer

public final class InitialEventContext
extends Object
implements EventContext

InitialEventContext class. This class is the starting context for performing naming operations. The class is loosely based on InitialContext in the Java JNDI package, but creates a lightweight Context that implements the DSOL ContextInterface. The InitialEventContext is a singleton class.

Copyright (c) 2002-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

Field Summary

Fields

Modifier and Type	Field	Description
ContextEventProducerImpl	contextEventProducerImpl	The event producer to which context events will be delegated for handling.
protected ContextInterface	defaultInitCtx	The initial context, usually built by a factory.
protected boolean	gotDefault	has the default context been generated?
static String	INITIAL_CONTEXT_FACTORY	Constant that holds the name of the environment property for specifying the initial context factory to use.
protected Hashtable<?,?>	properties	the properties of the initialEventContext.
static String	PROVIDER_URL	Constant that holds the name of the environment property for specifying configuration information for the service provider to use.
static String	WRAPPED_CONTEXT_FACTORY	Constant that holds the name of the environment property for specifying the initial context factory to use, as embedded factory in a remote context that is specified by the INITIAL_CONTEXT_FACTORY constant.

Fields inherited from interface nl.tudelft.simulation.naming.context.ContextInterface

OBJECT_ADDED_EVENT, OBJECT_CHANGED_EVENT, OBJECT_REMOVED_EVENT, REPLACE_SEPARATOR, ROOT, SEPARATOR

Fields inherited from interface org.djutils.event.EventProducer

FIRST_POSITION, LAST_POSITION

Method Summary

Modifier and Type	Method	Description
boolean	addListener(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(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(EventListener listener, String absolutePath, ContextScope contextScope, int position, ReferenceType referenceType)	Add a listener for the provided scope to the specified position of a queue of listeners.
boolean	addListener(EventListener listener, String absolutePath, ContextScope contextScope, ReferenceType referenceType)	Add a listener for the provided scope to the BEGINNING of a queue of listeners.
boolean	addListener(EventListener listener, EventType eventType)
boolean	addListener(EventListener listener, EventType eventType, int position)
boolean	addListener(EventListener listener, EventType eventType, int position, ReferenceType referenceType)
boolean	addListener(EventListener listener, EventType eventType, ReferenceType referenceType)
void	bind(String name, Object object)	Binds an object into the Context using the name.
Map<String,Object>	bindings()	Returns a (raw) map of bindings in the current context, mapping the name on the registered objects.
void	bindObject(Object object)	Binds an object into the Context using the toString() method of the object as the key.
void	bindObject(String key, Object object)	Binds an object into this Context using the key.
protected Hashtable<?,?>	buildEnvironment(Hashtable<?,?> environment)	Build the properties that the generation of the initial event context will use.
void	checkCircular(Object newObject)	Check whether a circular reference would occur when the object would be inserted into the current context.
void	close()	Closes the context and removes all content from the context.
ContextInterface	createSubcontext(String name)	Creates and binds a new context into the current Context using the name.
void	destroySubcontext(String name)	Removes the binding for an existing, empty subcontext with the given name, and recursively unbinds all objects and contexts in the context indicated by the name.
boolean	exists(String name)	Indicates whether an object with the given name has been registered in the Context.
void	fireObjectChangedEventKey(String key)	Fire an OBJECT_CHANGED_EVENT for an object with the given key in the current context.
void	fireObjectChangedEventValue(Object object)	Fire an OBJECT_CHANGED_EVENT for an object within the current context.
Object	get(String name)	Retrieves the named object from the Context.
String	getAbsolutePath()	Returns the absolute path for this context, or an empty string when this is the root context.
String	getAtomicName()	Retrieves the atomic name of this context.
protected ContextInterface	getDefaultInitCtx(String atomicName)	Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx.
Hashtable<?,?>	getEnvironment()	Return a safe copy of the used environment variables.
EventListenerMap	getEventListenerMap()
Object	getObject(String key)	Retrieves the named object from the Context.
ContextInterface	getParent()	Retrieves the parent context for this context, or null when this is the root context.
ContextInterface	getRootContext()	Retrieves the root context for this context, or the current context when this is the root context.
boolean	hasKey(String key)	Indicates whether the key has been registered in the current Context.
boolean	hasObject(Object object)	Indicates whether the object has been registered (once or more) in the current Context.
protected void	init(Hashtable<?,?> environment, String atomicName)	Initializes the initial context using the supplied environment.
static InitialEventContext	instantiate(String atomicName)	Constructs an initial context using the supplied environment; no overriding environment variables are provided.
static InitialEventContext	instantiate(Hashtable<?,?> environment, String atomicName)	Constructs an initial context using the supplied environment.
boolean	isEmpty()	Indicates whether the current context is empty.
Set<String>	keySet()	Returns a set of registered keys in the current context.
void	rebind(String name, Object object)	Replaces an object in the Context with the given name, or registers the object when a registration with the name does not exist yet.
void	rebindObject(String key, Object object)	Replaces an object in this Context with the given key, or registers the object when a registration with the key does not exist yet.
int	removeAllListeners()
boolean	removeListener(EventListener listener, String absolutePath, ContextScope contextScope)	Remove the subscription of a listener for the provided scope for a specific event.
boolean	removeListener(EventListener listener, EventType eventType)
void	rename(String oldName, String newName)	Replaces the name under which an object has been registered in the Context.
String	toString()
String	toString(boolean verbose)	Return a String with the hierarchical content of the Context in case verbose is true; otherwise return the atomic name.
void	unbind(String name)	Removes the binding for an object in the Context with the given name.
void	unbindObject(String key)	Removes the binding for an object in this Context with the given key.
Collection<Object>	values()	Returns a (raw) collection of registered values in the current context.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.djutils.event.EventProducer

fireEvent, fireEvent, fireEvent, fireTimedEvent, fireTimedEvent, fireTimedEvent, fireUnverifiedEvent, fireUnverifiedEvent, fireUnverifiedTimedEvent, fireUnverifiedTimedEvent, getEventTypesWithListeners, getListenerReferences, hasListeners, numberOfListeners, removeAllListeners

Field Detail

INITIAL_CONTEXT_FACTORY

public static final String INITIAL_CONTEXT_FACTORY

Constant that holds the name of the environment property for specifying the initial context factory to use. The value of the property should be the fully qualified class name of the factory class that will create an initial context. This property may be specified in the environment parameter passed to the initial context constructor, a system property, or an application resource file. If it is not specified in any of these sources, NoInitialContextException is thrown when an initial context is required to complete an operation.

The value of this constant is "java.naming.factory.initial".

See Also:

Constant Field Values

PROVIDER_URL

public static final String PROVIDER_URL

Constant that holds the name of the environment property for specifying configuration information for the service provider to use. The value of the property should contain a URL string (e.g. "http://localhost:1099/remoteContext"). This property may be specified in the environment, a system property, or a resource file. If it is not specified in any of these sources, the default configuration is determined by the service provider.

The value of this constant is "java.naming.provider.url".

See Also:

Constant Field Values

WRAPPED_CONTEXT_FACTORY

public static final String WRAPPED_CONTEXT_FACTORY

Constant that holds the name of the environment property for specifying the initial context factory to use, as embedded factory in a remote context that is specified by the INITIAL_CONTEXT_FACTORY constant. The value of the property should be the fully qualified class name of the factory class that will create an initial context that will be embedded within the remote context. This property may be specified in the environment parameter passed to the initial context constructor, a system property, or an application resource file. If it is not specified in any of these sources, NoInitialContextException is thrown when an initial context is required to complete an operation.

The value of this constant is "wrapped.naming.factory.initial".

See Also:

Constant Field Values

properties

protected Hashtable<?,?> properties

the properties of the initialEventContext.

defaultInitCtx

protected ContextInterface defaultInitCtx

The initial context, usually built by a factory. It is set by getDefaultInitCtx() the first time getDefaultInitCtx() is called. Subsequent invocations of getDefaultInitCtx() return the value of defaultInitCtx until close() is called.

gotDefault

protected boolean gotDefault

has the default context been generated?

contextEventProducerImpl

public ContextEventProducerImpl contextEventProducerImpl

The event producer to which context events will be delegated for handling.

Method Detail

instantiate

public static InitialEventContext instantiate(String atomicName)
                                       throws NamingException,
                                              RemoteException

Constructs an initial context using the supplied environment; no overriding environment variables are provided.

Parameters:

atomicName - String; the name under which the root context will be registered

Returns:

a singleton instance of InitialEventContext

Throws:

NamingException - when the provided ContextFactory was not able to instantiate the wrapped context

RemoteException - if a network connection failure occurs

instantiate

public static InitialEventContext instantiate(Hashtable<?,?> environment,
                                              String atomicName)
                                       throws NamingException,
                                              RemoteException

Constructs an initial context using the supplied environment.

Parameters:

environment - Hashtable<?,?>; environment used to create the initial context. Null indicates an empty environment.

atomicName - String; the name under which the root context will be registered

Returns:

a singleton instance of InitialEventContext

Throws:

NamingException - when the provided ContextFactory was not able to instantiate the wrapped context

RemoteException - if a network connection failure occurs

init

protected void init(Hashtable<?,?> environment,
                    String atomicName)
             throws NamingException,
                    RemoteException

Initializes the initial context using the supplied environment.

Parameters:

environment - Hashtable<?,?>; environment used to create the initial context. Null indicates an empty environment.

atomicName - String; the name under which the root context will be registered

Throws:

NamingException - when the provided ContextFactory was not able to instantiate the wrapped context

RemoteException - if a network connection failure occurs

buildEnvironment

protected Hashtable<?,?> buildEnvironment(Hashtable<?,?> environment)

Build the properties that the generation of the initial event context will use. In sequence, the following sources of properties are explored: (1) default values, (2) system environment, (3) Java system properties, (4) content of the /resources/jndi.properties file, (5) the provided environment. If a property is available in a later evaluation, it takes precedence over an earlier definition.

Parameters:

environment - the final overwriting environment to use (can be null)

Returns:

Hashtable<?,?>; a combined Hashtable with information from system properties, jndi.properties and the provided environment Hashtable

getDefaultInitCtx

protected ContextInterface getDefaultInitCtx(String atomicName)
                                      throws NamingException,
                                             RemoteException

Retrieves the initial context by calling NamingManager.getInitialContext() and cache it in defaultInitCtx. Set gotDefault so that we know we've tried this before.

Parameters:

atomicName - String; the name under which the root context will be registered

Returns:

The non-null cached initial context.

Throws:

NamingException - if a naming exception was encountered

RemoteException - if a network connection failure occurs

getEnvironment

public Hashtable<?,?> getEnvironment()

Return a safe copy of the used environment variables.

Returns:

Hashtable<?, ?>; a safe copy of the used environment variables

close

public void close()
           throws NamingException,
                  RemoteException

Closes the context and removes all content from the context. No events will be fired that the content of the context has been removed. Some contexts, such as the FileContext could have to be really closed as well.

Specified by:

close in interface ContextInterface

Throws:

NamingException - when a problem occurs during closing (e.g., of a FileContext)

RemoteException - on a network error when the Context is used over RMI

getAtomicName

public String getAtomicName()
                     throws RemoteException

Retrieves the atomic name of this context.

Specified by:

getAtomicName in interface ContextInterface

Returns:

String; the atomic name of this context

Throws:

RemoteException - on a network error when the Context is used over RMI

getParent

public ContextInterface getParent()
                           throws RemoteException

Retrieves the parent context for this context, or null when this is the root context.

Specified by:

getParent in interface ContextInterface

Returns:

ContextInterface; parent context for this context, or null when this is the root context

Throws:

RemoteException - on a network error when the Context is used over RMI

getRootContext

public ContextInterface getRootContext()
                                throws RemoteException

Retrieves the root context for this context, or the current context when this is the root context.

Specified by:

getRootContext in interface ContextInterface

Returns:

ContextInterface; the root context for this context

Throws:

RemoteException - on a network error when the Context is used over RMI

getAbsolutePath

public String getAbsolutePath()
                       throws RemoteException

Returns the absolute path for this context, or an empty string when this is the root context.

Specified by:

getAbsolutePath in interface ContextInterface

Returns:

String; the absolute path for this context, or an empty string when this is the root context

Throws:

RemoteException - on a network error when the Context is used over RMI

get

public Object get(String name)
           throws NamingException,
                  RemoteException

Retrieves the named object from the Context. The name may be a compound name where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts must exist. When name is the empty String or "/", the current Context is returned.

Specified by:

get in interface ContextInterface

Parameters:

name - String; the name of the object to look up; may be a compound name

Returns:

Object; the Context or Object indicated by the name

Throws:

NamingException - as a placeholder overarching exception

NameNotFoundException - if an intermediate context or the reference does not exist

RemoteException - on a network error when the Context is used over RMI

getObject

public Object getObject(String key)
                 throws NamingException,
                        RemoteException

Retrieves the named object from the Context. The key is not compound. Key cannot be empty or contain "/".

Specified by:

getObject in interface ContextInterface

Parameters:

key - String; the name of the object to look up; NOT a compound name

Returns:

Object; the Context or Object indicated by the key

Throws:

NamingException - when key is the empty string or when key contains "/"

NameNotFoundException - if the key does not exist in the current context

RemoteException - on a network error when the Context is used over RMI

exists

public boolean exists(String name)
               throws NamingException,
                      RemoteException

Indicates whether an object with the given name has been registered in the Context. The name may be a compound name where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts must exist. When name is the empty String or "/", the method returns true.

Specified by:

exists in interface ContextInterface

Parameters:

name - String; the name of the object to look up; may be a compound name

Returns:

boolean; whether an object with the given name has been registered

Throws:

NamingException - as a placeholder overarching exception

NameNotFoundException - when an intermediate context does not exist

RemoteException - on a network error when the Context is used over RMI

hasKey

public boolean hasKey(String key)
               throws NamingException,
                      RemoteException

Indicates whether the key has been registered in the current Context. The name is not compound. When name is the empty String or "/", the method returns an exception.

Specified by:

hasKey in interface ContextInterface

Parameters:

key - String; the name of the object to look up; NOT compound

Returns:

boolean; whether an object with the given key has been registered in the current context

Throws:

NamingException - when key is the empty string or when key contains "/"

RemoteException - on a network error when the Context is used over RMI

hasObject

public boolean hasObject(Object object)
                  throws RemoteException

Indicates whether the object has been registered (once or more) in the current Context. The object may be null.

Specified by:

hasObject in interface ContextInterface

Parameters:

object - Object; the object to look up; mey be null

Returns:

boolean; whether an object with the given key has been registered once or more in the current context

Throws:

RemoteException - on a network error when the Context is used over RMI

isEmpty

public boolean isEmpty()
                throws RemoteException

Indicates whether the current context is empty.

Specified by:

isEmpty in interface ContextInterface

Returns:

boolean; whether the current context is empty

Throws:

RemoteException - on a network error when the Context is used over RMI

bind

public void bind(String name,
                 Object object)
          throws NamingException,
                 RemoteException

Binds an object into the Context using the name. The name may be a compound name where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts must already exist. The object will be registered using the terminal atomic reference in the deepest subcontext provided. Name cannot be empty or "/". An OBJECT_ADDED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the object when a new binding has taken place.

Specified by:

bind in interface ContextInterface

Parameters:

name - String; the name under which the object will be stored; may be a compound name with the terminal reference indicating the key under which the object will be stored

object - Object; the Context or Object to be stored into the given context; a null object is allowed

Throws:

NamingException - when the reference is "/" or empty

NameAlreadyBoundException - if name is already bound to an object

NameNotFoundException - when an intermediate context does not exist

RemoteException - on a network error when the Context is used over RMI

bindObject

public void bindObject(String key,
                       Object object)
                throws NamingException,
                       RemoteException

Binds an object into this Context using the key. The key is not compound. The key cannot be empty or "/". An OBJECT_ADDED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the object when a new binding has taken place.

Specified by:

bindObject in interface ContextInterface

Parameters:

key - String; the key under which the object will be stored; NOT a compound name

object - Object; the Context or Object to be stored into this Context using the given name; a null object is allowed

Throws:

NamingException - when key is the empty string or when key contains "/"

NameAlreadyBoundException - if key is already bound to an object

RemoteException - on a network error when the Context is used over RMI

bindObject

public void bindObject(Object object)
                throws NamingException,
                       RemoteException

Binds an object into the Context using the toString() method of the object as the key. All "/" characters in the toString() result will be replaced by "#" characters. An OBJECT_ADDED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the object when a new binding has taken place.

Specified by:

bindObject in interface ContextInterface

Parameters:

object - Object; the Context or Object to be stored into this Context using the toString() result as the key; a null object is not allowed

Throws:

NamingException - when the toString() of the object results in an empty string

NameAlreadyBoundException - if key is already bound to an object

RemoteException - on a network error when the Context is used over RMI

unbind

public void unbind(String name)
            throws NamingException,
                   RemoteException

Removes the binding for an object in the Context with the given name. The name may be a compound name where parts are separated by separation strings indicating subcontexts. Name cannot be empty or "/". It is not a problem when there is no object registered with the given name. An OBJECT_REMOVED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the removed object when a binding has been removed.

Specified by:

unbind in interface ContextInterface

Parameters:

name - String; the name of the object that has to be removed; may be a compound name with the terminal reference indicating the key under which the object is stored

Throws:

NamingException - when the reference is "/" or empty

NameNotFoundException - when an intermediate context does not exist

RemoteException - on a network error when the Context is used over RMI

unbindObject

public void unbindObject(String key)
                  throws NamingException,
                         RemoteException

Removes the binding for an object in this Context with the given key. The key is not compound. The key cannot be empty or "/". It is not a problem when there is no object registered with the given key. An OBJECT_REMOVED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the removed object when a binding has been removed.

Specified by:

unbindObject in interface ContextInterface

Parameters:

key - String; the key of the object that has to be removed; NOT a compound name

Throws:

NamingException - when key is the empty string or when key contains "/"

RemoteException - on a network error when the Context is used over RMI

rebind

public void rebind(String name,
                   Object object)
            throws NamingException,
                   RemoteException

Replaces an object in the Context with the given name, or registers the object when a registration with the name does not exist yet. The name may be a compound name where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts must already exist. The object will be (re)registered using the terminal atomic reference in the deepest subcontext provided. Name cannot be empty or "/". An OBJECT_REMOVED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the removed object when a binding had to be removed, followed by an OBJECT_ADDED_EVENT containing an object array with a pointer to the context, the key, and the new object when a new binding has taken place.

Specified by:

rebind in interface ContextInterface

Parameters:

name - String; the name of the object to be replaced, or under which the object will be stored; may be a compound name with the terminal reference indicating the key under which the object will be stored

object - Object; the Context or Object to be replaced or stored into this Context using the given name; a null object is allowed

Throws:

NamingException - when the reference is "/" or empty

NameNotFoundException - when an intermediate context does not exist

RemoteException - on a network error when the Context is used over RMI

rebindObject

public void rebindObject(String key,
                         Object object)
                  throws NamingException,
                         RemoteException

Replaces an object in this Context with the given key, or registers the object when a registration with the key does not exist yet. The key is not a compound name. Name cannot be empty or "/". An OBJECT_REMOVED_EVENT is fired containing an object array with a pointer to the context, the relative key, and the removed object when a binding had to be removed, followed by an OBJECT_ADDED_EVENT containing an object array with a pointer to the context, the key, and the new object when a new binding has taken place.

Specified by:

rebindObject in interface ContextInterface

Parameters:

key - String; the key of the object to be replaced, or under which the object will be stored; NOT a compound name

object - Object; the Context or Object to be replaced or stored into this Context using the given name; a null object is allowed

Throws:

NamingException - when key is the empty string or when key contains "/"

RemoteException - on a network error when the Context is used over RMI

rename

public void rename(String oldName,
                   String newName)
            throws NamingException,
                   RemoteException

Replaces the name under which an object has been registered in the Context. Both names are relative to the current Context, and may be compound names where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts of the new name must already exist. The object will be deregistered under the old name, and reregistered using the terminal atomic reference in the deepest subcontext of the newName. Nether the oldName, nor the newName can be empty or "/". An OBJECT_REMOVED_EVENT is fired containing an object array with a pointer to the old context, the old relative key, and the object when a binding had to be removed, followed by an OBJECT_ADDED_EVENT containing an object array with a pointer to the new context, the new relative key, and the object when a new binding has taken place. When the new name is illegal or occupied, the object will not be renamed.

Specified by:

rename in interface ContextInterface

Parameters:

oldName - String; the (compound) name of the object to be moved to a new location

newName - String; the (compound) name with the terminal reference indicating where the object will be stored

Throws:

NamingException - when the reference of oldName or newName is "/" or empty

NameNotFoundException - when an intermediate context of oldName or newName does not exist, or when there is no registration at the oldName reference

NameAlreadyBoundException - if newName is already bound to an object

RemoteException - on a network error when the Context is used over RMI

createSubcontext

public ContextInterface createSubcontext(String name)
                                  throws NamingException,
                                         RemoteException

Creates and binds a new context into the current Context using the name. The name may be a compound name where parts are separated by separation strings indicating subcontexts. All intermediate subcontexts that do not yet exist, will be created. The new context will be registered using the terminal atomic reference in the deepest subcontext provided. Name cannot be empty or "/". On success, OBJECT_ADDED_EVENTs are fired for the created context and each new intermediate context, containing an object array with an object array with a pointer to the embedding context, the local key in the embedding context, and the newly created (intermediate) context.

Specified by:

createSubcontext in interface ContextInterface

Parameters:

name - String; the name under which the new context will be stored; may be a compound name with the terminal reference indicating the key under which the new context will be stored

Returns:

ContextInterface; a pointer to the newly created subcontext

Throws:

NamingException - when the terminal reference is "/" or empty

NameNotFoundException - when an intermediate context does not exist

NameAlreadyBoundException - if name is already bound to an object or context

RemoteException - on a network error when the Context is used over RMI

destroySubcontext

public void destroySubcontext(String name)
                       throws NamingException,
                              RemoteException

Removes the binding for an existing, empty subcontext with the given name, and recursively unbinds all objects and contexts in the context indicated by the name. The name may be a compound name where parts are separated by separation strings indicating subcontexts. Name cannot be empty or "/". A context has to be registered with the given name. For all removed objects and contexts, OBJECT_REMOVED_EVENT events are fired containing an object array with a pointer to the context from which content has been removed, the key of the binding that has been removed, and the removed object. The OBJECT_REMOVED_EVENT events are fired in depth-first order.

Specified by:

destroySubcontext in interface ContextInterface

Parameters:

name - String; the name of the object that has to be removed; may be a compound name with the terminal reference indicating the key under which the object is stored

Throws:

NamingException - when the reference is "/" or empty

NotContextException - if the name is bound but does not name a context

NameNotFoundException - when an intermediate context does not exist, or when no object is registered with the terminating atomic reference

RemoteException - on a network error when the Context is used over RMI

checkCircular

public void checkCircular(Object newObject)
                   throws NamingException,
                          RemoteException

Check whether a circular reference would occur when the object would be inserted into the current context. Insertion potentially causes a problem when the object to be inserted is a Context.

Specified by:

checkCircular in interface ContextInterface

Parameters:

newObject - the object to be inserted

Throws:

NamingException - when a circular reference would occur

RemoteException - on a network error when the Context is used over RMI

keySet

public Set<String> keySet()
                   throws RemoteException

Returns a set of registered keys in the current context.

Specified by:

keySet in interface ContextInterface

Returns:

Set<String>; a set of registered keys in the current context

Throws:

RemoteException - on a network error when the Context is used over RMI

values

public Collection<Object> values()
                          throws RemoteException

Returns a (raw) collection of registered values in the current context.

Specified by:

values in interface ContextInterface

Returns:

Collection<Object>; a raw set of registered objects in the current context

Throws:

RemoteException - on a network error when the Context is used over RMI

bindings

public Map<String,Object> bindings()
                                  throws RemoteException

Returns a (raw) map of bindings in the current context, mapping the name on the registered objects. Both regular objects and subcontexts are returned. Mappings to null objects can exist.

Specified by:

bindings in interface ContextInterface

Returns:

Map<String, Object>; a map of registered names and their bound (possibly null) object in the current context

Throws:

RemoteException - on a network error when the Context is used over RMI

fireObjectChangedEventValue

public void fireObjectChangedEventValue(Object object)
                                 throws NameNotFoundException,
                                        NullPointerException,
                                        NamingException,
                                        RemoteException

Fire an OBJECT_CHANGED_EVENT for an object within the current context. Look up if the the object exists using the toString() method of the object as the key. All "/" characters in the toString() result will be replaced by "#" characters. When the object does not exist directly in the context, a NameNotFoundException is thrown.

Specified by:

fireObjectChangedEventValue in interface ContextInterface

Parameters:

object - Object; the object that has changed and for which an event should be fired

Throws:

NameNotFoundException - when no object is registered with object.toString() as the key

NullPointerException - when object is null

NamingException - on general error in the method, e.g., a problem with remote connections

RemoteException - on a network error when the Context is used over RMI

fireObjectChangedEventKey

public void fireObjectChangedEventKey(String key)
                               throws NameNotFoundException,
                                      NullPointerException,
                                      NamingException,
                                      RemoteException

Fire an OBJECT_CHANGED_EVENT for an object with the given key in the current context. If the the key does not exist directly in the context, a NameNotFoundException is thrown. The key should not be the empty String or contain "/" characters.

Specified by:

fireObjectChangedEventKey in interface ContextInterface

Parameters:

key - String; the key within the context of the object that has changed and for which an event should be fired

Throws:

NameNotFoundException - when no object is registered with the key in the given context

NullPointerException - when key is null

NamingException - when key is the empty string or when key contains "/", or on a general error in the method, e.g., a problem with remote connections

RemoteException - on a network error when the Context is used over RMI

toString

public String toString()

Overrides:

toString in class Object

toString

public String toString(boolean verbose)
                throws RemoteException

Return a String with the hierarchical content of the Context in case verbose is true; otherwise return the atomic name.

Specified by:

toString in interface ContextInterface

Parameters:

verbose - boolean; whether the information is exhaustive or very brief

Returns:

String; formatted content of the context when verbose is true; otherwise the atomic name

Throws:

RemoteException - on a network error when the Context is used over RMI

addListener

public boolean addListener(EventListener listener,
                           EventType eventType)
                    throws RemoteException

Specified by:

addListener in interface EventProducer

Throws:

RemoteException

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           ReferenceType referenceType)
                    throws RemoteException

Specified by:

addListener in interface EventProducer

Throws:

RemoteException

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           int position)
                    throws RemoteException

Specified by:

addListener in interface EventProducer

Throws:

RemoteException

addListener

public boolean addListener(EventListener listener,
                           EventType eventType,
                           int position,
                           ReferenceType referenceType)
                    throws RemoteException

Specified by:

addListener in interface EventProducer

Throws:

RemoteException

removeListener

public boolean removeListener(EventListener listener,
                              EventType eventType)
                       throws RemoteException

Specified by:

removeListener in interface EventProducer

Throws:

RemoteException

getEventListenerMap

public EventListenerMap getEventListenerMap()
                                     throws RemoteException

Specified by:

getEventListenerMap in interface EventProducer

Throws:

RemoteException

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.

Specified by:

addListener in interface EventContextInterface

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:

RemoteException - if a network connection failure occurs.

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

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.

Specified by:

addListener in interface EventContextInterface

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:

RemoteException - if a network connection failure occurs.

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

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.

Specified by:

addListener in interface EventContextInterface

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:

RemoteException - if a network connection failure occurs.

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

addListener

public boolean addListener(EventListener listener,
                           String absolutePath,
                           ContextScope contextScope,
                           int position,
                           ReferenceType referenceType)
                    throws RemoteException,
                           NameNotFoundException,
                           InvalidNameException,
                           NotContextException,
                           NamingException,
                           NullPointerException

Add a listener for the provided scope to the specified position of a queue of listeners.

Specified by:

addListener in interface EventContextInterface

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:

RemoteException - if a network connection failure occurs.

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

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.

Specified by:

removeListener in interface EventContextInterface

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:

RemoteException - if a network connection failure occurs

InvalidNameException - when the path does not start with a slash

NullPointerException - when one of the arguments is null

removeAllListeners

public int removeAllListeners()

Specified by:

removeAllListeners in interface EventProducer