Package com.kabira.platform.component

Component support.

See: Description

Class Summary

Class	Description
Notifier	Component state change notifier class.

Exception Summary

Exception	Description
ComponentException	Component load failed exception.

Package com.kabira.platform.component Description

Component support.

A component is a jar file. It is identified as a component by the addition of a properties file named ast.properties to the top level of the jar, or in any class path top level directory.

At JVM startup all components found in the class path will be automatically activated. Components are activated in the order they are found in the class path.

Component activation occurs before main.

Component deactivation occurs automatically during JVM shutdown.

A component may contain configuration files.

A component may contain state change notifiers.

Properties File

The ast.properties file supports the following properties:

• Component-Name

  This property is required.

  A string uniquely identifying the component. If multiple components are found with the same Component-Name a trace message will be logged and the duplicate components will be ignored. This can occur if the same Component-Name is used in different components, or if the same component is found multiple times within the class path.

• Configuration-Files

  A comma separated list of configuration files which include path information relative to the top of the jar. It is recommended that configuration files are stored with enough path to prevent collisions with files of the same name in other components.

• Component-Notifiers

  A comma separated list of fully qualified class names which extend Notifier

Example:

 
 Configuration-Files      my/company/configuration/endpoints.kcs, \
                          my/company/configuration/states.kcs

 Component-Notifiers      my.company.component.Notifier
 
 

Configuration Files

Configuration files are automatically loaded and activated at component activation time.

Configuration files are loaded and activated in the order listed in the Configuration-Files property.

Component activation fails if a configuration file cannot be found, or if there is a configuration load or activate error.

Configuration files are automatically deactivated and unloaded as the component is shutdown. Deactivation failures are ignored.

Notifiers

Notifiers are invoked in the order specified in the Component-Notifiers property.

Component activation fails if the notifier class cannot be found.

A single instance of each notifier is instantiated and is used from activation through deactivation of the component.

Component activation fails if a class specified in Component-Notifiers does not extend Notifier

The execution order of the terminate notification and Runtime shutdown hooks is undefined.

A ComponentException thrown by an initialization notifier causes component activation to fail.

Startup Sequence

A transaction is started.

For each component found within the class path the following steps occur in order:

• The ast.properties file is read.
• Each Notifier from the Component-Notifiers property is instantiated and Notifier.preConfigurationInitialize() is called.
• Each configuration file from the Configuration-Files property is loaded and activated.
• Notifier.postConfigurationInitialize() is called for each Notifier.

The transaction is committed.

main is executed.

Startup Failure Handling

If the startup sequence fails, the following cleanup occurs:

• An error message is sent to the event log.
• An error message is printed on standard out.
• The transaction is rolled back. Rollback deactivates and unloads any configuration files that have been loaded, and deletes any Notifiers that have been created.
• JVM startup fails.

Shutdown Sequence

For each component activated at JVM startup, in reverse from which it was activated, the following steps occur in order:

• For each Notifier, in reverse order from it was were created, Notifier.preConfigurationTerminate() is called.
• Each configuration file activated from the component is deactivated and unloaded in reverse order from which it was activated. Configuration file deactivation and unload failures are ignored.
• For each Notifier, in reverse order from which it was created, Notifier.postConfigurationTerminate() is called.
• Each Notifier is deleted, in reverse order from which they were created.