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.

See Also
Preferences XML Schema
Sample Applications

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:

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.

Preferences Model

preferences model

XML-Based Preferences Structured as Defined in Above Model

<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:

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:

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.