com.novell.afw.portlet.api
Interface EbiPortletPreferences

All Superinterfaces:

Cloneable

All Known Subinterfaces:

EbiPortletPreferencesDefaultType, EbiPortletPreferencesInstanceType, EbiPortletPreferencesUserType, EbiPortletPreferencesWritable

public interface EbiPortletPreferences

extends Cloneable

Interface that represents a collection of preferences that can be expressed as XML. Subclasses will further define methods to manipulate the preference objects.

Since:

v5.0

Method Summary

List	getAllPreferences(Locale locale) Returns a List with all the preferences in the given locale.
String	getDisplayableXML(Locale locale) Deprecated. Use EboPortletPreferencesDisplayHelper.getDisplayableXML() to produce these results.
EbiPortletPreferences	getParentPreferences() Returns the parent level preferences.
EbiPortletPreference	getPreference(String name, Locale locale) Returns a preference by name and locale.
Map	getPreferenceMap(Locale locale) Returns a Map with all the preferences for a given locale keyed by the preference name.
boolean	isPreferenceInherited(EbiPortletPreference pref) Indicates if the preference passed comes directly from this level of preferences, or if it is a value that is inherited from a lower level.
StringBuffer	toXML(boolean composite) Returns an XML document representing the preferences.

Method Detail

getParentPreferences

public EbiPortletPreferences getParentPreferences()

Returns the parent level preferences. This will be null if the preferences object was not created as composite, or the preferences object is the top level and has no parent.

Returns:

EbiPortletPreference reference to the parent, or null if there is none, or the preferences object was not created in composite.

Since:

v5.0

toXML

public StringBuffer toXML(boolean composite)
                   throws EboUnrecoverableSystemException

Returns an XML document representing the preferences. This is the XML used to persist the set of preferences and might also be used by the UI to assist in rendering the preferences.

Parameters:

composite - if true, the xml will represent all levels, otherwise only the xml for the current level.

TODO: include xsd/sample xml

Returns:

an XML document (without the xml header) representing this object.

Since:

v5.0

getDisplayableXML

public String getDisplayableXML(Locale locale)
                         throws EboUnrecoverableSystemException

Deprecated. Use EboPortletPreferencesDisplayHelper.getDisplayableXML() to produce these results.

Returns xml that represents an integrated composite view of the preferences. This differers from the toXML(true) in that this method will not return the same preference more than once, but will indicate if the preference exists at the top level (with the inherihited attribute). This method exists solely for the purpose of rendering the preferences.
Some notes about this method:

• It was designed to be used for administrative UIs.
• It will only return the preferences that exist for the locale that is specified. This means that if the preferences are defined at locale "en" passing in "en_US" will return no preferences since this method returns the XML for the preferences located in the exact locale specified and will not try to calculate other locale variants.
• At the present time, this method works the same way for all implementations of this interface and so the same results can be expected if this method is called on a user level preferences object.
• This method is for internal use and is subject to change.

  Parameters:

  locale - The locale for which to display the preferences.

  Returns:

  a String xml document.

  Throws:

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

  Since:

  v5.0

  See Also:

  com.novell.afw.portlet.util.EboPortletPreferenceDisplayHelper#getDisplayableXML(com.novell.afw.portlet.api.EbiPortletPreferences, com.sssw.fw.api.EbiContext), com.novell.afw.portlet.util.EboPortletPreferenceDisplayHelper#getDisplayableXML(com.novell.afw.portlet.api.EbiPortletPreferences, java.util.Locale[])

getPreference

public EbiPortletPreference getPreference(String name,
                                          Locale locale)

Returns a preference by name and locale. If the locale is null, the default preference locale is returned.

Parameters:

name - String name of the preference.

locale - String locale of the preference. The locale has the format lang || lang_COUNTRY || null.

Returns:

EbiPortletPreference object for the name in the given locale or null if a preference of the given name does not exist in the specified locale.

Since:

v5.0

getAllPreferences

public List getAllPreferences(Locale locale)

Returns a List with all the preferences in the given locale. If locale is null, the the preferences in the default locale are returned. The objects in the Collection will be sorted according to the order of the preferences. The List returned is unmodifiable, and any attempts to modify it will result in a runtime exception.

Parameters:

locale - Locale or null to mean the default locale.

Returns:

List of EbiPortletPreference objects. The Collection should never be null, but may be empty if no preferences exist.

Since:

v5.0

getPreferenceMap

public Map getPreferenceMap(Locale locale)

Returns a Map with all the preferences for a given locale keyed by the preference name. The the locale is null, the preferences for the default locale are returned. The objects in the Map are sorted in the same manner that the the getAllPreferences() would return the preference list. The Map is unmodifiable and attempts to modify it will result in a runtime exception.

Parameters:

locale - Locale or null to mean the default locale.

Returns:

Map of EbiPortletPreference objects keyed by name. The Map should never be null, but may be empty if no preferences exist.

Since:

v5.0

isPreferenceInherited

public boolean isPreferenceInherited(EbiPortletPreference pref)

Indicates if the preference passed comes directly from this level of preferences, or if it is a value that is inherited from a lower level. This is useful when a determination must be made on wheather to override a preference in the current level or not.

Parameters:

pref - The EbiPortletPreference to test.

Returns:

true is the preference is inherihted.

Since:

v5.0