com.novell.afw.portlet.api
Interface EbiPortletPreference

All Superinterfaces:

Cloneable

All Known Subinterfaces:

EbiPortletPreferenceBoolean, EbiPortletPreferenceComplex, EbiPortletPreferenceInteger, EbiPortletPreferenceLocalized, EbiPortletPreferencePassword, EbiPortletPreferenceSelect

public interface EbiPortletPreference

extends Cloneable

Interface to represent a single portlet preference. It may be marked as a given datatype, and this information should be used by the UI as a hint for rendering the preference. If the datatype is anything other than String, it may be cast to the corresponding interface to allow access to the special methods provided to allow manipulation specific to a given datatype. All other portlet preference interfaces are decendent of this interface.

• String = EbiPortletPreference
• Password = EbiPortletPreferencePassword
• Complex = EbiPortletPreferenceComplex
• Integer = EbiPortletPreferenceInteger
• Boolean = EbiPortletPreferenceBoolean

Each preference is considered to be of one locale or of the default locale (null) , so within a grouping of preferences (see EbiPortletPreferences) there may be many preferences with the same name but with different locales. The default preference (null locale) serve as the base for the localized preferences, and while a separate object does exist for a given localized preference, most methods are delegated to the base. The only ones that are not are accessor/mutators that allow access to properties of the preference that are localizable and have actually been set to be different than the base's property value.

If the preference is marked as encrypted in the descriptor, then the preference will persist its values as encrypted using Phaos FIPS compliant AES encryption algorithm.
Developers should beware that if a preference value is persisted as non-encryted (i.e. encrypted flag == false) then the flag in the descriptor is set to true, the stored data can not be decrypted since it was never encrypted, and that in this case each value that can not be decrypted will be returned as it was stored originally (and a warning will be written to the portlet container log). When the preference is then saved (while the encrypted flag==true) the contents will be encrypted. Along the same lines, if the encrypted flag is set true in the descriptor, and non encrypted value tags are specified in the portlet.xml descriptor, the values in the descriptor will be returned verbatim. This attempting to decrypt and failing along with the log is a costly operation, and so, in a production environment, it is important to make sure that this situtation does not occur.

Since:

v5.0

See Also:

EbiPortletPreferenceInteger, EbiPortletPreferenceBoolean, EbiPortletPreferencePassword, EbiPortletPreferenceSelect, EbiPortletPreferenceComplex, EbiPortletPreferenceLocalized, EbiPortletPreferences, EbiPortletPreferencesWritable, EbiPortletPreferencesDefaultType, EbiPortletPreferencesInstanceType, EbiPortletPreferencesUserType

Field Summary

static String	TYPE_BOOLEAN Constant to indicate that a portlet preference datatype is Boolean.
static String	TYPE_COMPLEX Constant to indicate that a portlet preference datatype is composed of a Complex XML document that a special API can help build.
static String	TYPE_INTEGER Constant to indicate that a portlet preference datatype is Integer.
static String	TYPE_PASSWORD Constant to indicate that a portlet preference datatype is Password.
static String	TYPE_SELECT Constant to indicate that a portlet preference datatype is Select (constrained list).
static String	TYPE_STRING Constant to indicate that a portlet preference datatype is String.

Method Summary

String	getDataType() Returns the string reprentation of the datatype of this preference.
String	getDescription() Returns the description for the preference.
String	getDisplayableXML() Returns an xml that represents an the individual prefeence.
String	getDisplayName() Returns the display name for the preference.
Locale	getLocale() Returns the localization code for the preference.
String	getName() Returns the name of the preference.
String	getValue() Returns the raw string value for the preference.
String	getValue(EbiContext context) Returns the string value with the scoped path resolved based on the context passed in.
String[]	getValues() Returns all values for the preference as a String array.
String[]	getValues(EbiContext context) Returns all values for the preference as a String array.
boolean	isEncrypted() Indicates whether or not the value for this preference will be stored in an encrypted manner.
boolean	isHiddenFromUser() This flag serves as a hint for the UI that it should not show this preference to the general user, but can show it to administrators.
boolean	isMultiValued() Returns true if the preference may have more than one value.
boolean	isReadOnly() Indicates whether the value(s) of this preference can be modified.
boolean	isRequired() Returns true if the preference should have at least one value.
void	setDescription(String description) Sets the localized decription for the preference.
void	setDisplayName(String displayName) Sets the display name for the preference.
void	setHiddenFromUser(boolean hidden) This flag serves as a hint for the UI that it should not show this preference to the general user, but can show it to administrators.
void	setMultiValued(boolean multiValued) Set the flag for whether a portlet will expect multiple values for this preference.
void	setReadOnly(boolean readonly) Specifies whether the value(s) of this preference can be modified.
void	setRequired(boolean required) Sets the flag to indicate that the preference should have at least one value.
void	setValue(String value) Sets the string value for the preference.
void	setValues(String[] values) Sets all values for the preference object.
void	validate() Validates the preference value.

Field Detail

TYPE_STRING

public static final String TYPE_STRING

Constant to indicate that a portlet preference datatype is String.

Since:

v5.0

TYPE_INTEGER

public static final String TYPE_INTEGER

Constant to indicate that a portlet preference datatype is Integer.

Since:

v5.0

TYPE_BOOLEAN

public static final String TYPE_BOOLEAN

Constant to indicate that a portlet preference datatype is Boolean.

Since:

v5.0

TYPE_COMPLEX

public static final String TYPE_COMPLEX

Constant to indicate that a portlet preference datatype is composed of a Complex XML document that a special API can help build.

Since:

v5.0

TYPE_SELECT

public static final String TYPE_SELECT

Constant to indicate that a portlet preference datatype is Select (constrained list).

Since:

v5.0

TYPE_PASSWORD

public static final String TYPE_PASSWORD

Constant to indicate that a portlet preference datatype is Password.

Since:

v5.0

Method Detail

getName

public String getName()

Returns the name of the preference. This will be unique per portlet.

Returns:

the name of the preference, never null.

Since:

v5.0

getDisplayName

public String getDisplayName()

Returns the display name for the preference. This is the name that the UI should display to the user. If this value was not set (i.e. is null) or is set to null, then the getDisplayName method will return the name of the preference (i.e. same as getName()). This is a property that can be set per locale.

Returns:

the display name for the preference, never null.

Since:

v5.0

setDisplayName

public void setDisplayName(String displayName)

Sets the display name for the preference. This is the name that the UI should display to the user. If this value was not set (i.e. is null) or is set to null, then the getDisplayName method will return the name of the preference (i.e. same as getName()). This is a property that can be set per locale.

Parameters:

displayName - String to display as the name in the UI, or null to force usage of the real name of the preference.

Since:

v5.0

getDescription

public String getDescription()

Returns the description for the preference. This is a property that can be set per locale.

Returns:

String description (for the locale of the preference) that can be used by the UI give a full description of what the preference does and the values it can have.

Since:

v5.0

setDescription

public void setDescription(String description)

Sets the localized decription for the preference. This is a property that can be set per locale.

Parameters:

description - String (for the locale of the preference) that can be used by the UI give a full description of what the preference does and the values it can have.

Since:

v5.0

getDataType

public String getDataType()

Returns the string reprentation of the datatype of this preference. The allowable datatypes are defined as constants on the EbiPortletPreference interface and currently include:

EbiPortletPreference.TYPE_STRING

EbiPortletPreference.TYPE_INTEGER

EbiPortletPreference.TYPE_BOOLEAN

EbiPortletPreference.TYPE_PASSWORD

EbiPortletPreference.TYPE_SELECT

EbiPortletPreference.TYPE_COMPLEX.

Returns:

String with the datatype of the preference, never null.

Since:

v5.0

See Also:

EbiPortletPreference.TYPE_STRING, EbiPortletPreference.TYPE_INTEGER, EbiPortletPreference.TYPE_BOOLEAN, EbiPortletPreference.TYPE_PASSWORD, EbiPortletPreference.TYPE_SELECT, EbiPortletPreference.TYPE_COMPLEX, EbiPortletPreferenceInteger, EbiPortletPreferenceBoolean, EbiPortletPreferencePassword, EbiPortletPreferenceSelect, EbiPortletPreferenceComplex

getValue

public String getValue()

Returns the raw string value for the preference. This method will always work and return a string no matter what data type the preference is considered to be. It will return null if the value has not been set for this preference yet. This method returns only the first element of the array if the preference has multiple values ( that is it returns the same thing as getValues()[0] ). This method does NOT expand scoped paths, but returns the raw string as it was stored.

Returns:

String value of the first value or null if none.

Since:

v5.0

See Also:

EbiPortletPreference.getValues(), EbiPortletPreference.getDataType()

getValue

public String getValue(EbiContext context)

Returns the string value with the scoped path resolved based on the context passed in. This method will always work and return a string no matter what data type the preference is considered to be. It will return null if the value has not been set for this preference yet. This method returns only the first element of the array if the preference has multiple values ( that is it returns the same thing as getValues()[0] ). This method DOES expand scoped paths and returns the expanded string.

Parameters:

context - EbiContext used to resolve the scoped path.

Returns:

String value of the first value or null if none. Scoped paths are expanded, so the return value of this method may not be equal to a call to getValue().

Since:

v5.0

See Also:

EbiPortletPreference.getValue(), EbiPortletPreference.getValues(), EbiPortletPreference.getDataType()

setValue

public void setValue(String value)

Sets the string value for the preference. This method can be used no matter what the datatype of the preference is, however, the string should be coercable to the dataype, if it is not, an exception will be thrown during validation. This method operates on only the first element of the values of the preference if the preference has multiple values. Calling this method is roughly equivelant to:
String[] values = getValues();
values[0] = value; setValues(values);

Parameters:

value - String value to set as the current value.

Since:

v5.0

See Also:

EbiPortletPreference.setValues(String[] values)

getValues

public String[] getValues()

Returns all values for the preference as a String array. It should be noted that the implmentation will return a copy of the internal array, and not a reference to it. Thus, the only way to modify the contents of the array is to call setValues() with your modified array. This method does NOT expand scoped paths, but returns the raw string as it was stored.

Returns:

String[] with all the values for the preference. This will be null if no values have been specified.

Since:

v5.0

getValues

public String[] getValues(EbiContext context)

Returns all values for the preference as a String array. This method DOES expand scoped paths and returns each string as expanded. NOTE: This method will add processing overhead, as each time it is called it must resolve the scoped path for each of the strings in the values array. If it is not neccesary to resolved scoped paths, make sure to call getValues() instead.

Returns:

String[] with all the values for the preference. Each string in the array will have any scoped paths expanded.

Since:

v5.0

See Also:

EbiPortletPreference.getValues()

setValues

public void setValues(String[] values)

Sets all values for the preference object. This will replace the entire set of values, so any preexisting values will be replaced. The string array passed in is used as the new value array for the preference. A copy is not made, but the reference to the array passed in is stored. This leaves open the posibility one could modify the array though the external reference to the array. While this should cause no forseen issues, it is recommended references to that array to not be scoped outside of the method.

Parameters:

values - String[] to make the current set of values, or null to remove all values.

Since:

v5.0

isReadOnly

public boolean isReadOnly()

Indicates whether the value(s) of this preference can be modified. There is no runtime prevention of modification of a preference flagged as read-only, however, if the flag is true, any attempts to override the preference at higher levels will fail.
While the flag name is taken from the deployment descriptior's read-only tag, it can also be taken to indicate overridability. This is because, at the deployment descriptor level, the only way to change a value is to override it at a lower level in the hierarchy. Thus the semantic applies to all other levels as well. Of course, this flag only make sense in the context of multi-level hierarchies of preferences. See the EbiPortletPrefereces interface for a description of multi-level preference hierarchies.

Returns:

boolean that is true means that the preference is read-only and can not be overridden.

Since:

v5.0

See Also:

EbiPortletPreferences

setReadOnly

public void setReadOnly(boolean readonly)

Specifies whether the value(s) of this preference can be modified. There is no runtime prevention of modification of a preference flagged as read-only, however, if the flag is true, any attempts to override the preference at higher levels will fail.
While the flag name is taken from the deployment descriptior's read-only tag, it can also be taken to indicate overridability. This is because, at the deployment descriptor level, the only way to change a value is to override it at a lower level in the hierarchy. Thus the semantic applies to all other levels as well. Of course, this flag only make sense in the context of multi-level hierarchies of preferences. See the EbiPortletPrefereces interface for a description of multi-level preference hierarchies.

Since:

v5.0

See Also:

EbiPortletPreferences

getLocale

public Locale getLocale()

Returns the localization code for the preference. If this returns null, it means that the locale is the default locale.

Returns:

the Locale objbect for the designated locale of the preference or null to mean the default.

Since:

v5.0

isRequired

public boolean isRequired()

Returns true if the preference should have at least one value. This is a flag for the client API, and no validation is carried out using this flag.

Since:

v5.0

setRequired

public void setRequired(boolean required)

Sets the flag to indicate that the preference should have at least one value. This is a flag for the client API, and no validation is carried out using this flag.

Parameters:

required - boolean true to indicate that the preference must have at least one value.

Since:

v5.0

isMultiValued

public boolean isMultiValued()

Returns true if the preference may have more than one value. There is programatic enforcement of this value during validation, that is if this method returns false and there is more than one value for the preference, a validation exception will occur. It can also serve as a clue for a GUI as how to render the preference since the code in the portlet will assumably act in agreeance with this setting (i.e. if this returns false, the portlet code will not attempt to access past the first value). If not specified, this value defaults to true for String types, other types will default to an appropriate value for the type.

Returns:

boolean true if the preference can have more than one value.

Since:

v5.0

See Also:

EbiPortletPreference.validate()

setMultiValued

public void setMultiValued(boolean multiValued)

Set the flag for whether a portlet will expect multiple values for this preference. There is programatic enforcement of this value during validation, that is if this method returns false and there is more than one value for the preference, a validation exception will occur. It can also serve as a clue for a GUI as how to render the preference since the code in the portlet will assumably act in agreeance with this setting (i.e. if this returns false, the portlet code will not attempt to access past the first value). If not specified, this value defaults to true for String types, other types will default to an appropriate value for the type.

Parameters:

multiValued - boolean true if the preference should expect more than one value.

Since:

v5.0

isEncrypted

public boolean isEncrypted()

Indicates whether or not the value for this preference will be stored in an encrypted manner. This is set in the descriptor element //portlet/portlet-preferences/preference/encrypted. This setting can not be changed except in the descriptor. Developers should beware that if a preference value is persisted as non-encryted (i.e. encrypted flag == false) then the flag in the novell-portlet.xml is set to true, the data can not be decrypted since it was never encrypted, and that in this case each value that can not be decrypted will be returned as it was stored originally (and a warning will be wrtten to the portlet container log). When the preference is then saved (while the encrypted flag==true) the contents will be encrypted. Along the same lines, if the encrypted flag is set true in the descriptor, and non encrypted value tags are specified in the descriptor, the values in the descriptor will be returned verbatim. This attempting to decrypt and failing along with the log is a costly operation, so in a production environment, it is important to make sure that this situtation does not occur.

Returns:

boolean true to mean that this preference will persist its values in an encrypted format.

Since:

v5.0

isHiddenFromUser

public boolean isHiddenFromUser()

This flag serves as a hint for the UI that it should not show this preference to the general user, but can show it to administrators.

Returns:

true if the preference should be hidden from all users but admins, false if shown to all users.

Since:

v5.0

setHiddenFromUser

public void setHiddenFromUser(boolean hidden)

This flag serves as a hint for the UI that it should not show this preference to the general user, but can show it to administrators.

Parameters:

hidden - boolean false if the preference should be shown to all users, true if only to admins.

Since:

v5.0

validate

public void validate()
              throws com.novell.afw.portlet.exception.EboPortletPreferenceValidationException

Validates the preference value. This method can behave very differently depending on the datatype. If the preference data is valid, the method simply returns, if not, a EboPortletPreferenceValidationException is thrown indicating the cause of the failure.

Throws:

com.novell.afw.portlet.exception.EboPortletPreferenceValidationException - if the value of the preference does not conform to the expressed retrictions for the datatype.

Since:

v5.0

See Also:

, , , ,

getDisplayableXML

public String getDisplayableXML()
                         throws EboUnrecoverableSystemException

Returns an xml that represents an the individual prefeence. This method exists solely for the purpose of rendering the preferences.

TODO: include xsd/sample xml

Returns:

a String xml document.

Throws:

EboUnrecoverableSystemException - thrown is there was an error that could not be recovered from.

Since:

v5.0