Datasheet

portlet, and following that example, you could have a preference called “cities,” with values represent-
ing the zip codes of the cities for which you want the weather. Note that preferences are only meant for
configuring the portlet, so maintaining the list of all cities available in a preference would be an inappro-
priate use of preferences. Thinking of them in an object-oriented programming sense, they would be
attributes of the portlet itself.
Preferences are manipulated through an object that implements
PortletPreferences. All preference
values are stored as String arrays, so you would not have the capability to store complex objects as you
do with request or session attributes, nor do you have the advantage of declaring the type, as you would
with environment entries. Therefore, if you are storing numbers as preferences, you will need to do con-
versions yourself.
Specifically, the
PortletPreferences interface provides the following:
❑
getNames — This returns an Enumeration of the names of the available preferences.
❑
getValue — You pass it the name of the preference you are looking for, along with a default value
(in case it isn’t found), and it returns the first element of the array of that preference’s values.
❑
getValues — You pass it the name of the preference you want and a String array of default val-
ues and it returns a String array of its values.
❑
setValue — You pass it the name of the preference and the value of that preference, and it
sets it to a single-element String array containing that value. This method throws an
UnmodifiableException if the preference cannot be modified.
❑
setValues — You pass it the name of the preference and a String array representing the values for
that name, and it sets the preference values. This method throws an
UnmodifiableException if
the preference cannot be modified.
❑
isReadOnly — You pass it the name of a preference and it returns a Boolean indicating whether
the preference can be modified.
❑
reset — You pass it the name of the preference and it will restore the default; if there is no
default, it will delete the preference.
❑
store — This stores the preferences. Because this can only be done from within processAction,
it will throw an
IllegalStateException if it is done from within a render invocation. The
method will also throw a
ValidatorException if it fails validation.
❑
getMap — This returns a Map of the preferences. The Map consists of String keys and a
String[] for values. This map is also immutable (cannot be changed).
Note two important things to understand about the store method. First, it is an
atomic transaction. Therefore, all of the changes must succeed or none of them will
succeed. This is critical to understand if you have an enormous preference list for
your portlet and you don’t do a tremendous amount of validation of the input.
Second, you could get stung by concurrent writes to the preference store. The critical
message here is that you should view your preferences as one distinct entity and not
a collection of independent parameters accessible through a common interface.
17
The Java Portlet API (JSR 168)
04 469513 Ch01.qxd 1/16/04 11:04 AM Page 17