me.zeroeightsix.fiber.api.tree

Interface NodeCollection

All Superinterfaces:

java.util.Collection<ConfigNode>, java.lang.Iterable<ConfigNode>

All Known Implementing Classes:

IndexedNodeCollection

public interface NodeCollection
extends java.util.Collection<ConfigNode>

A specialized Collection implementation for use with nodes.

Note: This is not a general-purpose collection. Mutating methods in this class will mutate external state.

Elements in a node collection are considered children of the same tree. For this reason, each element of a node collection must have a distinct name. Mutating methods in this class will also update the parent field of added and removed elements.

The iterator returned by the iterator method traverses the elements in ascending name order (ie. lexicographic order of the nodes' names).

Null elements are not permitted. Attempts to insert a null element will throw a NullPointerException. Attempts to test for the presence of a null element or to remove one will, however, function properly.

Method Summary

Modifier and Type	Method and Description
boolean	add(ConfigNode child) Attempts to introduce a new child to this collection.
boolean	add(ConfigNode child, boolean overwrite) Attempts to introduce a new child to this collection.
ConfigNode	getByName(java.lang.String name) Tries to find a child in this collection by name.
boolean	remove(java.lang.Object child) Removes a child from this collection.
ConfigNode	removeByName(java.lang.String name) Attempts to remove an item from this collection by name.

Methods inherited from interface java.util.Collection

addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

add

boolean add(ConfigNode child)
     throws DuplicateChildException

Attempts to introduce a new child to this collection.

This method behaves as if add(node, false).

Specified by:

add in interface java.util.Collection<ConfigNode>

Parameters:

child - The child to add

Returns:

true (as specified by Collection.add(E))

Throws:

DuplicateChildException - if there was already a child by the same name

java.lang.IllegalStateException - if the child cannot be added to this tree at this time

java.lang.NullPointerException - if node is null

add

boolean add(ConfigNode child,
            boolean overwrite)
     throws DuplicateChildException

Attempts to introduce a new child to this collection.

If this method returns normally, the child will be attached to this collection's owner.

Parameters:

child - The child to add

overwrite - whether existing items with the same name should be overwritten

Returns:

true (as specified by Collection.add(E))

Throws:

DuplicateChildException - if there exists a child by the same name that was not overwritten

java.lang.IllegalStateException - if the child cannot be added to this tree at this time

java.lang.NullPointerException - if node is null

See Also:

ConfigNode.attachTo(ConfigBranch)

remove

boolean remove(java.lang.Object child)

Removes a child from this collection.

When this method returns, the child will be detached from this collection's owner. If the given object is not contained within this collection, this method returns false with no side effects.

Specified by:

remove in interface java.util.Collection<ConfigNode>

Parameters:

child - the child to remove

Returns:

true if a node was detached as a result of this call

See Also:

ConfigNode.detach()

getByName

ConfigNode getByName(java.lang.String name)

Tries to find a child in this collection by name. If a child is found, it will be returned.

Parameters:

name - The name of the child to look for

Returns:

the child if found, otherwise null

removeByName

@Nullable
ConfigNode removeByName(java.lang.String name)

Attempts to remove an item from this collection by name.

Parameters:

name - the name of the child that should be removed

Returns:

the child if removed, otherwise null