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