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: * @throws java.lang.IllegalArgumentException
048: * if <code>key</code> is <code>null</code>.
049: */
050: public boolean isReadOnly(String key);
051:
052: /**
053: * Returns the first String value associated with the specified key of this preference.
054: * If there is one or more preference values associated with the given key
055: * it returns the first associated value.
056: * If there are no preference values associated with the given key, or the
057: * backing preference database is unavailable, it returns the given
058: * default value.
059: *
060: * @param key key for which the associated value is to be returned
061: * @param def the value to be returned in the event that there is no
062: * value available associated with this <code>key</code>.
063: * @return the value associated with <code>key</code>, or <code>def</code>
064: * if no value is associated with <code>key</code>, or the backing
065: * store is inaccessible.
066: * @throws java.lang.IllegalArgumentException
067: * if <code>key</code> is <code>null</code>. (A
068: * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
069: * @see #getValues(String, String[])
070: */
071: public String getValue(String key, String def);
072:
073: /**
074: * Returns the String array value associated with the specified key in this preference.
075: * <p/>
076: * <p>Returns the specified default if there is no value
077: * associated with the key, or if the backing store is inaccessible.
078: * <p/>
079: * <p>If the implementation supports <i>stored defaults</i> and such a
080: * default exists and is accessible, it is used in favor of the
081: * specified default.
082: *
083: * @param key key for which associated value is to be returned.
084: * @param def the value to be returned in the event that this
085: * preference node has no value associated with <code>key</code>
086: * or the associated value cannot be interpreted as a String array,
087: * or the backing store is inaccessible.
088: * @return the String array value associated with
089: * <code>key</code>, or <code>def</code> if the
090: * associated value does not exist.
091: * @throws java.lang.IllegalArgumentException
092: * if <code>key</code> is <code>null</code>. (A
093: * <code>null</code> value for <code>def</code> <i>is</i> permitted.)
094: * @see #getValue(String,String)
095: */
096:
097: public String[] getValues(String key, String[] def);
098:
099: /**
100: * Associates the specified String value with the specified key in this
101: * preference.
102: * <p/>
103: * The key cannot be <code>null</code>, but <code>null</code> values
104: * for the value parameter are allowed.
105: *
106: * @param key key with which the specified value is to be associated.
107: * @param value value to be associated with the specified key.
108: * @throws ReadOnlyException if this preference cannot be modified for this request
109: * @throws java.lang.IllegalArgumentException
110: * if key is <code>null</code>,
111: * or <code>key.length()</code>
112: * or <code>value.length</code> are to long. The maximum length
113: * for key and value are implementation specific.
114: * @see #setValues(String, String[])
115: */
116: public void setValue(String key, String value)
117: throws ReadOnlyException;
118:
119: /**
120: * Associates the specified String array value with the specified key in this
121: * preference.
122: * <p/>
123: * The key cannot be <code>null</code>, but <code>null</code> values
124: * in the values parameter are allowed.
125: *
126: * @param key key with which the value is to be associated
127: * @param values values to be associated with key
128: * @throws java.lang.IllegalArgumentException
129: * if key is <code>null</code>, or
130: * <code>key.length()</code>
131: * is to long or <code>value.size</code> is to large. The maximum
132: * length for key and maximum size for value are implementation specific.
133: * @throws ReadOnlyException if this preference cannot be modified for this request
134: * @see #setValue(String,String)
135: */
136:
137: public void setValues(String key, String[] values)
138: throws ReadOnlyException;
139:
140: /**
141: * Returns all of the keys that have an associated value,
142: * or an empty <code>Enumeration</code> if no keys are
143: * available.
144: *
145: * @return an Enumeration of the keys that have an associated value,
146: * or an empty <code>Enumeration</code> if no keys are
147: * available.
148: */
149: public java.util.Enumeration getNames();
150:
151: /**
152: * Returns a <code>Map</code> of the preferences.
153: * <p/>
154: * The values in the returned <code>Map</code> are from type
155: * String array (<code>String[]</code>).
156: * <p/>
157: * If no preferences exist this method returns an empty <code>Map</code>.
158: *
159: * @return an immutable <code>Map</code> containing preference names as
160: * keys and preference values as map values, or an empty <code>Map</code>
161: * if no preference exist. The keys in the preference
162: * map are of type String. The values in the preference map are of type
163: * String array (<code>String[]</code>).
164: */
165:
166: public java.util.Map getMap();
167:
168: /**
169: * Resets or removes the value associated with the specified key.
170: * <p/>
171: * If this implementation supports stored defaults, and there is such
172: * a default for the specified preference, the given key will be
173: * reset to the stored default.
174: * <p/>
175: * If there is no default available the key will be removed.
176: *
177: * @param key to reset
178: * @throws java.lang.IllegalArgumentException
179: * if key is <code>null</code>.
180: * @throws ReadOnlyException if this preference cannot be modified for this request
181: */
182:
183: public void reset(String key) throws ReadOnlyException;
184:
185: /**
186: * Commits all changes made to the preferences via the
187: * <code>set</code> methods in the persistent store.
188: * <P>
189: * If this call returns succesfull, all changes are made
190: * persistent. If this call fails, no changes are made
191: * in the persistent store. This call is an atomic operation
192: * regardless of how many preference attributes have been modified.
193: * <P>
194: * All changes made to preferences not followed by a call
195: * to the <code>store</code> method are discarded when the
196: * portlet finishes the <code>processAction</code> method.
197: * <P>
198: * If a validator is defined for this preferences in the
199: * deployment descriptor, this validator is called before
200: * the actual store is performed to check wether the given
201: * preferences are vaild. If this check fails a
202: * <code>ValidatorException</code> is thrown.
203: *
204: * @throws java.io.IOException if changes cannot be written into
205: * the backend store
206: * @throws ValidatorException if the validation performed by the
207: * associated validator fails
208: * @throws java.lang.IllegalStateException
209: * if this method is called inside a render call
210: * @see PreferencesValidator
211: */
212:
213: public void store() throws java.io.IOException, ValidatorException;
214:
215: }
|