Java Portlet API V3.0 3.0.1 · javax.portlet.PortletPreferences

Method Summary

Modifier and Type	Method and Description
public Map<String, String[]>	Returns: an immutable `Map` containing preference names as keys and preference values as map values, or an empty `Map` 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[]`). getMap() Returns a `Map` of the preferences.
public Enumeration<String>	Returns: an Enumeration of the keys that have an associated value, or an empty `Enumeration` if no keys are available. getNames() Returns all of the keys that have an associated value, or an empty `Enumeration` if no keys are available.
public String	Returns: the value associated with `key`, or `def` if no value is associated with `key`, or the backing store is inaccessible. getValue(String key for which the associated value is to be returned key, String the value to be returned in the event that there is no value available associated with this `key`. def) Returns the first String value associated with the specified key of this preference.
public String[]	Returns: the String array value associated with `key`, or `def` if the associated value does not exist. getValues(String key for which associated value is to be returned. key, String[] 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. def) Returns the String array value associated with the specified key in this preference.
public boolean	Returns: false, if the value of this key can be changed, or if the key is not known isReadOnly(String key) Returns true, if the value of this key is defined as read-only and thus cannot be modified by the user.
public void	reset(String to reset key) Resets or removes the value associated with the specified key.
public void	setValue(String key with which the specified value is to be associated. key, String value to be associated with the specified key. value) Associates the specified String value with the specified key in this preference.
public void	setValues(String key with which the value is to be associated key, String... values to be associated with key values) Sets a multi-valued String preference for the specified key.
public void	store() Commits all changes made to the preferences via the `set` methods in the persistent store.

Method Detail

getMap back to summary

getMap	back to summary
public Map<String, String[]> 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`. Returns:Map<String, String[]> an immutable `Map` containing preference names as keys and preference values as map values, or an empty `Map` 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[]`).

public Map<String, String[]> 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.

Returns:Map<String, String[]>: an immutable Map containing preference names as keys and preference values as map values, or an empty Map 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[]).

getNames back to summary

getNames	back to summary
public Enumeration<String> getNames() Returns all of the keys that have an associated value, or an empty `Enumeration` if no keys are available. Returns:Enumeration<String> an Enumeration of the keys that have an associated value, or an empty `Enumeration` if no keys are available.

public Enumeration<String> getNames()

Returns all of the keys that have an associated value, or an empty Enumeration if no keys are available.

Returns:Enumeration<String>: an Enumeration of the keys that have an associated value, or an empty Enumeration if no keys are available.

getValue back to summary

getValue	back to summary
public String getValue(String key, String def) 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. A `null` value is treated as a non-existent value. Parameters key:String key for which the associated value is to be returned def:String the value to be returned in the event that there is no value available associated with this `key`. Returns:String the value associated with `key`, or `def` if no value is associated with `key`, or the backing store is inaccessible. Exceptions IllegalArgumentException: if `key` is `null`. (A `null` value for `def` is permitted.) See Also `getValues(String, String[])`

public String getValue(String key, String def)

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. A null value is treated as a non-existent value.

Parameters

key:String: key for which the associated value is to be returned
def:String: the value to be returned in the event that there is no value available associated with this key.

Returns:String

the value associated with key, or def if no value is associated with key, or the backing store is inaccessible.

Exceptions

IllegalArgumentException:: if key is null. (A null value for def is permitted.)

See Also

getValues(String, String[])

getValues back to summary

getValues	back to summary
public String[] getValues(String key, String[] def) 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. A `null` value is treated as a non-existent value. 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:String key for which associated value is to be returned. def:String[] 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. Returns:String[] the String array value associated with `key`, or `def` if the associated value does not exist. Exceptions IllegalArgumentException: if `key` is `null`. (A `null` value for `def` is permitted.) See Also `getValue(String, String)`

public String[] getValues(String key, String[] def)

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. A null value is treated as a non-existent value.

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:String: key for which associated value is to be returned.
def:String[]: 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.

Returns:String[]

the String array value associated with key, or def if the associated value does not exist.

Exceptions

IllegalArgumentException:: if key is null. (A null value for def is permitted.)

See Also

getValue(String, String)

isReadOnly back to summary

isReadOnly	back to summary
public boolean isReadOnly(String key) Returns true, if the value of this key is defined as read-only and thus 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, like the `CONFIG` mode, 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. Note that even if this call returns `false` and the preference key is modifiable in general it does not mean that it is modifiable in the scope of the current request, e.g. if this request is a render request. Returns:boolean false, if the value of this key can be changed, or if the key is not known Exceptions IllegalArgumentException: if `key` is `null`.

public boolean isReadOnly(String key)

Returns true, if the value of this key is defined as read-only and thus 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, like the CONFIG mode, 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.

Note that even if this call returns false and the preference key is modifiable in general it does not mean that it is modifiable in the scope of the current request, e.g. if this request is a render request.

Returns:boolean

false, if the value of this key can be changed, or if the key is not known

Exceptions

IllegalArgumentException:: if key is null.

reset back to summary

reset	back to summary
public void reset(String key) throws ReadOnlyException 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:String to reset Exceptions ReadOnlyException: if this preference cannot be modified for this request IllegalArgumentException: if key is `null`.

public void reset(String key) throws ReadOnlyException

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:String: to reset

Exceptions

ReadOnlyException:: if this preference cannot be modified for this request
IllegalArgumentException:: if key is null.

setValue back to summary

setValue	back to summary
public void setValue(String key, String value) throws ReadOnlyException 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. If the same key contained already a `String` or `String[]` value it must be replaced by the new value. Parameters key:String key with which the specified value is to be associated. value:String value to be associated with the specified key. Exceptions ReadOnlyException: if this preference cannot be modified for this request IllegalArgumentException: if key is `null`, or `key.length()` or `value.length` are to long. The maximum length for key and value are implementation specific. See Also `setValues(String, String[])`

public void setValue(String key, String value) throws ReadOnlyException

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.

If the same key contained already a String or String[] value it must be replaced by the new value.

Parameters

key:String: key with which the specified value is to be associated.
value:String: value to be associated with the specified key.

Exceptions

ReadOnlyException:: if this preference cannot be modified for this request
IllegalArgumentException:: if key is null, or key.length() or value.length are to long. The maximum length for key and value are implementation specific.

See Also

setValues(String, String[])

setValues back to summary

setValues	back to summary
public void setValues(String key, String... values) throws ReadOnlyException Sets a multi-valued String preference for the specified key. The key cannot be `null`, but `null` values in the values parameter are allowed. If the same key contained already a `String` or `String[]` value it must be replaced by the new value. Parameters key:String key with which the value is to be associated values:String[] values to be associated with key Exceptions ReadOnlyException: if this preference cannot be modified for this request 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. See Also `setValue(String, String)`

public void setValues(String key, String... values) throws ReadOnlyException

Sets a multi-valued String preference for the specified key.

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

If the same key contained already a String or String[] value it must be replaced by the new value.

Parameters

key:String: key with which the value is to be associated
values:String[]: values to be associated with key

Exceptions

ReadOnlyException:: if this preference cannot be modified for this request
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.

See Also

setValue(String, String)

store back to summary

store	back to summary
public void store() throws IOException, ValidatorException Commits all changes made to the preferences via the `set` methods in the persistent store. If this call returns successful, 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 whether the given preferences are valid. If this check fails a `ValidatorException` is thrown. Exceptions IOException: if changes cannot be written into the backend store ValidatorException: if the validation performed by the associated validator fails IllegalStateException: if this method is called inside a render call See Also `PreferencesValidator`

public void store() throws IOException, ValidatorException

Commits all changes made to the preferences via the set methods in the persistent store.

If this call returns successful, 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 whether the given preferences are valid. If this check fails a ValidatorException is thrown.

Exceptions

IOException:: if changes cannot be written into the backend store
ValidatorException:: if the validation performed by the associated validator fails
IllegalStateException:: if this method is called inside a render call

See Also

PreferencesValidator

public Interface PortletPreferences

Method Summary

Method Detail