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 }