Class Some<T extends KeyValue>

java.lang.Object
org.logicmachine.rebl.common.Some<T>
Type Parameters:
T - denotes the type of 'singular' class which is being 'pluralised' by this instance
All Implemented Interfaces:
Iterable<T>
Direct Known Subclasses:
EnvironmentObjects, Many, Resources, StateMachines
public class Some<T extends KeyValue> extends Object implements Iterable<T>
This class is intended to be used in those circumstances where we have a relatively small collection of 'things' which we wish to refer to directly, by key.

For example, we may have a small collection of resources. We would not want to have to iterate over this collection each time we needed access to a specific resource; rather we would prefer to access the required resource directly.

As an implementation note, this class is backed by a Map. Therefore the 'find()' and 'findAll()' methods complete in O(1) time.

However since this is backed by a Map, duplicate keys are not supported. Therefore the 'findAll()' method within this class will only return a list containing one element at most.

See also the related 'Many' class, which is backed by a List and which therefore also supports duplicate keys.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    allowNull
    If true, the 'find()' method will return null on no match.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Some()
    Default constructor.
    Some(T... entities)
    Constructor allowing a number of 'singular' instances to be added to this collection class.

  • Method Summary

    Modifier and Type
    Method
    Description
    Some<T>
    add(T entity)
    This method allows the given 'entity' to be added to the current collection.
    Some<T>
    addAll(Collection<T> entities)
    Adds all of the given 'entities' to the collection associated with this instance.
    Some<T>
    addAll(T... entities)
    Adds all of the given 'entities' to the collection associated with this instance.
    void
    allowNull()
    By default, the 'find()' method will return a non-null 'empty' instance on no match.
    Some<T>
    clear()
    Removes all elements from this collection.
    Maybe
    find(Object key, Maybe empty)
    Searches this collection for an element whose key matches the given 'key' value.
    Collection<T>
    findAll(Object key)
    Searches this collection for all elements whose keys match the given 'key' value.
    Collection<T>
    getCollection()
    Returns all of the objects within this collection.
    Iterator<T>
    iterator()
     
    int
    size()
    Returns the number of elements currently held within this collection.
    String
    toString()
     
    String
    toString(int indentLevel)
    Returns a formatted string representation of the contents of this class.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Field Details

    • allowNull

      protected boolean allowNull
      If true, the 'find()' method will return null on no match.

      If false, the 'find()' method requires a non-null 'empty' parameter which will be returned on no match.

      This flag defaults to false, meaning that the default behaviour of the 'find()' method requires an 'empty' instance to return on no match.

  • Constructor Details

    • Some

      public Some()
      Default constructor.

    • Some

      public Some(T... entities)
      Constructor allowing a number of 'singular' instances to be added to this collection class.
      Parameters:
      entities - the list of 'singular' instances to add

  • Method Details

    • allowNull

      public void allowNull()
      By default, the 'find()' method will return a non-null 'empty' instance on no match.

      Calling this method allows the 'find()' method to return null on no match.

    • add

      public Some<T> add(T entity)
      This method allows the given 'entity' to be added to the current collection.
      Parameters:
      entity - holds the entity to add to this collection
      Returns:
      a handle to self to allow chaining

    • addAll

      public Some<T> addAll(T... entities)
      Adds all of the given 'entities' to the collection associated with this instance.
      Parameters:
      entities - the list of 'singular' instances to add
      Returns:
      a handle to self to allow chaining

    • addAll

      public Some<T> addAll(Collection<T> entities)
      Adds all of the given 'entities' to the collection associated with this instance.
      Parameters:
      entities - the list of 'singular' instances to add
      Returns:
      a handle to self to allow chaining

    • getCollection

      public Collection<T> getCollection()
      Returns all of the objects within this collection.
      Returns:
      this collection

    • size

      public int size()
      Returns the number of elements currently held within this collection.
      Returns:
      the current size of this collection

    • clear

      public Some<T> clear()
      Removes all elements from this collection.
      Returns:
      a handle to self to allow chaining

    • iterator

      public Iterator<T> iterator()
      Specified by:
      iterator in interface Iterable<T extends KeyValue>

    • find

      public Maybe find(Object key, Maybe empty)
      Searches this collection for an element whose key matches the given 'key' value. Returns the first matching element on match, or the given 'empty' instance on no match.

      As an implementation note, this class is backed by a Map. Therefore the 'find()' and 'findAll()' methods complete in O(1) time.

      See also the related 'Many' class which is backed by a List and whose 'find()' and 'findAll()' methods complete in O(n) time.
      Parameters:
      key - holds the key to search for (can be null)
      empty - holds the empty instance which will be returned on no match (must not be null unless the 'allowNull()' method has previously been called)
      Returns:
      either the first element matching the given 'key', or the specified 'empty' instance on no match or if 'key' is null

    • findAll

      public Collection<T> findAll(Object key)
      Searches this collection for all elements whose keys match the given 'key' value. Returns a collection of matching elements, or an empty non-null collection on no match.

      As an implementation note, this class is backed by a Map. Therefore the 'find()' and 'findAll()' methods complete in O(1) time. However, since a Map cannot hold a duplicate key, this 'findAll()' method will only ever return one match, at most.

      If support for multiple keys is required, use the 'Many' collection class and call its 'findAll()' method.

      See also the related 'Many' class which is backed by a List and whose 'find()' and 'findAll()' methods complete in O(n) time.
      Parameters:
      key - holds the key to search for
      Returns:
      either a collection of elements matching the given 'key', or an empty non-null collection on no match

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      public String toString(int indentLevel)
      Returns a formatted string representation of the contents of this class.

      The components within the returned string will be indented to the level specified by the input parameter.
      Parameters:
      indentLevel - specifies the required level of indentation to be applied (can be 0)
      Returns:
      a string representation of this instance