1   /**
2    * Distribution License:
3    * JSword is free software; you can redistribute it and/or modify it under
4    * the terms of the GNU Lesser General Public License, version 2.1 as published by
5    * the Free Software Foundation. This program is distributed in the hope
6    * that it will be useful, but WITHOUT ANY WARRANTY; without even the
7    * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
8    * See the GNU Lesser General Public License for more details.
9    *
10   * The License is available on the internet at:
11   *       http://www.gnu.org/copyleft/lgpl.html
12   * or by writing to:
13   *      Free Software Foundation, Inc.
14   *      59 Temple Place - Suite 330
15   *      Boston, MA 02111-1307, USA
16   *
17   * Copyright: 2005
18   *     The copyright to this program is held by it's authors.
19   *
20   * ID: $Id: KeyFactory.java 1966 2009-10-30 01:15:14Z dmsmith $
21   */
22  package org.crosswire.jsword.passage;
23  
24  /**
25   * A Factory for new Keys and KeyLists.
26   * 
27   * @see gnu.lgpl.License for license details.<br>
28   *      The copyright to this program is held by it's authors.
29   * @author Joe Walker [joe at eireneh dot com]
30   */
31  public interface KeyFactory {
32      /**
33       * Get a complete list of index entries. Create a Key that encompasses all
34       * of the known valid keys for the given context. For a dictionary this will
35       * include all of the entries in the dictionary, for a Bible this will
36       * probably include all the verses in the Bible, but a commentary may well
37       * miss some out.
38       * 
39       * @return A Key that includes all of the known Keys
40       */
41      Key getGlobalKeyList();
42  
43      /**
44       * Get a Key for the name, if possible. Otherwise return an empty Key.
45       * 
46       * @param name
47       * @return a valid key.
48       */
49      Key getValidKey(String name);
50  
51      /**
52       * Someone has typed in a reference to find, but we need a Key to actually
53       * look it up. So we create a Key from the string if such a translation is
54       * possible. The returned Key may be a BranchKey if the string represents
55       * more than one Key.
56       * 
57       * @param name
58       *            The string to translate into a Key
59       * @return The Key corresponding to the input text
60       * @throws NoSuchKeyException
61       *             If the name can not be parsed.
62       */
63      Key getKey(String name) throws NoSuchKeyException;
64  
65      /**
66       * Fetch an empty Key to which we can add Keys. Not all implementations of
67       * Key are able to hold any type of Key, It isn't reasonable to expect a Key
68       * of Bible verses (=Passage) to hold a dictionary Key. So each KeyFactory
69       * must be able to create you an empty Key to which you can safely add other
70       * Keys it generates.
71       * 
72       * @return An empty Key that can hold other Keys from this factory.
73       */
74      Key createEmptyKeyList();
75  }
76