oracle.ide.util
Class Namespace

java.lang.Object
  oracle.ide.util.Namespace

Direct Known Subclasses:

oracle.jdevimpl.wizard.GenericWizardLauncher, TraversableContext

public class Namespace

extends java.lang.Object

This class implements a data structure that uses a hierarchy of named scopes to locate data objects. The names of all objects are specified as strings. Name paths are also allowed (see below), and these are expressed as string arrays.

The concept of "hierarchy" as it is used in this class refers to the way in which data is located by the find(String) method. If the find(String) method cannot locate a data object in the current namespace by the specified name, it searches the parent namespace, recursing up to the root namespace if necessary. If a data object still cannot be found after searching the root namespace, then null is returned. This type of find functionality treats the Namespace hierarchy as a series of nested scopes.

The concept of "name path" as it is used in this class refers to a way of addressing data using a String array as the "name path" when the data is not necessarily located in this Namespace. That is, the data may be located in a child or other descendant namespace. All name paths are relative to the Namespace in which they are used. There isn't direct support for absolute paths, although the notion of an absolute path can effectively be implemented by obtaining the root namespace and locating data using a name path that is relative to the root namespace.

Future considerations:

• It would probably be useful to update Namespace to implement the Map interface. Issues with name paths and nested Namespaces will need to be resolved first. For now, the toMap() method offers a work-around.

Constructor Summary

	Namespace() Creates an new, empty root Namespace.
	Namespace(java.util.Map data) Creates a new root Namespace whose data is the specified Map.
protected	Namespace(java.util.Map data, Namespace parent) Creates a new Namespace whose data is the specified Map and whose parent is the specified Namespace.
	Namespace(Namespace parent) Creates a new empty Namespace whose parent is the specified Namespace.
protected	Namespace(Namespace original, boolean copyDataMap) This is a pseudo copy constructor for use by subclasses which need to take on the responsibilities of an existing Namespace.

Method Summary

boolean	contains(java.lang.String key) Returns true if this Namespace contains a data object by the specified key.
java.lang.Object	find(java.lang.String key) This method attempts to locate a data object by the given key name in this Namespace.
void	findAndReplace(java.lang.String key, java.lang.Object data) This method locates a data object by the given key name using the same algorithm as the find(String) method.
java.lang.Object	get(java.lang.String key) Returns the data object in this Namespace whose name is the specified String.
java.lang.Object	get(java.lang.String[] keyPath) Returns the data object in this Namespace whose name path is the specified String array.
protected java.util.Map	getData() This method is used to retrieve the underlying Map storage associated with this Namespace instance.
Namespace	getParent() Returns the Namespace that is the immediate parent of this Namespace.
Namespace	getRoot() Returns the root Namespace of the hierarchy containing this Namespace.
boolean	isRoot() Returns true if this Namespace is a root Namespace.
void	put(java.lang.String[] keyPath, Namespace ns) Adds the specified Namespace to the specified namespace path.
void	put(java.lang.String[] keyPath, java.lang.Object data) Adds the specified data object to the specified namespace path.
void	put(java.lang.String key, Namespace ns) Adds the specified Namespace as a child of this Namespace.
void	put(java.lang.String key, java.lang.Object data) Adds the specified data object to this Namespace.
java.lang.Object	remove(java.lang.String key) Removes the mapping that is keyed by the specified string from this Namespace.
protected void	setParent(Namespace parent) Special care must be taken when calling this method.
java.util.Map	toMap() Returns the data contained by the Namespace as a Map.
protected java.lang.String	translateKey(java.lang.String key) This method is used to remap a key that is used when invoking either the find(String) or #findAndReplace(String, Object method.

Methods inherited from class java.lang.Object

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

Constructor Detail

Namespace

public Namespace()

Creates an new, empty root Namespace.

Namespace

public Namespace(java.util.Map data)

Creates a new root Namespace whose data is the specified Map.

The specified Map is copied shallowly when initializing the Namespace, so changes to the mapping will not affect the Namespace mapping and vice versa. However, direct changes to the value objects within the mapping will be reflected in both the original Map and the new Namespace. If the specified Map is null, then the Namespace will be initialized as empty.

Namespace

public Namespace(Namespace parent)

Creates a new empty Namespace whose parent is the specified Namespace. If the specified parent is null, the Namespace is initialized as a root Namespace.

Namespace

protected Namespace(java.util.Map data,
                    Namespace parent)

Creates a new Namespace whose data is the specified Map and whose parent is the specified Namespace.

The specified Map is copied shallowly when initializing the Namespace, so changes to the mapping will not affect the Namespace mapping and vice versa. However, direct changes to the value objects within the mapping will be reflected in both the original Map and the new Namespace.

If the specified Map is null, then the Namespace's default data storage will be null. In that case, the subclass must provide an implementation for getData() to return the corresponding Map object.

If the specified parent is null, the Namespace is initialized as a root Namespace.

Namespace

protected Namespace(Namespace original,
                    boolean copyDataMap)

This is a pseudo copy constructor for use by subclasses which need to take on the responsibilities of an existing Namespace.

Parameters:

original - The Namespace whose state should be copied. This must not be null, or else an IllegalArgumentException will be thrown.

copyDataMap - If true a new HashMap will be created to hold the the original's data. If false, the exact same reference for the original's data will be used, as returned by the getData() method.

Method Detail

isRoot

public boolean isRoot()

Returns true if this Namespace is a root Namespace. By definition, a Namespace is a root if and only if it is its own parent.

getParent

public Namespace getParent()

Returns the Namespace that is the immediate parent of this Namespace. If there is no parent, this method returns this. The return value is guaranteed to not be null.

getRoot

public Namespace getRoot()

Returns the root Namespace of the hierarchy containing this Namespace. If this Namespace is the root, then the return value is this. The return value is guaranteed to not be null.

contains

public boolean contains(java.lang.String key)

Returns true if this Namespace contains a data object by the specified key.

find

public java.lang.Object find(java.lang.String key)

This method attempts to locate a data object by the given key name in this Namespace. If the data object cannot be found, this method searches the parent Namespace recursing up toward the root. If the data object is still not found after searching the root Namespace, then null is returned. This type of functionality treats the Namespace hierarchy as a series of nested scopes.

This method is one of the two methods that performs key translation. See translateKey(String).

findAndReplace

public void findAndReplace(java.lang.String key,
                           java.lang.Object data)

This method locates a data object by the given key name using the same algorithm as the find(String) method. Upon finding the object, this method will then replace the associated value with the specified data object. The data object may be null replacing a non-null object, or the data object may be a non-null object replacing null.

If the specified key results in no object being found, then the specified data object is bound to the root Namespace.

This method is one of the two methods that performs key translation. See translateKey(String).

get

public java.lang.Object get(java.lang.String key)

Returns the data object in this Namespace whose name is the specified String. If not found, returns null. No parent Namespace is searched.

get

public java.lang.Object get(java.lang.String[] keyPath)

Returns the data object in this Namespace whose name path is the specified String array. If not found, returns null. A null or empty key path is treated as if it were a single null path element. No parent Namespace is searched.

put

public void put(java.lang.String key,
                java.lang.Object data)

Adds the specified data object to this Namespace. No special action is taken even of the specified data object is a Namespace instance. (See put(String, Namespace) for the special actions that it takes for adding a Namespace.)

The specified key and data object may both be null.

put

public void put(java.lang.String key,
                Namespace ns)

Adds the specified Namespace as a child of this Namespace.

This method differs from the put(String,Object) variant in that the added Namespace has its parent link changed to point to this and its root link changed to point to the root of this Namespace. Thus, the specified Namespace will lose any previous link to a parent and root.

The specified key may be null. If the specified Namespace is null, then a null value is added to this Namespace; of course, no relinking of parent and root could happen in that case.

put

public void put(java.lang.String[] keyPath,
                java.lang.Object data)

Adds the specified data object to the specified namespace path. The namespace path must already exist before the data can be added. If the namespace path cannot be found, then this method has no effect. No special action is taken even if the specified data object is a Namespace instance. (See put(String[], Namespace) for the special actions that it takes for adding a Namespace.)

put

public void put(java.lang.String[] keyPath,
                Namespace ns)

Adds the specified Namespace to the specified namespace path. The namespace path must already exist before the specified Namespace can be added. If the namespace path cannot be found, then this method has no effect.

This method differs from the put(String[],Object) variant in that the added Namespace has its parent link changed to point to the Namespace in which it is added and its root link changed to point to the root of that Namespace's root (which is the same as this Namespace's root). Thus, the specified Namespace will lose any previous link to a parent and root.

remove

public java.lang.Object remove(java.lang.String key)

Removes the mapping that is keyed by the specified string from this Namespace.

toMap

public java.util.Map toMap()

Returns the data contained by the Namespace as a Map. The returned Map is a shallow copy of the data structure used internally by the Namespace. Therefore, changes to the returned Map will not affect the Namespace. However, direct changes to value objects within the Map will be reflected in the Namespace.

setParent

protected void setParent(Namespace parent)

Special care must be taken when calling this method. In particular, subclasses must be able to guarantee that calls to this method do not introduce cycles in the Namespace tree nor should the parent ever be null. Otherwise, the Namespace data structure will no longer have the correct behavior.

getData

protected java.util.Map getData()

This method is used to retrieve the underlying Map storage associated with this Namespace instance. All methods in the Namespace class are implemented to obtain the underlying Map storage from this method.

translateKey

protected java.lang.String translateKey(java.lang.String key)

This method is used to remap a key that is used when invoking either the find(String) or #findAndReplace(String, Object method. In general, translation will not be necessary, so this method by default returns the specified key itself. A subclass that requires key mappings should override this method to provide the proper key mapping behavior.