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    }