PortletPreferences


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