Class NamespaceBuilder<T>

  • Type Parameters:
    T - the type of object stored in the namespace
    All Implemented Interfaces:
    Iterable<T>

    public class NamespaceBuilder<T>
    extends Object
    implements Iterable<T>
    A mutable implementation of a Namespace.
    • Field Detail

      • FAIL_ON_COLLISION

        public static final CollisionPolicy<?> FAIL_ON_COLLISION
        Predefined collision policy throwing a DRException on a name collision.
      • REPLACE_ON_COLLISION

        public static final CollisionPolicy<?> REPLACE_ON_COLLISION
        Predefined collision policy replacing the existing entry on a name collision.
      • RENAME_SEQUENTIALLY

        public static final CollisionPolicy<?> RENAME_SEQUENTIALLY
        Predefined collision policy retrying the name binding with a new name. The original name is repeatedly suffixed with an increasing number until a collision no longer exists.
      • NO_DEFAULT_NAME

        public static final NamingPolicy<?> NO_DEFAULT_NAME
        Predefined name generation policy throwing an exception. If used, the add(Object) method will always fail.
    • Constructor Detail

      • NamespaceBuilder

        public NamespaceBuilder()
        Creates a new mutable namespace with collisions causing an error and no default name generation.
      • NamespaceBuilder

        public NamespaceBuilder​(CollisionPolicy<T> onCollision)
        Creates a new mutable namespace with the specified collision policy and no default name generation.
        Parameters:
        onCollision - the collision policy to use in the namespace
      • NamespaceBuilder

        public NamespaceBuilder​(NamingPolicy<T> defaultNaming)
        Creates a new mutable namespace with collisions causing an error and the specified name generation policy.
        Parameters:
        defaultNaming - the name generation strategy to use in the namespace
      • NamespaceBuilder

        public NamespaceBuilder​(CollisionPolicy<T> onCollision,
                                NamingPolicy<T> defaultNaming)
        Creates a new mutable namespace with the specified collision and name generation policies.
        Parameters:
        onCollision - the collision policy to use in the namespace
        defaultNaming - the name generation strategy to use in the namespace
    • Method Detail

      • uniqueNamespace

        public static <T> NamespaceBuilder<T> uniqueNamespace()
        Gets a mutable namespace with no default naming policy. An error is raised on name collisions; see FAIL_ON_COLLISION.
        Type Parameters:
        T - the type of elements in the namespace
        Returns:
        a builder for constructing a namespace
      • uniqueNamespace

        public static <T> NamespaceBuilder<T> uniqueNamespace​(NamingPolicy<T> defaultNaming)
        Gets a mutable namespace using the specified default naming policy. An error is raised on name collisions; see FAIL_ON_COLLISION.
        Type Parameters:
        T - the type of elements in the namespace
        Parameters:
        defaultNaming - the naming policy to use when adding elements without a name
        Returns:
        a builder for constructing a namespace
      • sequencedNamespace

        public static <T> NamespaceBuilder<T> sequencedNamespace()
        Gets a mutable namespace with no default naming policy. Collisions are resolved by appending a sequence number; see RENAME_SEQUENTIALLY.
        Type Parameters:
        T - the type of elements in the namespace
        Returns:
        a builder for constructing a namespace
      • sequencedNamespace

        public static <T> NamespaceBuilder<T> sequencedNamespace​(NamingPolicy<T> defaultNaming)
        Gets a mutable namespace using the specified default naming policy. Collisions are resolved by appending a sequence number; see RENAME_SEQUENTIALLY.
        Type Parameters:
        T - the type of elements in the namespace
        Parameters:
        defaultNaming - the naming policy to use when adding elements without a name
        Returns:
        a builder for constructing a namespace
      • setListener

        public void setListener​(BindListener<T> listener)
        Attaches a listener for namespace entry assignment events. Only one listener at a time is supported; if a listener already exists, it will stop receiving events.
        Parameters:
        listener - the listener to attach
      • size

        public final int size()
        Retrieves the number of elements in the namespace.
        Returns:
        the count of elements
      • isEmpty

        public final boolean isEmpty()
        Indicates whether the namespace is empty. This is equivalent to checking size() == 0.
        Returns:
        true if empty, false otherwise
      • add

        public String add​(T entry)
        Add an entry to the namespace. A name will be generated using the default naming policy. Name collisions are handled according to the collision policy in effect.
        Parameters:
        entry - the value to add to the namespace
        Returns:
        the name assigned to the entry.
        Throws:
        DRException - if one of the namespace policies is violated
      • add

        public String add​(String name,
                          T entry)
        Adds an entry to the name space, associated with the given name. Name collisions are handled according to the collision policy in effect.
        Parameters:
        name - the name to associate with the entry
        entry - the value to add to the namespace
        Returns:
        the actual name associated with the entry. For some collision policies, this may be different than the supplied name.
        Throws:
        DRException - if one of the namespace policies is violated
      • addAll

        public void addAll​(Namespace<T> entries)
        Add all entries from a namespace into this namespace. The given namespace is not modified. Name collisions are handled according to the collision policy in effect.
        Parameters:
        entries - source of namespace entries to add
        Throws:
        DRException - if one of the namespace policies is violated. No guarantee is made about the contents of the namespace if this occurs.
      • clear

        public void clear()
        Removes all entries from the namespace.
      • get

        public T get​(int i)
        Gets the entry at the specified index. Indexing is based on the order in which the entries were added to the namespace.
        Parameters:
        i - index of the element to retrieve
        Returns:
        the ith entry inserted into the namespace
        Throws:
        IndexOutOfBoundsException - if i < 0 || i >= size()
      • getBinding

        public NameBinding<T> getBinding​(int i)
        Gets the name-entry association at the specified index. Indexing is based on the order in which the entries were added to the namespace.
        Parameters:
        i - index of the element to retrieve
        Returns:
        the ith name-entry binding in the namespace
        Throws:
        IndexOutOfBoundsException - if i < 0 || i >= size()
      • indexOf

        public int indexOf​(String name)
        Gets the index of the entry associated with the given name.
        Parameters:
        name - the name of the entry to find
        Returns:
        the index of the matching entry, -1 if no entry with the given name exists
      • get

        public T get​(String name)
        Gets the entry associated with the specified namefrom the namespace.
        Parameters:
        name - the name of the entry to find
        Returns:
        the associated entry, or null if there is no such entry
      • remove

        public T remove​(String name)
        Removes an entry from the namespace.
        Parameters:
        name - the name of the entry to remove
        Returns:
        the entry with the specified name, null if there is no such entry
      • getName

        public String getName​(int i)
        Gets the name associated with entry at the specified index. Indexing is based on the order in which the entries were added to the namespace.
        Parameters:
        i - index of the element name to retrieve
        Returns:
        the name of the ith entry inserted into the namespace
        Throws:
        IndexOutOfBoundsException - if i < 0 || i >= size()
      • getNames

        public String[] getNames()
        Gets all names registered in the namespace. The names are ordered according to the order in which the entries were added.
        Returns:
        the namespace's registered names
      • nameSet

        public Set<String> nameSet()
        Get an unmodifiable collection of all names. The order of entries when iterating over the set does not preserve the order in the namespace.
        Returns:
        the set of the namespace's registered names
      • getBindings

        public List<NameBinding<T>> getBindings()
        Gets a collection of all the name-entry associations. The ordering of the result is the same as that of the namespace.
        Returns:
        a list of bindings in the namespace
      • toNamespace

        public Namespace<T> toNamespace()
        Constructs the currently defined namespace.
        Returns:
        the namespace