1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package javax.portlet;
22
23
24
25 /***
26 * The <CODE>PortletPreferences</CODE> interface allows the portlet to store
27 * configuration data. It is not the
28 * purpose of this interface to replace general purpose databases.
29 * <p>
30 * There are two different types of preferences:
31 * <ul>
32 * <li>modifiable preferences - these preferences can be changed by the
33 * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
34 * Per default every preference is modifiable.
35 * <li>read-only preferences - these preferences cannot be changed by the
36 * portlet in any standard portlet mode, but may be changed by administrative modes.
37 * Preferences are read-only, if the are defined in the
38 * deployment descriptor with <code>read-only</code> set to <code>true</code>,
39 * or if the portlet container restricts write access.
40 * </ul>
41 * <p>
42 * Changes are persisted when the <code>store</code> method is called. The <code>store</code> method
43 * can only be invoked within the scope of a <code>processAction</code> call.
44 * Changes that are not persisted are discarded when the
45 * <code>processAction</code> or <code>render</code> method ends.
46 */
47 public interface PortletPreferences
48 {
49
50
51
52
53 /***
54 * Returns true, if the value of this key cannot be modified by the user.
55 * <p>
56 * Modifiable preferences can be changed by the
57 * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
58 * Per default every preference is modifiable.
59 * <p>
60 * Read-only preferences cannot be changed by the
61 * portlet in any standard portlet mode, but inside of custom modes
62 * it may be allowed changing them.
63 * Preferences are read-only, if they are defined in the
64 * deployment descriptor with <code>read-only</code> set to <code>true</code>,
65 * or if the portlet container restricts write access.
66 *
67 * @return false, if the value of this key can be changed, or
68 * if the key is not known
69 *
70 * @exception java.lang.IllegalArgumentException
71 * if <code>key</code> is <code>null</code>.
72 */
73 public boolean isReadOnly(String key);
74
75
76
77 /***
78 * Returns the first String value associated with the specified key of this preference.
79 * If there is one or more preference values associated with the given key
80 * it returns the first associated value.
81 * If there are no preference values associated with the given key, or the
82 * backing preference database is unavailable, it returns the given
83 * default value.
84 *
85 * @param key key for which the associated value is to be returned
86 * @param def the value to be returned in the event that there is no
87 * value available associated with this <code>key</code>.
88 *
89 * @return the value associated with <code>key</code>, or <code>def</code>
90 * if no value is associated with <code>key</code>, or the backing
91 * store is inaccessible.
92 *
93 * @exception java.lang.IllegalArgumentException
94 * if <code>key</code> is <code>null</code>. (A
95 * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
96 *
97 * @see #getValues(String, String[])
98 */
99 public String getValue(String key, String def);
100
101
102 /***
103 * Returns the String array value associated with the specified key in this preference.
104 *
105 * <p>Returns the specified default if there is no value
106 * associated with the key, or if the backing store is inaccessible.
107 *
108 * <p>If the implementation supports <i>stored defaults</i> and such a
109 * default exists and is accessible, it is used in favor of the
110 * specified default.
111 *
112 *
113 * @param key key for which associated value is to be returned.
114 * @param def the value to be returned in the event that this
115 * preference node has no value associated with <code>key</code>
116 * or the associated value cannot be interpreted as a String array,
117 * or the backing store is inaccessible.
118 *
119 * @return the String array value associated with
120 * <code>key</code>, or <code>def</code> if the
121 * associated value does not exist.
122 *
123 * @exception java.lang.IllegalArgumentException if <code>key</code> is <code>null</code>. (A
124 * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
125 *
126 * @see #getValue(String,String)
127 */
128
129 public String[] getValues(String key, String[] def);
130
131
132
133 /***
134 * Associates the specified String value with the specified key in this
135 * preference.
136 * <p>
137 * The key cannot be <code>null</code>, but <code>null</code> values
138 * for the value parameter are allowed.
139 *
140 * @param key key with which the specified value is to be associated.
141 * @param value value to be associated with the specified key.
142 *
143 * @exception ReadOnlyException
144 * if this preference cannot be modified for this request
145 * @exception java.lang.IllegalArgumentException if key is <code>null</code>,
146 * or <code>key.length()</code>
147 * or <code>value.length</code> are to long. The maximum length
148 * for key and value are implementation specific.
149 *
150 * @see #setValues(String, String[])
151 */
152 public void setValue(String key, String value) throws ReadOnlyException;
153
154
155
156
157 /***
158 * Associates the specified String array value with the specified key in this
159 * preference.
160 * <p>
161 * The key cannot be <code>null</code>, but <code>null</code> values
162 * in the values parameter are allowed.
163 *
164 * @param key key with which the value is to be associated
165 * @param values values to be associated with key
166 *
167 * @exception java.lang.IllegalArgumentException if key is <code>null</code>, or
168 * <code>key.length()</code>
169 * is to long or <code>value.size</code> is to large. The maximum
170 * length for key and maximum size for value are implementation specific.
171 * @exception ReadOnlyException
172 * if this preference cannot be modified for this request
173 *
174 * @see #setValue(String,String)
175 */
176
177 public void setValues(String key, String[] values) throws ReadOnlyException;
178
179
180 /***
181 * Returns all of the keys that have an associated value,
182 * or an empty <code>Enumeration</code> if no keys are
183 * available.
184 *
185 * @return an Enumeration of the keys that have an associated value,
186 * or an empty <code>Enumeration</code> if no keys are
187 * available.
188 */
189 public java.util.Enumeration getNames();
190
191 /***
192 * Returns a <code>Map</code> of the preferences.
193 * <p>
194 * The values in the returned <code>Map</code> are from type
195 * String array (<code>String[]</code>).
196 * <p>
197 * If no preferences exist this method returns an empty <code>Map</code>.
198 *
199 * @return an immutable <code>Map</code> containing preference names as
200 * keys and preference values as map values, or an empty <code>Map</code>
201 * if no preference exist. The keys in the preference
202 * map are of type String. The values in the preference map are of type
203 * String array (<code>String[]</code>).
204 */
205
206 public java.util.Map getMap();
207
208
209 /***
210 * Resets or removes the value associated with the specified key.
211 * <p>
212 * If this implementation supports stored defaults, and there is such
213 * a default for the specified preference, the given key will be
214 * reset to the stored default.
215 * <p>
216 * If there is no default available the key will be removed.
217 *
218 * @param key to reset
219 *
220 * @exception java.lang.IllegalArgumentException if key is <code>null</code>.
221 * @exception ReadOnlyException
222 * if this preference cannot be modified for this request
223 */
224
225 public void reset(String key) throws ReadOnlyException;
226
227
228 /***
229 * Commits all changes made to the preferences via the
230 * <code>set</code> methods in the persistent store.
231 * <P>
232 * If this call returns succesfull, all changes are made
233 * persistent. If this call fails, no changes are made
234 * in the persistent store. This call is an atomic operation
235 * regardless of how many preference attributes have been modified.
236 * <P>
237 * All changes made to preferences not followed by a call
238 * to the <code>store</code> method are discarded when the
239 * portlet finishes the <code>processAction</code> method.
240 * <P>
241 * If a validator is defined for this preferences in the
242 * deployment descriptor, this validator is called before
243 * the actual store is performed to check wether the given
244 * preferences are vaild. If this check fails a
245 * <code>ValidatorException</code> is thrown.
246 *
247 * @exception java.io.IOException
248 * if changes cannot be written into
249 * the backend store
250 * @exception ValidatorException
251 * if the validation performed by the
252 * associated validator fails
253 * @exception java.lang.IllegalStateException
254 * if this method is called inside a render call
255 *
256 * @see PreferencesValidator
257 */
258
259 public void store() throws java.io.IOException, ValidatorException;
260
261
262 }