Package me.datafox.dfxengine.handles.api

Interface Handle

All Superinterfaces:
Comparable<Handle>
All Known Implementing Classes:
HandleImpl
public interface Handle extends Comparable<Handle>

A handle is an identifier used for various objects. It contains a String id, an integer index and an arbitrary number of tags, which are also handles. A handle is always contained in a single Space, and may belong to one or more Groups within that Space. A handle's id may not be empty or blank and may consist of printable ASCII characters, with the exception of the colon (:) which is reserved as a separator for subhandles.

A handle may have any number of subhandles. The ids of subhandles are in the format handle:subhandle. A subhandle may not have subhandles of its own. Subhandles may be used in any situation where a handle would need to have parameters attached to it that are also handles. Subhandles are used internally for the identifying handles of Spaces to identify their respective Groups.

Every handle has an index and a sub-index. Indices are unique for handles within a given Space, starting from 0. Sub-indices are unique for subhandles within their parent handle, also starting from 0. A handle that is not a subhandle has a sub-index of -1.

  • Method Details

    • getHandleManager

      HandleManager getHandleManager()
      Returns:
      HandleManager managing this handle

    • getSpace

      Space getSpace()
      Returns:
      Space that this handle is contained in

    • getId

      String getId()
      Returns:
      String id of this handle

    • getIndex

      int getIndex()
      Returns:
      index of this handle

    • getSubIndex

      int getSubIndex()
      Returns -1 if this handle is not a subhandle.
      Returns:
      sub-index of this handle

    • getSubHandles

      HandleSet getSubHandles()
      Returns:
      subhandles contained in this handle

    • createSubHandle

      Handle createSubHandle(String id)
      Creates a new subhandle. Throws UnsupportedOperationException if this handle is a subhandle or is associated with a Space (subhandles for space handles are used exclusively for Groups, use Space.createGroup(String) instead).
      Parameters:
      id - String id for the new subhandle
      Returns:
      created subhandle
      Throws:
      NullPointerException - if the id is null
      IllegalArgumentException - if the id is empty, blank, contains non-ASCII or non-printable characters or the colon (:), or if a subhandle with the given id already exists in this handle
      UnsupportedOperationException - if this handle is a subhandle or if this handle is associated with a Space

    • getOrCreateSubHandle

      Handle getOrCreateSubHandle(String id)
      Creates a subhandle with the specified id if it does not already exist and returns the subhandle with that id. Throws UnsupportedOperationException if this handle is a subhandle or is associated with a Space (subhandles for space handles are used exclusively for Groups) and a subhandle with the specified id is not present. Use Space.getOrCreateGroup(String).
      Parameters:
      id - String id for the subhandle
      Returns:
      created or pre-existing subhandle
      Throws:
      NullPointerException - if the id is null
      IllegalArgumentException - if the id is empty, blank, contains non-ASCII or non-printable characters or the colon (:)
      UnsupportedOperationException - if this handle is a subhandle or if this handle is associated with a Space and a subhandle with the specified id is not present

    • getTags

      HandleSet getTags()
      The returned HandleSet is modifiable and tags may be added to or removed from it at will.
      Returns:
      HandleSet containing the tags of this handle

    • isSubHandle

      boolean isSubHandle()
      Returns:
      true if this handle is a subhandle

    • compareTo

      int compareTo(Handle o)
      Compares this handle with the specified handle for order. Returns a negative integer, zero, or a positive integer as this handle is less than, equal to, or greater than the specified handle. The order of handles is specified by three things. If the Spaces of the handles are different, comparison is done with the space's handle. If the spaces are the same, comparison is done with the index, using the sub-index if the indices are also the same.
      Specified by:
      compareTo in interface Comparable<Handle>
      Parameters:
      o - handle to be compared.
      Returns:
      negative integer, zero, or a positive integer as this handle is less than, equal to, or greater than the specified handle
      Throws:
      NullPointerException - if the specified handle is null