org.crosswire.jsword.passage

## Interface KeyFactory

-     public interface KeyFactory

  A Factory for new Keys and KeyLists.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Key` | `createEmptyKeyList()` Fetch an empty Key to which we can add Keys.
    `Key` | `getGlobalKeyList()` Get a complete list of index entries.
    `Key` | `getKey(String name)` Someone has typed in a reference to find, but we need a Key to actually look it up.
    `Key` | `getValidKey(String name)` Get a Key for the name, if possible.

- - ### Method Detail

    - #### getGlobalKeyList

          Key getGlobalKeyList()

      Get a complete list of index entries. Create a Key that encompasses all of the known valid keys for the given context. For a dictionary this will include all of the entries in the dictionary, for a Bible this will probably include all the verses in the Bible, but a commentary may well miss some out.
      Returns:
        A Key that includes all of the known Keys

    - #### getValidKey

          Key getValidKey(String name)

      Get a Key for the name, if possible. Otherwise return an empty Key.
      Parameters:
        `name` -
      Returns:
        a valid key.

    - #### getKey

          Key getKey(String name)
                     throws NoSuchKeyException

      Someone has typed in a reference to find, but we need a Key to actually look it up. So we create a Key from the string if such a translation is possible. The returned Key may be a BranchKey if the string represents more than one Key.
      Parameters:
        `name` - The string to translate into a Key
      Returns:
        The Key corresponding to the input text
      Throws:
        `NoSuchKeyException` - If the name can not be parsed.

    - #### createEmptyKeyList

          Key createEmptyKeyList()

      Fetch an empty Key to which we can add Keys. Not all implementations of Key are able to hold any type of Key, It isn't reasonable to expect a Key of Bible verses (=Passage) to hold a dictionary Key. So each KeyFactory must be able to create you an empty Key to which you can safely add other Keys it generates.
      Returns:
        An empty Key that can hold other Keys from this factory.