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 }