IDialogSettings


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.dialogs;
12  
13  import java.io.IOException  ;
14  import java.io.Reader  ;
15  import java.io.Writer  ;
16  
17  /**
18   * An interface to a storage mechanism for making dialog settings persistent.
19   * The store manages a collection of key/value pairs. The keys must be strings
20   * and the values can be either, strings or array of strings. Convenience API to
21   * convert primitive types to strings is provided.
22   */
23  public interface IDialogSettings {
24      /**
25       * Create a new section in the receiver and return it.
26       * 
27       * @param name
28       *            the name of the new section
29       * @return the new section
30       */
31      public IDialogSettings addNewSection(String   name);
32  
33      /**
34       * Add a section in the receiver.
35       * 
36       * @param section
37       *            the section to be added
38       */
39      public void addSection(IDialogSettings section);
40  
41      /**
42       * Returns the value of the given key in this dialog settings.
43       * 
44       * @param key
45       *            the key
46       * @return the value, or <code>null</code> if none
47       */
48      public String   get(String   key);
49  
50      /**
51       * Returns the value, an array of strings, of the given key in this dialog
52       * settings.
53       * 
54       * @param key
55       *            the key
56       * @return the array of string, or <code>null</code> if none
57       */
58      public String  [] getArray(String   key);
59  
60      /**
61       * Convenience API. Convert the value of the given key in this dialog
62       * settings to a boolean and return it.
63       * 
64       * @param key
65       *            the key
66       * @return the boolean value, or <code>false</code> if none
67       */
68      public boolean getBoolean(String   key);
69  
70      /**
71       * Convenience API. Convert the value of the given key in this dialog
72       * settings to a double and return it.
73       * 
74       * @param key
75       *            the key
76       * @return the value coverted to double, or throws
77       *         <code>NumberFormatException</code> if none
78       * 
79       * @exception NumberFormatException
80       *                if the string value does not contain a parsable number.
81       * @see java.lang.Double#valueOf(java.lang.String)
82       */
83      public double getDouble(String   key) throws NumberFormatException  ;
84  
85      /**
86       * Convenience API. Convert the value of the given key in this dialog
87       * settings to a float and return it.
88       * 
89       * @param key
90       *            the key
91       * @return the value coverted to float, or throws
92       *         <code>NumberFormatException</code> if none
93       * 
94       * @exception NumberFormatException
95       *                if the string value does not contain a parsable number.
96       * @see java.lang.Float#valueOf(java.lang.String)
97       */
98      public float getFloat(String   key) throws NumberFormatException  ;
99  
100     /**
101      * Convenience API. Convert the value of the given key in this dialog
102      * settings to a int and return it.
103      * 
104      * @param key
105      *            the key
106      * @return the value coverted to int, or throws
107      *         <code>NumberFormatException</code> if none
108      * 
109      * @exception NumberFormatException
110      *                if the string value does not contain a parsable number.
111      * @see java.lang.Integer#valueOf(java.lang.String)
112      */
113     public int getInt(String   key) throws NumberFormatException  ;
114 
115     /**
116      * Convenience API. Convert the value of the given key in this dialog
117      * settings to a long and return it.
118      * 
119      * @param key
120      *            the key
121      * @return the value coverted to long, or throws
122      *         <code>NumberFormatException</code> if none
123      * 
124      * @exception NumberFormatException
125      *                if the string value does not contain a parsable number.
126      * @see java.lang.Long#valueOf(java.lang.String)
127      */
128     public long getLong(String   key) throws NumberFormatException  ;
129 
130     /**
131      * Returns the IDialogSettings name.
132      * 
133      * @return the name
134      */
135     public String   getName();
136 
137     /**
138      * Returns the section with the given name in this dialog settings.
139      * 
140      * @param sectionName
141      *            the key
142      * @return IDialogSettings (the section), or <code>null</code> if none
143      */
144     public IDialogSettings getSection(String   sectionName);
145 
146     /**
147      * Returns all the sections in this dialog settings.
148      * 
149      * @return the section, or <code>null</code> if none
150      */
151     public IDialogSettings[] getSections();
152 
153     /**
154      * Load a dialog settings from a stream and fill the receiver with its
155      * content.
156      * 
157      * @param reader
158      *            a Reader specifying the stream where the settings are read
159      *            from.
160      * @throws IOException
161      */
162     public void load(Reader   reader) throws IOException  ;
163 
164     /**
165      * Load a dialog settings from a file and fill the receiver with its
166      * content.
167      * 
168      * @param fileName
169      *            the name of the file the settings are read from.
170      * @throws IOException
171      */
172     public void load(String   fileName) throws IOException  ;
173 
174     /**
175      * Adds the pair <code>key/value</code> to this dialog settings.
176      * 
177      * @param key
178      *            the key.
179      * @param value
180      *            the value to be associated with the <code>key</code>
181      */
182     public void put(String   key, String  [] value);
183 
184     /**
185      * Convenience API. Converts the double <code>value</code> to a string and
186      * adds the pair <code>key/value</code> to this dialog settings.
187      * 
188      * @param key
189      *            the key.
190      * @param value
191      *            the value to be associated with the <code>key</code>
192      */
193     public void put(String   key, double value);
194 
195     /**
196      * Convenience API. Converts the float <code>value</code> to a string and
197      * adds the pair <code>key/value</code> to this dialog settings.
198      * 
199      * @param key
200      *            the key.
201      * @param value
202      *            the value to be associated with the <code>key</code>
203      */
204     public void put(String   key, float value);
205 
206     /**
207      * Convenience API. Converts the int <code>value</code> to a string and
208      * adds the pair <code>key/value</code> to this dialog settings.
209      * 
210      * @param key
211      *            the key.
212      * @param value
213      *            the value to be associated with the <code>key</code>
214      */
215     public void put(String   key, int value);
216 
217     /**
218      * Convenience API. Converts the long <code>value</code> to a string and
219      * adds the pair <code>key/value</code> to this dialog settings.
220      * 
221      * @param key
222      *            the key.
223      * @param value
224      *            the value to be associated with the <code>key</code>
225      */
226     public void put(String   key, long value);
227 
228     /**
229      * Adds the pair <code>key/value</code> to this dialog settings.
230      * 
231      * @param key
232      *            the key.
233      * @param value
234      *            the value to be associated with the <code>key</code>
235      */
236     public void put(String   key, String   value);
237 
238     /**
239      * Convenience API. Converts the boolean <code>value</code> to a string
240      * and adds the pair <code>key/value</code> to this dialog settings.
241      * 
242      * @param key
243      *            the key.
244      * @param value
245      *            the value to be associated with the <code>key</code>
246      */
247     public void put(String   key, boolean value);
248 
249     /**
250      * Save a dialog settings to a stream
251      * 
252      * @param writer
253      *            a Writer specifying the stream the settings are written in.
254      * @throws IOException
255      */
256     public void save(Writer   writer) throws IOException  ;
257 
258     /**
259      * Save a dialog settings to a file.
260      * 
261      * @param fileName
262      *            the name of the file the settings are written in.
263      * @throws IOException
264      */
265     public void save(String   fileName) throws IOException  ;
266 }
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags