javax.portlet.PortletPreferences Maven / Gradle / Ivy
/* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* NOTE: this source code is based on an early draft version of JSR 286 and not intended for product
* implementations. This file may change or vanish in the final version of the JSR 286 specification.
*/
/*
* This source code implements specifications defined by the Java
* Community Process. In order to remain compliant with the specification
* DO NOT add / change / or delete method signatures!
*/
/**
* Copyright 2006 IBM Corporation.
*/
package javax.portlet;
/**
* 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.
*/
public interface PortletPreferences
{
/**
* 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.
*
* @return false, if the value of this key can be changed, or
* if the key is not known
*
* @exception java.lang.IllegalArgumentException
* if key is null.
*/
public boolean isReadOnly(String key);
/**
* 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.
*
* @param key key for which the associated value is to be returned
* @param def the value to be returned in the event that there is no
* value available associated with this key.
*
* @return the value associated with key, or def
* if no value is associated with key, or the backing
* store is inaccessible.
*
* @exception java.lang.IllegalArgumentException
* if key is null. (A
* null value for def is permitted.)
*
* @see #getValues(String, String[])
*/
public String getValue(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.
*
*
* @param key key for which associated value is to be returned.
* @param 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.
*
* @return the String array value associated with
* key, or def if the
* associated value does not exist.
*
* @exception java.lang.IllegalArgumentException if key is null. (A
* null value for def is permitted.)
*
* @see #getValue(String,String)
*/
public String[] getValues(String key, String[] def);
/**
* 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.
*
* @param key key with which the specified value is to be associated.
* @param value value to be associated with the specified key.
*
* @exception ReadOnlyException
* if this preference cannot be modified for this request
* @exception 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 #setValues(String, String[])
*/
public void setValue(String key, String value) throws ReadOnlyException;
/**
* 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.
*
* If the same key contained already a String or String[]
* value it must be replaced by the new value.
*
* @param key key with which the value is to be associated
* @param values values to be associated with key
*
* @exception 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.
* @exception ReadOnlyException
* if this preference cannot be modified for this request
*
* @see #setValue(String,String)
*/
public void setValues(String key, String[] values) throws ReadOnlyException;
/**
* Returns all of the keys that have an associated value,
* or an empty Enumeration if no keys are
* available.
*
* @return an Enumeration of the keys that have an associated value,
* or an empty Enumeration if no keys are
* available.
*/
public java.util.Enumeration getNames();
/**
* 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.
*
* @return 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 java.util.Map getMap();
/**
* 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.
*
* @param key to reset
*
* @exception java.lang.IllegalArgumentException if key is null.
* @exception ReadOnlyException
* if this preference cannot be modified for this request
*/
public void reset(String key) throws ReadOnlyException;
/**
* 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.
*
* @exception java.io.IOException
* if changes cannot be written into
* the backend store
* @exception ValidatorException
* if the validation performed by the
* associated validator fails
* @exception java.lang.IllegalStateException
* if this method is called inside a render call
*
* @see PreferencesValidator
*/
public void store() throws java.io.IOException, ValidatorException;
}