Package de.gebit.integrity.remoting.entities.setlist

## Class SetList

- java.lang.Object
- - de.gebit.integrity.remoting.entities.setlist.SetList

- All Implemented Interfaces:
    `Serializable`

      public class SetList
      extends Object
      implements Serializable

  The Setlist is a data structure to contain a test execution plan as well as test results. Its name refers to the setlists used by bands to write down the songs played during a concert (okay, it's a stupid reason to name it like that, but hey, I didn't have any better idea ;-) ).
  Setlists are stored in a flat way, with the entries actually resembling a tree structure by referencing each other via their IDs. This allows for easy incremental update of single entries regardless of the size of the subtrees below them, as long as the IDs of each entry stay the same.
  Author:
    Rene Schneider - initial API and implementation
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SetList()` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addReference​(SetListEntry aReferringEntry, SetListEntryAttributeKeys anAttributeKey, SetListEntry aReferredEntry)` | Adds a reference to another entry to a specified parent entry under a specified attribute key.
    `protected String` | `calculateFullyQualifiedBaseName​(SetListEntry anEntry)` | Determines the fully qualified base name for an entry (this entry is possibly extended with a counter to resolve duplicates, hence it is a base name).
    `SetListEntry` | `createEntry​(SetListEntryTypes aType)` | Creates a new entry.
    `protected SetListEntryResultStates` | `determineEntryResultState​(SetListEntry anEntry)` | Determines the result state for a specific entry.
    `void` | `dumpEntries​(PrintStream aStream)` | Performs a full dump of all entries in the setlist into the given stream.
    `SetListEntry` | `findEntryByFullyQualifiedName​(String aName)` | Finds an entry based on a given fully qualified name.
    `List<SetListEntry>` | `getEntriesInExecution()` |
    `SetListEntry` | `getEntryInExecution()` |
    `int` | `getEntryListPosition()` |
    `String[]` | `getForkExecutingEntry​(SetListEntry anEntry)` | Returns the name of the fork that executes the given entry.
    `String` | `getFullyQualifiedName​(SetListEntry anEntry)` | Gets the fully qualified name for an entry.
    `String` | `getFullyQualifiedName​(Integer anEntryReference)` | Gets the fully qualified name for an entry.
    `Integer` | `getLastCreatedEntryId​(SetListEntryTypes aType)` | Returns the ID that was last given to an entry of the specified type.
    `Integer` | `getLastCreatedEntryId​(SetListEntryTypes... someTypes)` | Returns the lowest ID given to any of the specified entry types.
    `int` | `getNumberOfEntriesInResultState​(SetListEntryResultStates aState)` | Returns the number of entries in the given result state.
    `int` | `getNumberOfExecutableEntries()` |
    `SetListEntry` | `getParent​(SetListEntry anEntry)` | Returns the parent entry for a given entry.
    `SetListEntryResultStates` | `getResultStateForEntry​(SetListEntry anEntry)` | Returns the result state of an entry from the map.
    `SetListEntryResultStates` | `getResultStateForExecutableEntry​(int aPosition)` | Returns the result state of an executable entry at the specified position in the list of executable entries.
    `SetListEntry` | `getRootEntry()` |
    `void` | `integrateUpdates​(SetListEntry[] someUpdatedEntries)` | Integrates a list of updated entries into this `SetList`.
    `boolean` | `isEntryInExecution​(SetListEntry anEntry)` | Checks whether a given entry is currently being executed.
    `void` | `recreateTransientData()` | Recreates transient data from the list of entries.
    `SetListEntry` | `resolveReference​(Integer aReference)` | Resolves a single entry reference (ID).
    `List<SetListEntry>` | `resolveReferences​(SetListEntry anEntry, SetListEntryAttributeKeys anAttributeKey)` | Returns a list of entries that are referred by the given entry under the given attribute key.
    `List<SetListEntry>` | `resolveReferences​(List<Integer> someItemIds)` | Resolves a list of entry IDs to the actual entries.
    `void` | `rewind()` | Clears the entry list position.
    `void` | `setEntryInExecutionReference​(Integer anEntryReference)` | Updates the reference to the entry that's currently in execution, recalculating the execution path.
    `String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SetList

          public SetList()

  - ### Method Detail

    - #### recreateTransientData

          public void recreateTransientData()

      Recreates transient data from the list of entries. Used after deserialization of the whole structure in order to prepare it for being actually used. Transient entries are redundant and not transmitted for size reasons.

    - #### determineEntryResultState

          protected SetListEntryResultStates determineEntryResultState​(SetListEntry anEntry)

      Determines the result state for a specific entry.
      Parameters:
        `anEntry` - the entry
      Returns:
        the result state or null in case the entry doesn't have a result

    - #### getNumberOfExecutableEntries

          public int getNumberOfExecutableEntries()

    - #### getNumberOfEntriesInResultState

          public int getNumberOfEntriesInResultState​(SetListEntryResultStates aState)

      Returns the number of entries in the given result state.
      Parameters:
        `aState` - the state to query
      Returns:
        the number

    - #### getResultStateForEntry

          public SetListEntryResultStates getResultStateForEntry​(SetListEntry anEntry)

      Returns the result state of an entry from the map.
      Parameters:
        `anEntry` - the entry
      Returns:
        the result state, or null if the entry doesn't have one

    - #### getResultStateForExecutableEntry

          public SetListEntryResultStates getResultStateForExecutableEntry​(int aPosition)

      Returns the result state of an executable entry at the specified position in the list of executable entries.
      Parameters:
        `aPosition` - the position
      Returns:
        the result state, or null if the position doesn't have one

    - #### createEntry

          public SetListEntry createEntry​(SetListEntryTypes aType)

      Creates a new entry. Uses up an entry ID in the process.
      Note that this doesn't necessarily create a new entry, it may also reuse an already existing one! It's part of the concept of the `SetList` to actually create entries on the first (dry) run through the tests, and reuse old entries during the second (actual) test run, updating their result status etc. in the process.
      Parameters:
        `aType` - the type of entry
      Returns:
        the new entry

    - #### getLastCreatedEntryId

          public Integer getLastCreatedEntryId​(SetListEntryTypes aType)

      Returns the ID that was last given to an entry of the specified type.
      Parameters:
        `aType` - the type
      Returns:
        the ID if available, or null if none has been given to an entry of that type

    - #### getLastCreatedEntryId

          public Integer getLastCreatedEntryId​(SetListEntryTypes... someTypes)

      Returns the lowest ID given to any of the specified entry types.
      Parameters:
        `someTypes` - the types
      Returns:
        the ID if available, or null if none has been given to any entry of the types

    - #### addReference

          public void addReference​(SetListEntry aReferringEntry,
                                   SetListEntryAttributeKeys anAttributeKey,
                                   SetListEntry aReferredEntry)

      Adds a reference to another entry to a specified parent entry under a specified attribute key.
      Parameters:
        `aReferringEntry` - the parent entry
        `anAttributeKey` - the attribute key under which the reference shall be created
        `aReferredEntry` - the entry to refer

    - #### rewind

          public void rewind()

      Clears the entry list position.

    - #### integrateUpdates

          public void integrateUpdates​(SetListEntry[] someUpdatedEntries)

      Integrates a list of updated entries into this `SetList`.
      Parameters:
        `someUpdatedEntries` - the updated entries

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### resolveReferences

          public List<SetListEntry> resolveReferences​(SetListEntry anEntry,
                                                      SetListEntryAttributeKeys anAttributeKey)

      Returns a list of entries that are referred by the given entry under the given attribute key.
      Parameters:
        `anEntry` - the entry
        `anAttributeKey` - the attribute key
      Returns:
        the list of resolved entries

    - #### resolveReferences

          public List<SetListEntry> resolveReferences​(List<Integer> someItemIds)

      Resolves a list of entry IDs to the actual entries.
      Parameters:
        `someItemIds` - the IDs to resolve
      Returns:
        the list of entries

    - #### resolveReference

          public SetListEntry resolveReference​(Integer aReference)

      Resolves a single entry reference (ID).
      Parameters:
        `aReference` - the ID of the entry
      Returns:
        the entry, or null if there is none with that ID

    - #### getRootEntry

          public SetListEntry getRootEntry()

    - #### getParent

          public SetListEntry getParent​(SetListEntry anEntry)

      Returns the parent entry for a given entry.
      Parameters:
        `anEntry` - the child entry
      Returns:
        the parent, or null if none was found

    - #### getFullyQualifiedName

          public String getFullyQualifiedName​(SetListEntry anEntry)

      Gets the fully qualified name for an entry. For more info regarding this name, see `fullyQualifiedNameMap`.
      Parameters:
        `anEntry` - the entry to look for
      Returns:
        the fully qualified name

    - #### getFullyQualifiedName

          public String getFullyQualifiedName​(Integer anEntryReference)

      Gets the fully qualified name for an entry. For more info regarding this name, see `fullyQualifiedNameMap`.
      Parameters:
        `anEntryReference` - the entry to look for
      Returns:
        the fully qualified name

    - #### findEntryByFullyQualifiedName

          public SetListEntry findEntryByFullyQualifiedName​(String aName)

      Finds an entry based on a given fully qualified name. For more info regarding this name, see `fullyQualifiedNameMap`.
      Parameters:
        `aName` - the name to search for
      Returns:
        the entry or null if none was found

    - #### calculateFullyQualifiedBaseName

          protected String calculateFullyQualifiedBaseName​(SetListEntry anEntry)

      Determines the fully qualified base name for an entry (this entry is possibly extended with a counter to resolve duplicates, hence it is a base name). For more info regarding this name, see `fullyQualifiedNameMap`.
      Parameters:
        `anEntry` - the entry to calculate the name for
      Returns:
        the name

    - #### setEntryInExecutionReference

          public void setEntryInExecutionReference​(Integer anEntryReference)

      Updates the reference to the entry that's currently in execution, recalculating the execution path.
      Parameters:
        `anEntryReference` - the new entry in execution

    - #### getEntryInExecution

          public SetListEntry getEntryInExecution()

    - #### getEntryListPosition

          public int getEntryListPosition()

    - #### getEntriesInExecution

          public List<SetListEntry> getEntriesInExecution()

    - #### isEntryInExecution

          public boolean isEntryInExecution​(SetListEntry anEntry)

      Checks whether a given entry is currently being executed.
      Parameters:
        `anEntry` - the entry
      Returns:
        true if the entry is being executed, false otherwise

    - #### getForkExecutingEntry

          public String[] getForkExecutingEntry​(SetListEntry anEntry)

      Returns the name of the fork that executes the given entry.
      Parameters:
        `anEntry` - the entry
      Returns:
        the forks' name (index 0) and description (index 1, if available, otherwise null) or null if the entry is executed by the master

    - #### dumpEntries

          public void dumpEntries​(PrintStream aStream)

      Performs a full dump of all entries in the setlist into the given stream.
      Parameters:
        `aStream` - the stream to write into