View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
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 }