001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.dialogs;
011:
012: import java.io.IOException;
013: import java.io.Reader;
014: import java.io.Writer;
015:
016: /**
017: * An interface to a storage mechanism for making dialog settings persistent.
018: * The store manages a collection of key/value pairs. The keys must be strings
019: * and the values can be either, strings or array of strings. Convenience API to
020: * convert primitive types to strings is provided.
021: */
022: public interface IDialogSettings {
023: /**
024: * Create a new section in the receiver and return it.
025: *
026: * @param name
027: * the name of the new section
028: * @return the new section
029: */
030: public IDialogSettings addNewSection(String name);
031:
032: /**
033: * Add a section in the receiver.
034: *
035: * @param section
036: * the section to be added
037: */
038: public void addSection(IDialogSettings section);
039:
040: /**
041: * Returns the value of the given key in this dialog settings.
042: *
043: * @param key
044: * the key
045: * @return the value, or <code>null</code> if none
046: */
047: public String get(String key);
048:
049: /**
050: * Returns the value, an array of strings, of the given key in this dialog
051: * settings.
052: *
053: * @param key
054: * the key
055: * @return the array of string, or <code>null</code> if none
056: */
057: public String[] getArray(String key);
058:
059: /**
060: * Convenience API. Convert the value of the given key in this dialog
061: * settings to a boolean and return it.
062: *
063: * @param key
064: * the key
065: * @return the boolean value, or <code>false</code> if none
066: */
067: public boolean getBoolean(String key);
068:
069: /**
070: * Convenience API. Convert the value of the given key in this dialog
071: * settings to a double and return it.
072: *
073: * @param key
074: * the key
075: * @return the value coverted to double, or throws
076: * <code>NumberFormatException</code> if none
077: *
078: * @exception NumberFormatException
079: * if the string value does not contain a parsable number.
080: * @see java.lang.Double#valueOf(java.lang.String)
081: */
082: public double getDouble(String key) throws NumberFormatException;
083:
084: /**
085: * Convenience API. Convert the value of the given key in this dialog
086: * settings to a float and return it.
087: *
088: * @param key
089: * the key
090: * @return the value coverted to float, or throws
091: * <code>NumberFormatException</code> if none
092: *
093: * @exception NumberFormatException
094: * if the string value does not contain a parsable number.
095: * @see java.lang.Float#valueOf(java.lang.String)
096: */
097: public float getFloat(String key) throws NumberFormatException;
098:
099: /**
100: * Convenience API. Convert the value of the given key in this dialog
101: * settings to a int and return it.
102: *
103: * @param key
104: * the key
105: * @return the value coverted to int, or throws
106: * <code>NumberFormatException</code> if none
107: *
108: * @exception NumberFormatException
109: * if the string value does not contain a parsable number.
110: * @see java.lang.Integer#valueOf(java.lang.String)
111: */
112: public int getInt(String key) throws NumberFormatException;
113:
114: /**
115: * Convenience API. Convert the value of the given key in this dialog
116: * settings to a long and return it.
117: *
118: * @param key
119: * the key
120: * @return the value coverted to long, or throws
121: * <code>NumberFormatException</code> if none
122: *
123: * @exception NumberFormatException
124: * if the string value does not contain a parsable number.
125: * @see java.lang.Long#valueOf(java.lang.String)
126: */
127: public long getLong(String key) throws NumberFormatException;
128:
129: /**
130: * Returns the IDialogSettings name.
131: *
132: * @return the name
133: */
134: public String getName();
135:
136: /**
137: * Returns the section with the given name in this dialog settings.
138: *
139: * @param sectionName
140: * the key
141: * @return IDialogSettings (the section), or <code>null</code> if none
142: */
143: public IDialogSettings getSection(String sectionName);
144:
145: /**
146: * Returns all the sections in this dialog settings.
147: *
148: * @return the section, or <code>null</code> if none
149: */
150: public IDialogSettings[] getSections();
151:
152: /**
153: * Load a dialog settings from a stream and fill the receiver with its
154: * content.
155: *
156: * @param reader
157: * a Reader specifying the stream where the settings are read
158: * from.
159: * @throws IOException
160: */
161: public void load(Reader reader) throws IOException;
162:
163: /**
164: * Load a dialog settings from a file and fill the receiver with its
165: * content.
166: *
167: * @param fileName
168: * the name of the file the settings are read from.
169: * @throws IOException
170: */
171: public void load(String fileName) throws IOException;
172:
173: /**
174: * Adds the pair <code>key/value</code> to this dialog settings.
175: *
176: * @param key
177: * the key.
178: * @param value
179: * the value to be associated with the <code>key</code>
180: */
181: public void put(String key, String[] value);
182:
183: /**
184: * Convenience API. Converts the double <code>value</code> to a string and
185: * adds the pair <code>key/value</code> to this dialog settings.
186: *
187: * @param key
188: * the key.
189: * @param value
190: * the value to be associated with the <code>key</code>
191: */
192: public void put(String key, double value);
193:
194: /**
195: * Convenience API. Converts the float <code>value</code> to a string and
196: * adds the pair <code>key/value</code> to this dialog settings.
197: *
198: * @param key
199: * the key.
200: * @param value
201: * the value to be associated with the <code>key</code>
202: */
203: public void put(String key, float value);
204:
205: /**
206: * Convenience API. Converts the int <code>value</code> to a string and
207: * adds the pair <code>key/value</code> to this dialog settings.
208: *
209: * @param key
210: * the key.
211: * @param value
212: * the value to be associated with the <code>key</code>
213: */
214: public void put(String key, int value);
215:
216: /**
217: * Convenience API. Converts the long <code>value</code> to a string and
218: * adds the pair <code>key/value</code> to this dialog settings.
219: *
220: * @param key
221: * the key.
222: * @param value
223: * the value to be associated with the <code>key</code>
224: */
225: public void put(String key, long value);
226:
227: /**
228: * Adds the pair <code>key/value</code> to this dialog settings.
229: *
230: * @param key
231: * the key.
232: * @param value
233: * the value to be associated with the <code>key</code>
234: */
235: public void put(String key, String value);
236:
237: /**
238: * Convenience API. Converts the boolean <code>value</code> to a string
239: * and adds the pair <code>key/value</code> to this dialog settings.
240: *
241: * @param key
242: * the key.
243: * @param value
244: * the value to be associated with the <code>key</code>
245: */
246: public void put(String key, boolean value);
247:
248: /**
249: * Save a dialog settings to a stream
250: *
251: * @param writer
252: * a Writer specifying the stream the settings are written in.
253: * @throws IOException
254: */
255: public void save(Writer writer) throws IOException;
256:
257: /**
258: * Save a dialog settings to a file.
259: *
260: * @param fileName
261: * the name of the file the settings are written in.
262: * @throws IOException
263: */
264: public void save(String fileName) throws IOException;
265: }
|