001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
003 * agreements. See the NOTICE file distributed with this work for additional information regarding
004 * copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the
005 * "License"); you may not use this file except in compliance with the License. You may obtain a
006 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable
007 * law or agreed to in writing, software distributed under the License is distributed on an "AS IS"
008 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
009 * for the specific language governing permissions and limitations under the License.
010 */
011 package javax.portlet.faces.preference;
012
013
014 import java.util.List;
015 import javax.portlet.ReadOnlyException;
016
017 /**
018 * The <CODE>Preference</CODE> interface allows one to access each
019 * <CODE>PortletPreferences</CODE> as a discrete object. This allows one to more
020 * easily access a preference via EL. Operations made on a <CODE>Preference</CODE>
021 * object are immediately reflected in the underlying <CODE>PortletPreferences</CODE>.
022 * As usual, changes aren't committed until <CODE>PortletPreferences.store</CODE>
023 * is called.
024 */
025 public interface Preference
026 {
027
028 /**
029 * Sets the name of this preference.
030 *
031 * @param name
032 * the new name for this preference.
033 */
034 public void setName(String name);
035
036 /**
037 * Returns the name of this preference.
038 *
039 * @return the name of this preference.
040 */
041 public String getName();
042
043 /**
044 * Returns the first String value associated with this preference.
045 * If there is one or more values associated with this preference
046 * it returns the first associated value.
047 * If there are no values associated with this preference, or the
048 * backing preference database is unavailable, it returns null.
049 *
050 * @return the first value associated with this preference, or <code>null</code>
051 * if there isn't an associated value or the backing
052 * store is inaccessible.
053 *
054 *
055 * @see #getValues()
056 */
057 public String getValue();
058
059 /**
060 * Returns a <code>List</code> of values associated with this preference.
061 *
062 * <p>Returns the <CODE>null</CODE> if there aren't any values,
063 * or if the backing store is inaccessible.
064 *
065 * <p>If the implementation supports <i>stored defaults</i> and such a
066 * default exists and is accessible, they are returned in a situation where null
067 * otherwise would have been returned.
068 *
069 *
070 *
071 * @return the List associated with
072 * this preference, or <code>null</code> if the
073 * associated value does not exist.
074 *
075 * @see #getValue()
076 */
077 public List getValues();
078
079 /**
080 * Returns true, if the value of this preference cannot be modified by the user.
081 * <p>
082 * Modifiable preferences can be changed by the
083 * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
084 * Per default every preference is modifiable.
085 * <p>
086 * Read-only preferences cannot be changed by the
087 * portlet in any standard portlet mode, but inside of custom modes
088 * it may be allowed changing them.
089 * Preferences are read-only, if they are defined in the
090 * deployment descriptor with <code>read-only</code> set to <code>true</code>,
091 * or if the portlet container restricts write access.
092 *
093 * @return false, if the value of this preference can be changed
094 *
095 */
096 public boolean isReadOnly();
097
098 /**
099 * Resets or removes the value(s) of this preference.
100 * <p>
101 * If this implementation supports stored defaults, and there is such
102 * a default for the specified preference, the preference will be
103 * reset to the stored default.
104 * <p>
105 * If there is no default available the preference will be removed from
106 * the underyling system.
107 *
108 * @exception ReadOnlyException
109 * if this preference cannot be modified for this request
110 */
111 public void reset() throws ReadOnlyException;
112
113
114 /**
115 * Associates the specified String value with this
116 * preference.
117 * <p>
118 * <code>null</code> values
119 * for the value parameter are allowed.
120 *
121 * @param value value to be associated with the specified key.
122 *
123 * @exception ReadOnlyException
124 * if this preference cannot be modified for this request
125 *
126 * @see #setValues(String[])
127 */
128 public void setValue(String value) throws ReadOnlyException;
129
130 /**
131 * Associates the specified String array value with this
132 * preference.
133 * <p>
134 * <code>null</code> values
135 * in the values parameter are allowed.
136 *
137 * @param values values to be associated with key
138 *
139 * @exception ReadOnlyException
140 * if this preference cannot be modified for this request
141 *
142 * @see #setValue(String)
143 */
144 public void setValues(String[] values) throws ReadOnlyException;
145 }