001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>PortletPreferences</CODE> interface allows the portlet to store
009: * configuration data. It is not the
010: * purpose of this interface to replace general purpose databases.
011: * <p>
012: * There are two different types of preferences:
013: * <ul>
014: * <li>modifiable preferences - these preferences can be changed by the
015: * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
016: * Per default every preference is modifiable.
017: * <li>read-only preferences - these preferences cannot be changed by the
018: * portlet in any standard portlet mode, but may be changed by administrative modes.
019: * Preferences are read-only, if the are defined in the
020: * deployment descriptor with <code>read-only</code> set to <code>true</code>,
021: * or if the portlet container restricts write access.
022: * </ul>
023: * <p>
024: * Changes are persisted when the <code>store</code> method is called. The <code>store</code> method
025: * can only be invoked within the scope of a <code>processAction</code> call.
026: * Changes that are not persisted are discarded when the
027: * <code>processAction</code> or <code>render</code> method ends.
028: */
029: public interface PortletPreferences {
030:
031: /**
032: * Returns true, if the value of this key cannot be modified by the user.
033: * <p>
034: * Modifiable preferences can be changed by the
035: * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
036: * Per default every preference is modifiable.
037: * <p>
038: * Read-only preferences cannot be changed by the
039: * portlet in any standard portlet mode, but inside of custom modes
040: * it may be allowed changing them.
041: * Preferences are read-only, if they are defined in the
042: * deployment descriptor with <code>read-only</code> set to <code>true</code>,
043: * or if the portlet container restricts write access.
044: *
045: * @return false, if the value of this key can be changed, or
046: * if the key is not known
047: *
048: * @exception java.lang.IllegalArgumentException
049: * if <code>key</code> is <code>null</code>.
050: */
051: public boolean isReadOnly(String key);
052:
053: /**
054: * Returns the first String value associated with the specified key of this preference.
055: * If there is one or more preference values associated with the given key
056: * it returns the first associated value.
057: * If there are no preference values associated with the given key, or the
058: * backing preference database is unavailable, it returns the given
059: * default value.
060: *
061: * @param key key for which the associated value is to be returned
062: * @param def the value to be returned in the event that there is no
063: * value available associated with this <code>key</code>.
064: *
065: * @return the value associated with <code>key</code>, or <code>def</code>
066: * if no value is associated with <code>key</code>, or the backing
067: * store is inaccessible.
068: *
069: * @exception java.lang.IllegalArgumentException
070: * if <code>key</code> is <code>null</code>. (A
071: * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
072: *
073: * @see #getValues(String, String[])
074: */
075: public String getValue(String key, String def);
076:
077: /**
078: * Returns the String array value associated with the specified key in this preference.
079: *
080: * <p>Returns the specified default if there is no value
081: * associated with the key, or if the backing store is inaccessible.
082: *
083: * <p>If the implementation supports <i>stored defaults</i> and such a
084: * default exists and is accessible, it is used in favor of the
085: * specified default.
086: *
087: *
088: * @param key key for which associated value is to be returned.
089: * @param def the value to be returned in the event that this
090: * preference node has no value associated with <code>key</code>
091: * or the associated value cannot be interpreted as a String array,
092: * or the backing store is inaccessible.
093: *
094: * @return the String array value associated with
095: * <code>key</code>, or <code>def</code> if the
096: * associated value does not exist.
097: *
098: * @exception java.lang.IllegalArgumentException if <code>key</code> is <code>null</code>. (A
099: * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
100: *
101: * @see #getValue(String,String)
102: */
103:
104: public String[] getValues(String key, String[] def);
105:
106: /**
107: * Associates the specified String value with the specified key in this
108: * preference.
109: * <p>
110: * The key cannot be <code>null</code>, but <code>null</code> values
111: * for the value parameter are allowed.
112: *
113: * @param key key with which the specified value is to be associated.
114: * @param value value to be associated with the specified key.
115: *
116: * @exception ReadOnlyException
117: * if this preference cannot be modified for this request
118: * @exception java.lang.IllegalArgumentException if key is <code>null</code>,
119: * or <code>key.length()</code>
120: * or <code>value.length</code> are to long. The maximum length
121: * for key and value are implementation specific.
122: *
123: * @see #setValues(String, String[])
124: */
125: public void setValue(String key, String value)
126: throws ReadOnlyException;
127:
128: /**
129: * Associates the specified String array value with the specified key in this
130: * preference.
131: * <p>
132: * The key cannot be <code>null</code>, but <code>null</code> values
133: * in the values parameter are allowed.
134: *
135: * @param key key with which the value is to be associated
136: * @param values values to be associated with key
137: *
138: * @exception java.lang.IllegalArgumentException if key is <code>null</code>, or
139: * <code>key.length()</code>
140: * is to long or <code>value.size</code> is to large. The maximum
141: * length for key and maximum size for value are implementation specific.
142: * @exception ReadOnlyException
143: * if this preference cannot be modified for this request
144: *
145: * @see #setValue(String,String)
146: */
147:
148: public void setValues(String key, String[] values)
149: throws ReadOnlyException;
150:
151: /**
152: * Returns all of the keys that have an associated value,
153: * or an empty <code>Enumeration</code> if no keys are
154: * available.
155: *
156: * @return an Enumeration of the keys that have an associated value,
157: * or an empty <code>Enumeration</code> if no keys are
158: * available.
159: */
160: public java.util.Enumeration getNames();
161:
162: /**
163: * Returns a <code>Map</code> of the preferences.
164: * <p>
165: * The values in the returned <code>Map</code> are from type
166: * String array (<code>String[]</code>).
167: * <p>
168: * If no preferences exist this method returns an empty <code>Map</code>.
169: *
170: * @return an immutable <code>Map</code> containing preference names as
171: * keys and preference values as map values, or an empty <code>Map</code>
172: * if no preference exist. The keys in the preference
173: * map are of type String. The values in the preference map are of type
174: * String array (<code>String[]</code>).
175: */
176:
177: public java.util.Map getMap();
178:
179: /**
180: * Resets or removes the value associated with the specified key.
181: * <p>
182: * If this implementation supports stored defaults, and there is such
183: * a default for the specified preference, the given key will be
184: * reset to the stored default.
185: * <p>
186: * If there is no default available the key will be removed.
187: *
188: * @param key to reset
189: *
190: * @exception java.lang.IllegalArgumentException if key is <code>null</code>.
191: * @exception ReadOnlyException
192: * if this preference cannot be modified for this request
193: */
194:
195: public void reset(String key) throws ReadOnlyException;
196:
197: /**
198: * Commits all changes made to the preferences via the
199: * <code>set</code> methods in the persistent store.
200: * <P>
201: * If this call returns succesfull, all changes are made
202: * persistent. If this call fails, no changes are made
203: * in the persistent store. This call is an atomic operation
204: * regardless of how many preference attributes have been modified.
205: * <P>
206: * All changes made to preferences not followed by a call
207: * to the <code>store</code> method are discarded when the
208: * portlet finishes the <code>processAction</code> method.
209: * <P>
210: * If a validator is defined for this preferences in the
211: * deployment descriptor, this validator is called before
212: * the actual store is performed to check wether the given
213: * preferences are vaild. If this check fails a
214: * <code>ValidatorException</code> is thrown.
215: *
216: * @exception java.io.IOException
217: * if changes cannot be written into
218: * the backend store
219: * @exception ValidatorException
220: * if the validation performed by the
221: * associated validator fails
222: * @exception java.lang.IllegalStateException
223: * if this method is called inside a render call
224: *
225: * @see PreferencesValidator
226: */
227:
228: public void store() throws java.io.IOException, ValidatorException;
229:
230: }
|