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