Eclipse
Eclipse
IDEA
IntelliJ
NetBeans
NetBeans
XpoLog
XpoLog
javax.portlet
Interface PortletPreferences
Tab mode
public interface PortletPreferences
The 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 to true, 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.

SinceNot specified.
Version$Revision:
Author<a href="mailto:julien@jboss.org">Julien Viet</a>
Wiki javadoc Use textile entry format.
Add your comments here.
Method Summary
Map getMap()
Returns a Map of the preferences.
Enumeration getNames()
Returns all of the keys that have an associated value, or an empty Enumeration if no keys are available.
String getValue( String key, String def )
Returns the first String value associated with the specified key of this preference.
String[] getValues( String key, String [] def )
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 reset( String key )
Resets or removes the value associated with the specified key.
void setValue( String key, String value )
Associates the specified String value with the specified key in this preference.
void setValues( String key, String [] values )
Associates the specified String array value with the specified key in this preference.
void store()
Commits all changes made to the preferences via the set methods in the persistent store.
Method Detail
getMap
public Map getMap ( )
Returns a Map 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.

Wiki javadoc Use textile entry format.
Add your comments here.
getNames
public Enumeration getNames ( )
Returns all of the keys that have an associated value, or an empty Enumeration if no keys are available.
Wiki javadoc Use textile entry format.
Add your comments here.
getValue
public String getValue ( String key, String def )
throws
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
TypeNameDescription
String key key for which the associated value is to be returned
String def the value to be returned in the event that there is no value available associated with this key.
Exceptions
IllegalArgumentException if key is null. (A null value for def is permitted.)
See also
Wiki javadoc Use textile entry format.
Add your comments here.
getValues
public String[] getValues ( String key, String [] def )
throws
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
TypeNameDescription
String key key for which associated value is to be returned.
String [] def the value to be returned in the event that this preference node has no value associated with key or the associated value cannot be interpreted as a String array, or the backing store is inaccessible.
Exceptions
IllegalArgumentException if key is null. (A null value for def is permitted.)
See also
Wiki javadoc Use textile entry format.
Add your comments here.
isReadOnly
public boolean isReadOnly ( String key )
throws
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 to true, or if the portlet container restricts write access.

Parameters
TypeNameDescription
String key No description provided.
Exceptions
IllegalArgumentException if key is null.
Wiki javadoc Use textile entry format.
Add your comments here.
reset
public void reset ( String key )
throws
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
TypeNameDescription
String key to reset
Returns void No description provided.
Exceptions
IllegalArgumentException if key is null.
ReadOnlyException if this preference cannot be modified for this request
Wiki javadoc Use textile entry format.
Add your comments here.
setValue
public void setValue ( String key, String value )
throws
Associates the specified String value with the specified key in this preference.

The key cannot be null, but null values for the value parameter are allowed.

Parameters
TypeNameDescription
String key key with which the specified value is to be associated.
String value value to be associated with the specified key.
Returns void No description provided.
Exceptions
IllegalArgumentException if key is null, or key.length() or value.length are to long. The maximum length for key and value are implementation specific.
ReadOnlyException if this preference cannot be modified for this request
See also
Wiki javadoc Use textile entry format.
Add your comments here.
setValues
public void setValues ( String key, String [] values )
throws
Associates the specified String array value with the specified key in this preference.

The key cannot be null, but null values in the values parameter are allowed.

Parameters
TypeNameDescription
String key key with which the value is to be associated
String [] values values to be associated with key
Returns void No description provided.
Exceptions
IllegalArgumentException if key is null, or key.length() is to long or value.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
Wiki javadoc Use textile entry format.
Add your comments here.
store
public void store ( )
throws
Commits all changes made to the preferences via the set 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 the processAction 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.

Returns void No description provided.
Exceptions
IOException if changes cannot be written into the backend store
ValidatorException if the validation performed by the associated validator fails
See also
Wiki javadoc Use textile entry format.
Add your comments here.