Portlet preferences are the basic configuration data for portlets. A preference is a name and value pair. The type of the name is a string, whereas the type of the value is either a string or an array of strings. A portlet preference is not suited for storing arbitrary data. The portlet container provides persistent storage for portlet preferences.
Preferences persistence relies on the portal infrastructure
The following part of the portlet deployment descriptor lists some values for portlet preferences:
<portlet> <!-- Portlet Preferences --> <portlet-preferences> <preference> <name>PreferredStockSymbols</name> <value>FOO</value> <value>XYZ</value> <read-only>true</read-only> </preference> <preference> <name>quotesFeedURL</name> <value>http://www.foomarket.com/quotes</value> </preference> </portlet-preferences> </portlet> |
These portlet preferences are accessed in the code in the following way:
PortletPreferences prefs = request.getPreferences(); String[] symbols = prefs.getValues("preferredStockSymbols", new String[]{"ACME","FOO"}); String url = prefs.getValue("quotesFeedURL",null); int refreshInterval = Integer.parseInt(prefs.getValue("refresh","10")); |
As there is no preference value associated with the refresh key, the specified default value of 10 is returned.
To set a preference value, you use the following code:
PortletPreferences prefs = request.getPreferences(); if (prefs != null) { prefs.setValue("preferredLanguage", "English"); prefs.store(); } |
All changes made to the PortletPreferences object not followed by a call to the store method are discarded when the portlet finishes the actionRequest method.
If you need to validate values in the PortletPreferences before storing them, you can associate a validator with the preferences in the portlet definition. The portlet container invokes the validate method of the validator before writing the changes to persistent storage.
The following code associates a class that impements the PreferenceValidator interface with the preferences definition in the portlet deployment descriptor:
<!-- Portlet Preferences --> <portlet-preferences>
<preferences-validator> com.foo.portlets.XYZValidator </preferences-validator> </portlet-preferences> |
The store method should not be invoked within the scope of a render method invocation. An invocation of this kind throws an IllegalStateException to be thrown.