Portlet API (V0.7.1) : Interface PortletPreferences

Package | Class | Tree | Deprecated | Index | Help
| Portlet API (V0.7.1)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.portlet
Interface PortletPreferences

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.
- non-modifiable preferences - these preferences cannot be changed by the portlet in any standard portlet mode, but may be changed by administrative modes. Preferences are non-modifiable, if the are defined in the deployment descriptor with `modifiable` set to zero.

Changes are persisted when the `store` method is called. Changes that are not persisted are discarded when the `processAction` or `render` method ends.

Method Summary
`java.util.Enumeration` | `getNames()` Returns all of the keys that have an associated value, or an empty `Enumeration` if no keys are available.
`java.lang.String` | `getValue(java.lang.String key, java.lang.String def)` Returns the first String value associated with the specified key in this preference.
`java.lang.String[]` | `getValues(java.lang.String key, java.lang.String[] def)` Returns the String array value associated with the specified key in this preference.
`boolean` | `isModifiable(java.lang.String key)` Returns true, if the value of this key can be modified by the user.
`void` | `reset(java.lang.String key)` Resets or removes the value associated with the specified key.
`void` | `setValue(java.lang.String key, java.lang.String value)` Associates the specified String value with the specified key in this preference.
`void` | `setValues(java.lang.String key, java.lang.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

### isModifiable

    public boolean isModifiable(java.lang.String key)

  Returns true, if the value of this key can 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.

  Non-modifiable preferences cannot be changed by the portlet in any standard portlet mode, but may be changed by administrative modes. Preferences are non-modifiable, if they are defined in the deployment descriptor with `modifiable` set to zero.

  Returns:
    true, if the value of this key can be changed, or if the key is not known
  Throws:
    `java.lang.IllegalArgumentException` - if `key` is `null`.

### getValue

    public java.lang.String getValue(java.lang.String key,
                                     java.lang.String def)

  Returns the first String 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.

  Some implementations may store default values in their backing stores. If there is no value associated with the specified key but there is such a stored default, it is returned in preference to the specified default.

  Parameters:
    `key` - key for which the associated value is to be returned
    `def` - the value to be returned in the event that there is no value available associated with this `key`.
  Returns:
    the value associated with `key`, or `def` if no value is associated with `key`, or the backing store is inaccessible.
  Throws:
    `java.lang.IllegalArgumentException` - if `key` is `null`. (A `null` value for `def` is permitted.)
  See Also:
    `getValues(String, String[])`

### getValues

    public java.lang.String[] getValues(java.lang.String key,
                                        java.lang.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.

  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 with `key` 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`, or `def` if the associated value does not exist.
  Throws:
    `java.lang.IllegalArgumentException` - if `key` is `null`. (A `null` value for `def` is permitted.)
  See Also:
    `getValue(String,String)`

### setValue

    public void setValue(java.lang.String key,
                         java.lang.String value)
                  throws UnmodifiableException

  Associates the specified String value with the specified key in this preference.
  Parameters:
    `key` - key with which the specified value is to be associated.
    `value` - value to be associated with the specified key.
  Throws:
    `UnmodifiableException` - if this preference cannot be modified for this request
    `java.lang.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

    public void setValues(java.lang.String key,
                          java.lang.String[] values)
                   throws UnmodifiableException

  Associates the specified String array value with the specified key in this preference.
  Parameters:
    `key` - key with which the value is to be associated
    `values` - values to be associated with key
  Throws:
    `java.lang.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.
    `UnmodifiableException` - if this preference cannot be modified for this request
  See Also:
    `setValue(String,String)`

### getNames

    public java.util.Enumeration getNames()

  Returns all of the keys that have an associated value, or an empty `Enumeration` 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.

### reset

    public void reset(java.lang.String key)
               throws UnmodifiableException

  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:
    `java.lang.IllegalArgumentException` - if key is `null`.
    `UnmodifiableException` - if this preference cannot be modified for this request

### store

    public void store()
               throws java.io.IOException,
                      ValidatorException

  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` or `render` methods.

  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:
    `java.io.IOException` - if changes cannot be written into the backend store
    `ValidatorException` - if the validation performed by the associated validator fails
    `java.lang.UnsupportedOperationException` - if this method is called inside a render call
  See Also:
    `PreferencesValidator`

Package | Class | Tree | Deprecated | Index | Help
| Portlet API (V0.7.1)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD