Package me.datafox.dfxengine.handles.api

Interface HandleMap<T>

Type Parameters:
T - the type of mapped values
All Superinterfaces:
Map<Handle,T>
All Known Subinterfaces:
ValueMap
All Known Implementing Classes:
DelegatedValueMap, HashHandleMap, TreeHandleMap
public interface HandleMap<T> extends Map<Handle,T>
An extension of Map that may only contain Handle keys from a specified Space. Also has extra functionality to query entries based on their String id.

  • Method Details

    • getSpace

      Space getSpace()
      Returns the Space associated with this map. All Handle keys present in this map must be associated with this space.
      Returns:
      Space associated with this map

    • containsKeys

      boolean containsKeys(Collection<?> keys)
      Returns true if this map contains a mapping for all the specified keys. The keys may either be Handles or their String ids.
      Parameters:
      keys - Handle keys or their String ids whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for all the specified keys
      Throws:
      ClassCastException - if any of the keys are of an inappropriate type for this map
      NullPointerException - if any of the keys is null

    • putHandled

      T putHandled(T value)
      Associates a Handled value with its associated Handle. If the map previously contained a mapping for the key, the old value is replaced by the specified value. The Handle key must be present in this map's associated Space.
      Parameters:
      value - Handled value to be associated with its associated Handle key
      Returns:
      the previous value associated with the key, or null if none was present
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map
      ClassCastException - if the value does not implement Handled
      NullPointerException - if the specified value is null
      IllegalArgumentException - if the value's associated Handle is not present in this map's associated Space

    • unmodifiable

      HandleMap<T> unmodifiable()
      Returns an unmodifiable version of this map. All changes made to the original map will be reflected in the returned one.
      Returns:
      unmodifiable version of this map

    • getByTag

      Collection<T> getByTag(Object tag)
      Returns all values mapped to keys containing the specified tag. The tag may be a Handle or its String id.
      Parameters:
      tag - tag Handle or its String id
      Returns:
      all values mapped to keys 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<T> getByTags(Collection<?> tags)
      Returns all values mapped to keys containing the specified tag. The tags may be Handles or their String ids.
      Parameters:
      tags - tag Handles or their String ids
      Returns:
      all values mapped to keys containing the specified tags
      Throws:
      ClassCastException - if any of the tags are not Handles or a Strings
      NullPointerException - if any of the tags is null
      IllegalArgumentException - if any of the Handles is not a tag

    • containsKey

      boolean containsKey(Object key)
      Returns true if this map contains a mapping for the specified key. The key may either be a Handle or its String id.
      Specified by:
      containsKey in interface Map<Handle,T>
      Parameters:
      key - Handle key or its String id whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified key
      Throws:
      ClassCastException - if the key is of an inappropriate type for this map
      NullPointerException - if the specified key is null

    • get

      T get(Object key)
      Returns the value to which the specified key is mapped, or null if none is present. The key may either be a Handle or its String id.
      Specified by:
      get in interface Map<Handle,T>
      Parameters:
      key - Handle key or its String id whose associated value is to be returned
      Returns:
      the value to which the specified key is mapped, or null if none is present
      Throws:
      ClassCastException - if the key is of not a Handle or a String
      NullPointerException - if the specified key is null

    • put

      T put(Handle key, T value)
      Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified value. The Handle key must be present in this map's associated Space.
      Specified by:
      put in interface Map<Handle,T>
      Parameters:
      key - Handle key with which the specified value is to be associated with
      value - value to be associated with the specified key
      Returns:
      the previous value associated with the key, or null if none was present
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map
      NullPointerException - if the specified key or value is null
      IllegalArgumentException - if the Handle key is not present in this map's associated Space

    • remove

      T remove(Object key)
      Removes the mapping for a key from this map if it is present. Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key. The key may either be a Handle or its String id.
      Specified by:
      remove in interface Map<Handle,T>
      Parameters:
      key - Handle key or its String id whose mapping is to be removed from this map
      Returns:
      the previous value associated with key, or null if none was present
      Throws:
      UnsupportedOperationException - if the remove operation is not supported by this map
      ClassCastException - if the key is of not a Handle or a String
      NullPointerException - if the specified key is null

    • putAll

      void putAll(Map<? extends Handle,? extends T> map)
      Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling put(Handle, Object) on this map once for each mapping from key to value in the specified map. All Handle keys must be present in this map's associated Space.
      Specified by:
      putAll in interface Map<Handle,T>
      Parameters:
      map - mappings to be stored in this map
      Throws:
      UnsupportedOperationException - if the putAll operation is not supported by this map
      NullPointerException - if the specified map is null or contains null keys or values
      IllegalArgumentException - if the specified map contains a Handle key that is not present in this map's associated Space

    • getOrDefault

      T getOrDefault(Object key, T defaultValue)
      Returns true if this map contains a mapping for the specified key, or the specified default value if none is present. The key may either be a Handle or its String id.
      Specified by:
      getOrDefault in interface Map<Handle,T>
      Parameters:
      key - Handle key or its String id whose associated value is to be returned
      defaultValue - the default mapping of the key
      Returns:
      the value to which the specified key is mapped, or the specified default value if this map contains no mapping for the key
      Throws:
      ClassCastException - if the key is of not a Handle or a String
      NullPointerException - if the specified key is null

    • putIfAbsent

      T putIfAbsent(Handle key, T value)
      Associates the specified key with the specified value and returns null if the specified key is not already associated with a value, otherwise returns the current value.
      Specified by:
      putIfAbsent in interface Map<Handle,T>
      Parameters:
      key - Handle key with which the specified value is to be associated with
      value - value to be associated with the specified key
      Returns:
      the previous value associated with the specified key, or null if there was no mapping for the key
      Throws:
      UnsupportedOperationException - if the put operation is not supported by this map
      NullPointerException - if the specified key or value is null
      IllegalArgumentException - if the Handle key is not present in this map's associated Space

    • remove

      boolean remove(Object key, Object value)
      Removes the entry for the specified key only if it is currently mapped to the specified value. The key may either be a Handle or its String id.
      Specified by:
      remove in interface Map<Handle,T>
      Parameters:
      key - Handle key or its String id with which the specified value is associated
      value - value expected to be associated with the specified key
      Returns:
      true if the value was removed
      Throws:
      UnsupportedOperationException - if the remove operation is not supported by this map
      ClassCastException - if the key is of not a Handle or a String
      NullPointerException - if the specified key or value is null