svn commit: r671927 - in /myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces: preference/ preference/Preference.java preferences/

[mf...@apache.org]

Author: mfreedman
Date: Thu Jun 26 08:47:12 2008
New Revision: 671927

URL: http://svn.apache.org/viewvc?rev=671927&view=rev
Log: (empty)

Added:
    myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/
    myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/Preference.java
Removed:
    myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preferences/

Added: myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/Preference.java
URL: http://svn.apache.org/viewvc/myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/Preference.java?rev=671927&view=auto
==============================================================================
--- myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/Preference.java (added)
+++ myfaces/portlet-bridge/core/trunk/api/src/main/java/javax/portlet/faces/preference/Preference.java Thu Jun 26 08:47:12 2008
@@ -0,0 +1,147 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
+ * agreements. See the NOTICE file distributed with this work for additional information regarding
+ * copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the License. You may obtain a
+ * copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable
+ * law or agreed to in writing, software distributed under the License is distributed on an "AS IS"
+ * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
+ * for the specific language governing permissions and limitations under the License.
+ */
+package javax.portlet.faces.preference;
+
+
+import java.util.List;
+import javax.portlet.ReadOnlyException;
+
+/**
+ * The <CODE>Preference</CODE> interface allows one to access each
+ * <CODE>PortletPreferences</CODE> as a discrete object.  This allows one to more
+ * easily access a preference via EL.  Operations made on a <CODE>Preference</CODE>
+ * object are immediately reflected in the underlying <CODE>PortletPreferences</CODE>.
+ * As usual, changes aren't committed until <CODE>PortletPreferences.store</CODE>
+ * is called.
+ */
+public interface Preference
+{
+
+  /**
+   * Sets the name of this preference.
+   *
+   * @param the new name for this preference.
+   */   
+  public void setName(String name);
+
+  /**
+   * Returns the name of this preference.
+   *
+   * @return the name of this preference.
+   */  
+  public String getName();
+
+  /**
+   * Returns the first String value associated with this preference.
+   * If there is one or more values associated with this preference 
+   * it returns the first associated value.
+   * If there are no values associated with this preference, or the 
+   * backing preference database is unavailable, it returns null.
+   *
+   * @param def the value to be returned in the event that there is no 
+   *            value available associated with this <code>key</code>.
+   *
+   * @return the first value associated with this preference, or <code>null</code>
+   *         if there isn't an associated value or the backing
+   *         store is inaccessible.
+   *
+   * 
+   * @see #getValues()
+   */  
+  public String getValue();
+  
+  /**
+   * Returns a <code>List</code> of values associated with this preference.
+   *
+   * <p>Returns the <CODE>null</CODE> if there aren't any values,
+   * or if the backing store is inaccessible.
+   *
+   * <p>If the implementation supports <i>stored defaults</i> and such a
+   * default exists and is accessible, they are returned in a situation where null
+   * otherwise would have been returned.
+   *
+   *
+   *
+   * @return the List associated with
+   *         this preference, or <code>null</code> if the
+   *         associated value does not exist.
+   *
+   * @see #getValue()
+   */
+  public List getValues();
+
+  /**
+   * Returns true, if the value of this preference cannot be modified by the user.
+   * <p>
+   * Modifiable preferences can be changed by the
+   * portlet in any standard portlet mode (<code>EDIT, HELP, VIEW</code>). 
+   * Per default every preference is modifiable.
+   * <p>
+   * Read-only preferences cannot be changed by the
+   * portlet in any standard portlet mode, but inside of custom modes
+   * it may be allowed changing them.
+   * Preferences are read-only, if they are defined in the 
+   * deployment descriptor with <code>read-only</code> set to <code>true</code>,
+   * or if the portlet container restricts write access.
+   *
+   * @return  false, if the value of this preference can be changed
+   *
+   */  
+  public boolean isReadOnly();
+
+  /**
+   * Resets or removes the value(s) of this preference.
+   * <p>
+   * If this implementation supports stored defaults, and there is such
+   * a default for the specified preference, the preference will be 
+   * reset to the stored default.
+   * <p>
+   * If there is no default available the preference will be removed from
+   * the underyling system.
+   *
+   * @exception  ReadOnlyException
+   *                 if this preference cannot be modified for this request
+   */  
+  public void reset() throws ReadOnlyException;
+
+
+  /**
+   * Associates the specified String value with this
+   * preference.
+   * <p>
+   * <code>null</code> values
+   * for the value parameter are allowed.
+   *
+   * @param value value to be associated with the specified key.
+   *
+   * @exception  ReadOnlyException
+   *                 if this preference cannot be modified for this request
+   *
+   * @see #setValues(String[])
+   */  
+  public void setValue(String value) throws ReadOnlyException;
+  
+  /**
+   * Associates the specified String array value with this
+   * preference.
+   * <p>
+   * <code>null</code> values
+   * in the values parameter are allowed.
+   *
+   * @param values values to be associated with key
+   *
+   * @exception  ReadOnlyException
+   *                 if this preference cannot be modified for this request
+   *
+   * @see #setValue(String)
+   */
+  public void setValues(String[] values) throws ReadOnlyException;
+}