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 *
051 * @return the first value associated with this preference, or <code>null</code>
052 * if there isn't an associated value or the backing
053 * store is inaccessible.
054 *
055 *
056 * @see #getValues()
057 */
058 public String getValue();
059
060 /**
061 * Returns a <code>List</code> of values associated with this preference.
062 *
063 * <p>Returns the <CODE>null</CODE> if there aren't any values,
064 * or if the backing store is inaccessible.
065 *
066 * <p>If the implementation supports <i>stored defaults</i> and such a
067 * default exists and is accessible, they are returned in a situation where null
068 * otherwise would have been returned.
069 *
070 *
071 *
072 * @return the List associated with
073 * this preference, or <code>null</code> if the
074 * associated value does not exist.
075 *
076 * @see #getValue()
077 */
078 public List getValues();
079
080 /**
081 * Returns true, if the value of this preference cannot be modified by the user.
082 * <p>
083 * Modifiable preferences can be changed by the
084 * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>).
085 * Per default every preference is modifiable.
086 * <p>
087 * Read-only preferences cannot be changed by the
088 * portlet in any standard portlet mode, but inside of custom modes
089 * it may be allowed changing them.
090 * Preferences are read-only, if they are defined in the
091 * deployment descriptor with <code>read-only</code> set to <code>true</code>,
092 * or if the portlet container restricts write access.
093 *
094 * @return false, if the value of this preference can be changed
095 *
096 */
097 public boolean isReadOnly();
098
099 /**
100 * Resets or removes the value(s) of this preference.
101 * <p>
102 * If this implementation supports stored defaults, and there is such
103 * a default for the specified preference, the preference will be
104 * reset to the stored default.
105 * <p>
106 * If there is no default available the preference will be removed from
107 * the underyling system.
108 *
109 * @exception ReadOnlyException
110 * if this preference cannot be modified for this request
111 */
112 public void reset() throws ReadOnlyException;
113
114
115 /**
116 * Associates the specified String value with this
117 * preference.
118 * <p>
119 * <code>null</code> values
120 * for the value parameter are allowed.
121 *
122 * @param value value to be associated with the specified key.
123 *
124 * @exception ReadOnlyException
125 * if this preference cannot be modified for this request
126 *
127 * @see #setValues(String[])
128 */
129 public void setValue(String value) throws ReadOnlyException;
130
131 /**
132 * Associates the specified String array value with this
133 * preference.
134 * <p>
135 * <code>null</code> values
136 * in the values parameter are allowed.
137 *
138 * @param values values to be associated with key
139 *
140 * @exception ReadOnlyException
141 * if this preference cannot be modified for this request
142 *
143 * @see #setValue(String)
144 */
145 public void setValues(String[] values) throws ReadOnlyException;
146 }