org.mitre.sim.api3
Interface Population

All Known Implementing Classes:
ReferencePopulation

public interface Population

Interface that represents sets of entities. A Population is a set of instances of Entity or a subclass. A Population instance is obtained originally by invoking createPopulation on an Entity. The membership of a Population can be refined by creating a new instance, using the methods applyFilter, join, or rejectFilter. An Entity can wait for the state of a Population to change by using the Trigger instances returned by the methods becomesEmpty, excludes, includes, sizeBelow, or sizeExceeds.

A Population will never contain a null member. A Population will never contain duplicate members.

The membership of a Population will not change unless an Entity either



Copyright © 2003-2004 The MITRE Corporation


Method Summary
 Population applyFilter(Filter filter)
          Create new filtered Population.
 Trigger becomesEmpty()
          Trigger for Population being empty.
 boolean contains(Entity e)
          Returns true if this contains the specified element.
 Trigger excludes(Entity entity)
          Trigger when Entity not a member.
 Trigger includes(Entity entity)
          Trigger when Entity is a member.
 boolean isEmpty()
          Returns true if this Population contains no members.
 java.util.Iterator iterator()
          Returns an iterator over the members in this Population.
 Population join(Population pop)
          Create new combination Population.
 Population rejectFilter(Filter filter)
          Create new filtered Population.
 int size()
          Returns the number of members in this Population.
 Trigger sizeBelow(int threshold)
          Trigger on Population size.
 Trigger sizeExceeds(int threshold)
          Trigger on Population size.
 Entity[] toArray()
          Returns an array containing all the members in this Population.
 

Method Detail

applyFilter

public Population applyFilter(Filter filter)
Create new filtered Population. Create new Population instance whose members are all the members of the current instance for which the filter returns true.

Parameters:
filter - Developer-supplied instance of Filter implementation
Returns:
new Population

becomesEmpty

public Trigger becomesEmpty()
Trigger for Population being empty. Create Trigger whose condition returns true when the size of the current Population is zero.

Returns:
new Trigger

contains

public boolean contains(Entity e)
Returns true if this contains the specified element. More formally, returns true if and only if this contains an element elt such that elt.equals(e). (Note that Entity does not override equals().)

Parameters:
e - Entity whose membership is to be tested
Returns:
true if e is member of current instance

excludes

public Trigger excludes(Entity entity)
Trigger when Entity not a member. Create Trigger whose condition returns true when entity is not a member of the current Population.

Parameters:
entity - Entity to be excluded
Returns:
new Trigger

includes

public Trigger includes(Entity entity)
Trigger when Entity is a member. Create Trigger whose condition returns true when entity is a member of the current Population.

Parameters:
entity - Entity to be included
Returns:
new Trigger

isEmpty

public boolean isEmpty()
Returns true if this Population contains no members.

Returns:
true if this Population contains no members

iterator

public java.util.Iterator iterator()
Returns an iterator over the members in this Population. There are no guarantees concerning the order in which the members are returned. The behavior of the iterator is undefined if the Entity takes any action while holding an Iterator returned by this method that might change the membership of the Population.

Returns:
an Iterator over the members of this Population

join

public Population join(Population pop)
Create new combination Population. Create new Population instance whose members are all the members of the current instance and all the members of pop. Like all instances of Population, the new instance contains no duplicates.

Returns:
new Population

rejectFilter

public Population rejectFilter(Filter filter)
Create new filtered Population. Create new Population instance whose members are all the members of the current instance for which the filter returns false.

Parameters:
filter - Developer-supplied instance of Filter implementation
Returns:
new Population

size

public int size()
Returns the number of members in this Population. If this Population contains more than Integer.MAX_VALUE members, returns Integer.MAX_VALUE.

Returns:
number of members of this Population

sizeBelow

public Trigger sizeBelow(int threshold)
Trigger on Population size. Create Trigger whose condition returns true when the size of the current Population is less than threshold.

Parameters:
threshold - size below which Trigger is true
Returns:
new Trigger

sizeExceeds

public Trigger sizeExceeds(int threshold)
Trigger on Population size. Create Trigger whose condition returns true when the size of the current Population is greater than threshold.

Parameters:
threshold - size above which Trigger is true
Returns:
new Trigger

toArray

public Entity[] toArray()
Returns an array containing all the members in this Population. There are no guarantees as to the order of the array elements. The caller is free to modify the returned array. If the membership of the Population changes after this call returns, the array is not modified. Thus the array is a snapshot of the membership at the time of the call.

Returns:
an array containing all the members of this Population