Package me.datafox.dfxengine.handles.api

Interface HandleSet

All Superinterfaces:

Collection<Handle>, Iterable<Handle>, Set<Handle>

All Known Implementing Classes:

HashHandleSet, TreeHandleSet

public interface HandleSet
extends Set<Handle>

An extension of Set that may only contain Handles from a specified Space. Also has extra functionality to query elements based on their String id.

Method Summary

Modifier and Type	Method	Description
Handle	add(String id)	Creates a Handle with the specified id if one does not already exist and adds it to this set.
boolean	add(Handle handle)	Adds the specified element to this set if it is not already present.
boolean	addAll(Collection<? extends Handle> c)	Adds all elements in the specified collection to this set if they're not already present.
boolean	contains(Object o)	Returns true if this set contains the specified element.
boolean	containsAll(Collection<?> c)	Returns true if this set contains all elements present in the specified collection.
Handle	get(String id)	Returns the Handle in this set with the specified String id, or null if none is present.
Collection<Handle>	getByTag(Object tag)	Returns all Handles in this set containing the specified tag.
Collection<Handle>	getByTags(Collection<?> tags)	Returns all Handles in this set containing the specified tags.
Space	getSpace()	Returns the Space associated with this set.
boolean	remove(Object o)	Removes the specified element from this set if it is present.
boolean	removeAll(Collection<?> c)	Removes from this set all of its elements that are contained in the specified collection.
boolean	retainAll(Collection<?> c)	Retains only the elements in this set that are contained in the specified collection.
HandleSet	unmodifiable()	Returns an unmodifiable version of this set.

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Methods inherited from interface java.util.Set

clear, equals, hashCode, isEmpty, iterator, size, spliterator, toArray, toArray

Method Details

getSpace

Space getSpace()

Returns the Space associated with this set. All Handles present in this set must be associated with this space.

Returns:

Space associated with this set

get

Handle get(String id)

Returns the Handle in this set with the specified String id, or null if none is present.

Parameters:

id - String id of a Handle

Returns:

Handle with the given id, or null if none is present

Throws:

NullPointerException - if the specified id is null

add

Handle add(String id)

Creates a Handle with the specified id if one does not already exist and adds it to this set.

Parameters:

id - id for the new Handle

Returns:

created or pre-existing Handle

Throws:

UnsupportedOperationException - if the add operation is not supported by this set

NullPointerException - if the id is null

IllegalArgumentException - if the id is empty, blank, contains non-ASCII or non-printable characters or more than one colon (:)

unmodifiable

HandleSet unmodifiable()

Returns an unmodifiable version of this set. All changes made to the original set will be reflected in the returned one.

Returns:

unmodifiable version of this set

getByTag

Collection<Handle> getByTag(Object tag)

Returns all Handles in this set containing the specified tag. The tag may be a Handle or its String id.

Parameters:

tag - tag Handle or its String id

Returns:

all Handles in this set containing the specified tag

Throws:

ClassCastException - if the tag is not a Handle or a String

NullPointerException - if the tag is null

IllegalArgumentException - if the Handle is not a tag

getByTags

Collection<Handle> getByTags(Collection<?> tags)

Returns all Handles in this set containing the specified tags. The tags may be Handles or their String ids.

Parameters:

tags - tag Handles or their String ids

Returns:

all Handles in this set containing the specified tags

Throws:

ClassCastException - if any of the tags is not a Handle or a String

NullPointerException - if the specified collection contains one or more null elements or if the collection itself is null

IllegalArgumentException - if any of the Handles is not a tag

contains

boolean contains(Object o)

Returns true if this set contains the specified element. The element may be a Handle or its String id.

Specified by:

contains in interface Collection<Handle>

Specified by:

contains in interface Set<Handle>

Parameters:

o - Handle element or its String id whose presence in this set is to be tested

Returns:

true if this set contains the specified element

Throws:

ClassCastException - if the object is of not a Handle or a String

NullPointerException - if the specified element is null

add

boolean add(Handle handle)

Adds the specified element to this set if it is not already present. The Handle element must be present in this set's associated Space.

Specified by:

add in interface Collection<Handle>

Specified by:

add in interface Set<Handle>

Parameters:

handle - element to be added to this set

Returns:

true if this set did not already contain the specified element

Throws:

UnsupportedOperationException - if the add operation is not supported by this set

NullPointerException - if the specified element is null

IllegalArgumentException - if the Handle element is not present in this set's associated Space

remove

boolean remove(Object o)

Removes the specified element from this set if it is present. The element may be a Handle or its String id.

Specified by:

remove in interface Collection<Handle>

Specified by:

remove in interface Set<Handle>

Parameters:

o - Handle element or its String id to be removed from this set, if present

Returns:

true if this set contained the specified element

Throws:

UnsupportedOperationException - if the remove operation is not supported by this set

ClassCastException - if the object is of not a Handle or a String

NullPointerException - if the specified element is null

containsAll

boolean containsAll(Collection<?> c)

Returns true if this set contains all elements present in the specified collection. The elements may be Handles or their String ids.

Specified by:

containsAll in interface Collection<Handle>

Specified by:

containsAll in interface Set<Handle>

Parameters:

c - Handle elements or their String ids to be checked for containment in this set

Returns:

true if this set contains all elements of the specified collection

Throws:

ClassCastException - if any of the elements is not a Handle or a String

NullPointerException - if the specified collection contains one or more null elements or if the collection itself is null

addAll

boolean addAll(Collection<? extends Handle> c)

Adds all elements in the specified collection to this set if they're not already present. The Handle elements must be present in this set's associated Space.

Specified by:

addAll in interface Collection<Handle>

Specified by:

addAll in interface Set<Handle>

Parameters:

c - collection containing elements to be added to this set

Returns:

true if this set changed as a result of the call

Throws:

UnsupportedOperationException - if the addAll operation is not supported by this set

NullPointerException - if the specified collection contains one or more null elements or if the collection itself is null

IllegalArgumentException - if any of the Handle elements is not present within this set's associated Space

retainAll

boolean retainAll(Collection<?> c)

Retains only the elements in this set that are contained in the specified collection. The elements may be Handles or their String ids.

Specified by:

retainAll in interface Collection<Handle>

Specified by:

retainAll in interface Set<Handle>

Parameters:

c - collection containing elements to be retained in this set

Returns:

true if this set changed as a result of the call

Throws:

UnsupportedOperationException - if the retainAll operation is not supported by this set

ClassCastException - if any of the elements is not a Handle or a String

NullPointerException - if the specified collection contains one or more null elements or if the collection itself is null

removeAll

boolean removeAll(Collection<?> c)

Removes from this set all of its elements that are contained in the specified collection. The elements may be Handles or their String ids.

Specified by:

removeAll in interface Collection<Handle>

Specified by:

removeAll in interface Set<Handle>

Parameters:

c - collection containing elements to be removed from this set

Returns:

true if this set changed as a result of the call

Throws:

UnsupportedOperationException - if the removeAll operation is not supported by this set

ClassCastException - if any of the elements is not a Handle or a String

NullPointerException - if the specified collection contains one or more null elements or if the collection itself is null