This section describes the life cycle of features for the Lotus® Expeditor platform. It is important to understand the feature life cycle when distributing features to client systems.
Just like the plug-ins that exist within the platform, the features that define the plug-ins have a similar life cycle that affects the ability to use what they provide.
A feature exists in one of three states:
This refers to a feature that is not installed on the platform sites. This is either a feature that has never been installed or one that was previously installed and then had an uninstall operation performed on it. During the uninstall operation, the uninstall methods of the InstallHandler are invoked.Installed
The installed state is entered either by performing an install action on an uninstalled feature, or disabling an enabled feature.Configured (or Enabled)
For an uninstalled feature that is installed, the install related methods of any InstallHandler associated with the feature are called.
For a previously enabled feature that is being disabled, the unconfigure related methods of any InstallHandler are called. For a feature to successfully install, the feature descriptor as well as any required plug-ins must be accessible and valid to be copied to the platform site. In addition, any requirements expressed by the feature must also be met before it can be installed. A validation phase occurs prior to attempting an install to verify that the feature deployment descriptors are accessible, and that the requirements are satisfied. Plug-in existence and validity (that is, the valid signed certificate) are checked during the actual task of installing the feature.
A feature that is only installed does not provide any function to the platform, and its contained plug-ins are not installed into the runtime.
The configured (or enabled) state occurs by performing a configure (or enable) operation on a feature in the installed state. During the configure operation, the configure related methods of the InstallHandler are called to perform tasks.
Once configured, the feature and its contained plug-ins are then able to provide function to the platform.
A feature that is currently enabled can be disabled, but only if by doing so it would not invalidate other features dependencies upon the feature or its contained plug-ins.
The enable and disable operations require a platform restart before the results are effective.
Now that the life cycle of features has been explained, we can now discuss the role of the InstallHandler, which was referenced above.
InstallHandlers may be specific to either a single feature, or global to the entire platform. Regardless of the type, the behavior and call sequence is equivalent.
The InstallHandler class will be instantiated prior to any operation. The first call (after the constructor) will always be the initialize method. This method sets up the install handler and provides information that can be used throughout the call sequence.
During an install operation, the following sequence of calls would be made:
Refer to the Javadoc for specific signature information. Once initialize method has been called, the installCompleted call will always be performed. The installCompleted call is passed a Boolean indicating success or failure of the install operation.
Tasks that need to be performed to install the feature should be performed during the range of calls from installInitiated to completeInstall. A CoreException thrown during these methods will result in the feature failing to install. At the point when the installCompleted() method is called, the feature is either installed or not installed. While the signature allows a CoreException to be thrown at this point, it is strongly recommended that features do not throw a CoreException from the installCompleted (true) call, as it will result in error messages being logged, but will still result in the feature being installed.
During the configure (or enable) operation, the following sequence of calls would be made:
As in the install case, once the install handler has been initialized, the configureCompleted() method will always be called. As in the install case, the configureCompleted() does allow a CoreException to be thrown, but work should preferably be done in either the configureInitiated or completeConfigure methods. A failure in any of the methods will result in the feature not being configured.
The install handler is also called during the disable operation in the following sequence:
A CoreException thrown in the unconfigureInitiated method will abandon install handler processing for the feature, and the completeUnconfigure and unconfigureCompleted methods will not be called. Unless exceptions otherwise inhibit the call, unconfigureCompleted() will be called following an initialize. It is suggested that the main install handler work be performed in the unconfigureInitiated() and completeUnconfigure() methods.
Finally, the install handler is called during the uninstallation of a feature.
A CoreException thrown in the uninstallInitiated method will abandon install handler processing for the feature, and the completeUninstall and uninstallCompleted methods will not be called. Unless exceptions otherwise inhibit the call, uninstallCompleted() will be called following an initialize. It is suggested that the main install handler work be performed in the uninstallInitiated() and completeUninstall() methods.
When the multiuser platform configuration is used, features installed by the administrator and available to the users will only be installed a single time. This means that the install methods of the install handlers will be run at most once. For this reason, and in anticipation of a change in a direction of install processing, it is not recommended that install handlers perform work related to feature configuration during the install related methods of the install handler. Features will be configured (or enabled) multiple times, at least once in each workspace, so the preferable location for feature related changes would be the configure related methods.
Parent topic: Packaging applications for deployment: XPD621