com.day.crx

Interface CRXModule

public interface CRXModule

The CRXModule interface defines the API which must be implemented by modules extending the functionality of the repository. Modules are installed into the repository either by configuration or by calling the CRXRepository#installModule(javax.jcr.Session, CRXModule) method.

Lifecycle

The life cycle of a module encompasses six stages:

Instantiation

The extension class instantiated either by the repository in the case of a configured module or by the application when manually installing the module.

Configuration

The extension class is configured. In the case of a configured module, configuration is based on bean style properties being set. When manually installing the module, configuration may happen in an application specific way.

Start

The module is started when it is installed into the repository. Starting the module comprises two steps: (1) Starting and (2) registering the module internally. These operations are implemented by the repository.

Operation

After having been started until being stopped, the module may operate as implemented. A module should not operate before being started and should cease operating after having been stopped.

Stop

The module is stopped when it is uninstalled from the repository. Stopping the module comprises two steps: (1) Unregistering the module internally and (2) stopping the module. After having been stopped, the module should not operate anymore.

Garbage Collection

After the module has been stopped, the repository releases all hard references to the module instance. Provided no other hard references exist any more, the object will be collected by the Java VM sooner or later.

When the repository is shutting down, all modules which are still installed are uninstalled, that is unregistered and stopped.

Configuration

A module configured with the the repository configuration file is configured automatically when the repository is started. Modules are configured in Module elements nested within the Modules element. Configuration properties may be set by nested param elements.

When the module is installed by the repository, the module's class as configured in the Module.class attribute is instantiated and the configured properties from the nested param elements are set JavaBean style.

For the repository to be able to instantiate the module, the module must have a public default constructor. Also the property setter methods must be public and for each property a setter and a getter method must be provided for the parameter configuration to be successfull.

Installation

Modules may be installed automatically when the repository is started or manually by the application. To automatically start the modules, they must be configured as described above. To manually install a module, the application is responsible for the instantiation and configuration of the module.

To install, the application will call the CRXRepository#installModule(javax.jcr.Session, CRXModule) which then calls the start(CRXSession) method to start the module before registering it.

Method Summary

Modifier and Type	Method and Description
java.lang.String	getName() Returns the name of this module.
void	start(CRXSession session) Starts this module and makes it ready for use.
void	stop() Stops this module.

Method Detail

getName

java.lang.String getName()

Returns the name of this module.

This name is expected to be unique amongst the registered modules and is just used to identify the module. Other than to register the module under this name, the repository does not use it for anything else.

Returns:

The non-null, non-empty module name.

start

void start(CRXSession session)
    throws RepositoryException

Starts this module and makes it ready for use.

This method is called by the repository before registering the module internally. This means, that while this method is active, this module is not yet visible by the CRXRepository.getModule(String) and CRXRepository.getModules() method.

If this method fails by throwing a RepositoryException, any resources already acquired must be released. A module failing to start is also not registered and thus visible. Finally a module failing to start will never be stopped, that is the stop() method will not be called.

This method should only throw a RepositoryException if failing to start. Notably, the implementation should prevent throwing a RuntimeException.

NOTE:

• The module MUST NOT call the logout() method on this session. Otherwise the repository may behave unexpectedly.
• The session is a shared Session. This means, the Session is not thread safe and may at most be used for concurrent read operations but MUST NOT be used to write to the repository. If the module requires writing to the repository, a new Session MUST be acquired calling the CRXSession.getSession(String) method on the session. Such session SHOULD of course be logged out when the module is stopped}.

Parameters:

session - The CRXSession to access the system workspace of the repository. This session is shared and MUST NOT be used to write to the repository. Use the CRXSession.getSession(String) method to get a session to write to the repository.

Throws:

RepositoryException - May be thrown if the module fails to start.

stop

void stop()

Stops this module.

This method is called after the module has been unregistered. If the module failed to start, this method is never called.

This method is not excpected to throw any exception. Care must be taken to prevent RuntimeExceptions from occurring.