Interface PortletPreferences
PortletPreferences
interface allows the portlet to store
configuration data. It is not the
purpose of this interface to replace general purpose databases.
There are two different types of preferences:
- modifiable preferences - these preferences can be changed by the
portlet in any standard portlet mode (
EDIT, HELP, VIEW
). Per default every preference is modifiable. - read-only preferences - these preferences cannot be changed by the
portlet in any standard portlet mode, but may be changed by administrative modes.
Preferences are read-only, if the are defined in the
deployment descriptor with
read-only
set totrue
, or if the portlet container restricts write access.
Changes are persisted when the store
method is called. The store
method
can only be invoked within the scope of a processAction
call.
Changes that are not persisted are discarded when the
processAction
or render
method ends.
-
Method Summary
Modifier and TypeMethodDescriptiongetMap()
Returns aMap
of the preferences.getNames()
Returns all of the keys that have an associated value, or an emptyEnumeration
if no keys are available.Returns the first String value associated with the specified key of this preference.String[]
Returns the String array value associated with the specified key in this preference.boolean
isReadOnly
(String key) Returns true, if the value of this key cannot be modified by the user.void
Resets or removes the value associated with the specified key.void
Associates the specified String value with the specified key in this preference.void
Associates the specified String array value with the specified key in this preference.void
store()
Commits all changes made to the preferences via theset
methods in the persistent store.
-
Method Details
-
isReadOnly
Returns true, if the value of this key cannot be modified by the user.Modifiable preferences can be changed by the portlet in any standard portlet mode (
EDIT, HELP, VIEW
). Per default every preference is modifiable.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
read-only
set totrue
, or if the portlet container restricts write access.- Returns:
- false, if the value of this key can be changed, or if the key is not known
- Throws:
IllegalArgumentException
- ifkey
isnull
.
-
getValue
Returns the first String value associated with the specified key of this preference. If there is one or more preference values associated with the given key it returns the first associated value. If there are no preference values associated with the given key, or the backing preference database is unavailable, it returns the given default value.- Parameters:
key
- key for which the associated value is to be returneddef
- the value to be returned in the event that there is no value available associated with thiskey
.- Returns:
- the value associated with
key
, ordef
if no value is associated withkey
, or the backing store is inaccessible. - Throws:
IllegalArgumentException
- ifkey
isnull
. (Anull
value fordef
is permitted.)- See Also:
-
getValues
Returns the String array value associated with the specified key in this preference.Returns the specified default if there is no value associated with the key, or if the backing store is inaccessible.
If the implementation supports stored defaults and such a default exists and is accessible, it is used in favor of the specified default.
- Parameters:
key
- key for which associated value is to be returned.def
- the value to be returned in the event that this preference node has no value associated withkey
or the associated value cannot be interpreted as a String array, or the backing store is inaccessible.- Returns:
- the String array value associated with
key
, ordef
if the associated value does not exist. - Throws:
IllegalArgumentException
- ifkey
isnull
. (Anull
value fordef
is permitted.)- See Also:
-
setValue
Associates the specified String value with the specified key in this preference.The key cannot be
null
, butnull
values for the value parameter are allowed.- Parameters:
key
- key with which the specified value is to be associated.value
- value to be associated with the specified key.- Throws:
ReadOnlyException
- if this preference cannot be modified for this requestIllegalArgumentException
- if key isnull
, orkey.length()
orvalue.length
are to long. The maximum length for key and value are implementation specific.- See Also:
-
setValues
Associates the specified String array value with the specified key in this preference.The key cannot be
null
, butnull
values in the values parameter are allowed.- Parameters:
key
- key with which the value is to be associatedvalues
- values to be associated with key- Throws:
IllegalArgumentException
- if key isnull
, orkey.length()
is to long orvalue.size
is to large. The maximum length for key and maximum size for value are implementation specific.ReadOnlyException
- if this preference cannot be modified for this request- See Also:
-
getNames
Enumeration getNames()Returns all of the keys that have an associated value, or an emptyEnumeration
if no keys are available.- Returns:
- an Enumeration of the keys that have an associated value,
or an empty
Enumeration
if no keys are available.
-
getMap
Map getMap()Returns aMap
of the preferences.The values in the returned
Map
are from type String array (String[]
).If no preferences exist this method returns an empty
Map
.- Returns:
- an immutable
Map
containing preference names as keys and preference values as map values, or an emptyMap
if no preference exist. The keys in the preference map are of type String. The values in the preference map are of type String array (String[]
).
-
reset
Resets or removes the value associated with the specified key.If this implementation supports stored defaults, and there is such a default for the specified preference, the given key will be reset to the stored default.
If there is no default available the key will be removed.
- Parameters:
key
- to reset- Throws:
IllegalArgumentException
- if key isnull
.ReadOnlyException
- if this preference cannot be modified for this request
-
store
Commits all changes made to the preferences via theset
methods in the persistent store.If this call returns succesfull, all changes are made persistent. If this call fails, no changes are made in the persistent store. This call is an atomic operation regardless of how many preference attributes have been modified.
All changes made to preferences not followed by a call to the
store
method are discarded when the portlet finishes theprocessAction
method.If a validator is defined for this preferences in the deployment descriptor, this validator is called before the actual store is performed to check wether the given preferences are vaild. If this check fails a
ValidatorException
is thrown.- Throws:
IOException
- if changes cannot be written into the backend storeValidatorException
- if the validation performed by the associated validator failsIllegalStateException
- if this method is called inside a render call- See Also:
-