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
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
|
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> |
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 is the base mapping class for XML-based preferences. It includes the following characteristics:
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. |
get(...)
returns a WcmPrefsObject
object; getString(...)
returns a String setting. 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. toByteArrayXML()
, toXML()
,
writeXML(...)
. 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
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:
getConfiguration()
method.
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.
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.