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 or later
5    * as published by the Free Software Foundation. This program is distributed
6    * in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
7    * the 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   * © CrossWire Bible Society, 2005 - 2016
18   *
19   */
20  package org.crosswire.common.config;
21  
22  import java.util.ResourceBundle;
23  
24  import org.jdom2.Element;
25  
26  /**
27   * Choice is the fundamental building block of the config system.
28   * 
29   * Every Choice must be able to:
30   * <ul>
31   * <li>get and set itself using a String</li>
32   * <li>provide some simple help about itself</li>
33   * <li>elect a user level for itself (Beginner, Intermediate, Advanced)</li>
34   * <li>provide a GUI editor for itself</li>
35   * </ul>
36   * 
37   * @see gnu.lgpl.License The GNU Lesser General Public License for details.
38   * @author Joe Walker
39   */
40  public interface Choice {
41      /**
42       * String value to associate with the name (key)
43       * 
44       * @param option the option
45       * @param configResources the resource bundle to load
46       * @throws StartupException if startup is not possible
47       */
48      void init(Element option, ResourceBundle configResources) throws StartupException;
49  
50      /**
51       * The key of the option.
52       * 
53       * @return String The key string as supplied in config.xml
54       */
55      String getKey();
56  
57      /**
58       * The full path of the option.
59       * 
60       * @return String The path string as supplied in config.properties
61       */
62      String getFullPath();
63  
64      /**
65       * Sets the full path of the option.
66       * 
67       * @param fullPath
68       *            The path string as supplied in config.properties
69       */
70      void setFullPath(String fullPath);
71  
72      /**
73       * The type by which UIs can pick an appropriate editor
74       * 
75       * @return String The type string as supplied in config.xml
76       */
77      String getType();
78  
79      /**
80       * The class that this Choice works on. Used to decide how to display the
81       * choice to the user.
82       * 
83       * @return The Class that this Choice works using.
84       */
85      Class<? extends Object> getConversionClass();
86  
87      /**
88       * String value to associate with the name (key)
89       * 
90       * @return value of this Choice
91       */
92      String getString();
93  
94      /**
95       * String value to associate with this Field. This method can throw any
96       * Exception since almost anything could go wrong at this point. The Config
97       * dialog ought to cope with any errors.
98       * 
99       * @param value
100      *            The new value for this Choice
101      * @throws ConfigException if there is a problem with the configuration
102      */
103     void setString(String value) throws ConfigException;
104 
105     /**
106      * Gets a brief description of what is going on
107      * 
108      * @return Some help text
109      */
110     String getHelpText();
111 
112     /**
113      * Sets a brief description of what is going on
114      * 
115      * @param helptext
116      *            Some help text
117      */
118     void setHelpText(String helptext);
119 
120     /**
121      * Is this Choice OK to write out to a file, or should we use settings in
122      * this run of the program, but forget them for next time. A typical use of
123      * this is for password configuration.
124      * 
125      * @return True if it is safe to store the value in a config file.
126      */
127     boolean isSaveable();
128 
129     /**
130      * Whether this should be visible in a Config Editor.
131      * 
132      * @return hidden or visible
133      */
134     boolean isHidden();
135 
136     /**
137      * Whether this should be ignored altogether in a Config Editor.
138      * 
139      * @return hidden or visible
140      */
141     boolean isIgnored();
142 
143     /**
144      * Do we need to restart the program in order for this change to have
145      * effect?
146      * 
147      * @return True if a restart is required
148      */
149     boolean requiresRestart();
150 }
151