Preferences API

The Toolkit provides a base API for controller, site, and user preferences. Preference data is stored in XML, defined by a flexible, hierarchical model. The XML structure that you choose for your preference data determines how you extend the base preferences API.

The preferences API provides a single point of access that encapsulates controller preferences, site preferences, user preferences, and bootstrap properties. The API is accessible globally from ConfigurableController.

You can store site and user preferences on a Content Engine to make them available to administrators and end users from any machine. You can also store these preferences locally on the Application Engine for development, or for production environments where versioning of the XML preference documents is not an advantage.

This section describes the conceptual model of the base preferences API and the classes that make up the API. For procedural details on using the base preferences classes, see Step 6: Implement Your Preferences API.

Preferences Model

The design of the base preferences API rests on a set of fundamental building blocks, which you can arrange as necessary to best implement your extended preferences API. These building blocks consist of the following types:

Configuration Root. The configuration root class is the single point of entry into preferences for the application. It provides access to site Preferences and user Preferences. The base Toolkit root class is WcmConfiguration.
Object. An object can contain one or more of each of settings, lists and arrays.
- List. A list contains references to one or more objects, and allows iterative or positional access to each of the contained objects.
- Setting. Settings simply represent string properties or key/values that store the actual preference data.
- Array. An array is like a setting, except that it can have multiple values.

The following diagram illustrates the preferences model. Below the diagram is an XML listing that reflects the data types and hierarchical relationships expressed in the diagram. Note that the Preferences XML Schema offers a lot of flexibility in how you organize your preference data.

<object key="sitePreferences" version="2.0">
   <setting key="listViewMode">1</setting>
   <setting key="browseView">1</setting>
   <setting key="searchView">1</setting>
   <array key="detailedProps">
      <value>ContentSize</value>
      <value>LastModifier</value>
      <value>DateLastModified</value>
      <value>MajorVersionNumber</value>
   </array>
   <list key="referenceServices">
      <object key="referenceService">
         <setting key="name">Image Service</setting>
         <setting key="location">getISContent</setting>
         <setting key="mimeType">application/x-filenet-external-is</setting>
         <setting key="uri">filenet:/is</setting>
         <setting key="visible">false</setting>
         <array key="parameterLabels">
            <value>Library Name</value>
            <value>Document ID</value>
            <value>Page Number</value>
         </array>
      </object>
   </list>
</object>

Base Preference Classes

You build your preferences API on the base classes in the Toolkit's com.filenet.wcm.toolkit.server.util.prefs package: WcmPrefsObject, WcmConfiguration, and WcmBootstrapPrefs. Also included in this package are preferences classes used by ConfigurableController.

WcmPrefsObject

WcmPrefsObject is the base mapping class for XML-based preferences. It includes the following characteristics:

WcmPrefsObjects is loaded from XML, where elements are mapped to the following data types: WcmPrefsObject, String, int and boolean stored as Strings, String array, and List of WcmPrefsObject types. The underlying XML elements corresponding to each data type are listed here:

XML Element	Data Type	Notes
`<setting>`	int	The value of the setting must be a valid number.
`<setting>`	boolean	The value must be the word "true" or "false"
`<setting>`	String
`<array>`	String [ ]
`<object>`	WcmPrefsObject	Build a tree this way.
`<list>`	WcmPrefsObject [ ]	Returned as java.util.List. Class must be the same for all entries.

WcmPrefsObject provides data type accessors for each supported data type. For example, get(...) returns a WcmPrefsObject object; getString(...) returns a String setting.
You can create one or more subclasses of WcmPrefsObject in order to add custom accessors for your custom application. These subclasses can then be registered through WcmPrefsObject.registerKey(...), which maps a key name to a WcmPrefsObject class when loading from XML. With custom accessors, coding in an IDE or an editor that supports Java™ Intellisense becomes a snap.
For a small number of preferences, you can use WcmPrefsObject directly as a generic map, creating a tree of maps representing the preferences.
WcmPrefsObject writes out to XML, for example, toByteArrayXML(), toXML(), writeXML(...).
Any preferences data structure is implicitly upgradeable provided that either of the following conditions are met:
- Your custom application sets up a sane default for anything accessed via the base WcmPrefsObject, and sets it accordingly if the accessor returns null.
- Your custom application uses subclassed WcmPrefsObjects that provide custom accessors that return sane defaults (and set them in the map) when no map entry is found.
  Therefore, if new preferences are required in future releases of your custom application, they can be supported without the need of a preferences upgrade tool or of upgrading preferences in the application installer.

WcmConfiguration

WcmConfiguration is the point of entry into preferences objects; that is, the standard interface for user and site preferences provided by ConfigurableController.getConfiguration(). By convention, an application will call getConfiguration() to access preferences. Other characteristics are as follows:

At application start-up, WcmConfiguration initiates loading of XML preference documents (site and user) to WcmPrefsObject objects. If preference documents are not found in the specified Content Engine object store, WcmConfiguration will copy the default preference documents from the Application Engine to the object store.
Constructor takes parameters to help in document naming on the Content Engine.
WcmConfiguration uses Content Engine version control to manage update conflicts.
WcmConfiguration can persist XML locally on the Application Engine as well persist it as documents on the Content Engine.
WcmConfiguration does not register any WcmPrefsObject subclasses.
WcmConfiguration allows you to instantiate a WcmBootstrapPrefs object to load and save bootstrap settings.
For a preferences root other than site or user preferences, you have the option of subclassing WcmConfiguration and implementing another preferences accessor, or of setting up persistence independent from the WcmConfiguration object.
WcmConfiguration implements WcmConfigurationInterface:
- Returned by ConfigurableController, or your controller implementation of the getConfiguration() method.
- Defines user and site preferences roots.
- Provides persistence interface for preference object trees.
- Defines the persistence mechanism that will be used. The default implementation provided by the Toolkit persists preferences as documents in the object store.

WcmBootstrapPrefs

The WcmBootstrapPrefs class represents the configured bootstrap settings, and includes accessor methods to read and change the settings. Bootstrap settings are stored in the bootstrap.properties file located by default in <AE_deploy_path>/FileNet/Config/AE/bootstrap.properties. Optionally, you can place bootstrap.properties in a shared location to accommodate web farm/clusters environments. The shared location is specified in <app_root>/WEB-INF/web.xml.

ConfigurableController Preferences Classes

The ConfigurableController is configured with XML-based preferences. It leverages the following WcmPrefsObject subclasses to manage its settings: AllControllerPrefs, ControllerPrefs, and HomePagePrefs. When ConfigurableController is instantiated, these classes are deserialized from the /<app_root>/WEB-INF/p8controller.xml file. The elements in p8controller.xml are mapped to the data types supported by WcmPrefsObject. The subclasses are registered through WcmPrefsObject.registerKey(...).

AllControllerPrefs registers itself, ControllerPrefs, and HomePagePrefs as WcmPrefsObject objects. It loads the default ConfigurableController preferences. If you were to implement more than one controller, then it would load the settings for the additional controllers as well. AllControllerPrefs provides the accessor to the ControllerPrefs object.

ControllerPrefs stores and provides accessors to each of the ConfigurableController preferences. These preferences include homePage settings, which specify the top-level JavaServer Pages (JSP) pages for various categories of functionality: browse, search, tasks, and so on. Each homePage preference is stored as an object of type HomePagePrefs, with each HomePagePrefs object put into a HashMap. You can retrieve a specified HomePagePrefs object from the HashMap, and call HomePagePrefs accessors to retrieve preference settings on the object.

For a description of the preferences in p8controller.xml, see ConfigurableController Preferences.