net.sf.genuine.organizer
Interface Module

All Known Implementing Classes:

AbstractModule

public interface Module

A module defines a self-contained part of a client application that runs inside the Organizer. An application typically consists of many modules. Between modules, no direct connections (i.e. method calls) should be made. Rather, modules should only send messages or call methods on services that are provided by other modules.

This interface defines the functionality, the Organizer needs to integrate a module into an application. To actually include a module into an application you need to add its definition to an application's configuration file. Such a file is passed to the Organizer at start up time. The organizer parses it and initializes all modules defined there. See the example application's configuration file.

A module lives inside a restricted environment. Its life-cycle is determined by the module manager that creates and destroys modules. The module manager does not influence the module's internal state, though. The module is therefore responsible to fully initialize itself when asked to do so.

Author:

Tim Wellhausen

Method Summary

VisualComponent	createVisualComponent(java.lang.String componentId, java.lang.String instanceId) If the XML configuration data for the module includes visual components, the component manager will call this method to fetch the components.
GenuineAction	getAction(java.lang.String actionId) Must return an instance of GenuineAction for each action identifier that is refered to in the module's definition of the application's configuration file.
java.lang.String	getId() Must return the id passed to the initialize method.
Service	getService(java.lang.Class serviceType) If the module has defined to provide services in its configuration file, the service broker will call this method with the defined classes as parameter to fetch the service instances.
void	initialize(java.lang.String id, ModuleManager moduleManager, java.util.Map properties) Called by the ModuleManager to let the module initialize itself.
void	postInitialize() Called by the module manager when all modules have been fully initialized but the organizer frame is not yet visible.

Method Detail

initialize

public void initialize(java.lang.String id,
                       ModuleManager moduleManager,
                       java.util.Map properties)
                throws ConfigurationException

Called by the ModuleManager to let the module initialize itself. A module may not perform any initialization in its constructor. Instead, all initialization should be done in this method besides creating visual components. Visual components must be created in createVisualComponent(String, String).

Parameters:

id - The module's unique identifier that is defined in the application's configuration file.

moduleManager - A reference to the ModuleManager that gives access to all services the Organizer provides to modules.

properties - A collection of properties that has been defined for this module in the application's configuration file. For each key, there is either an Object value or a Set of Object values, depending on the XML configuration data. For each property defined, there is a Object value, for each propertyset defined, there is a Set of Object values. If the value is an integer, the value instance is of type Integer, otherwise the value instance is of type String. A Set instance is actually an instance of LinkedHashSet so that the order of values is kept as in the configuration file if you iterate over them.

Throws:

ConfigurationException - Thrown by the module if a severe error occurs during its initialization so that the module cannot operate.

getId

public java.lang.String getId()

Must return the id passed to the initialize method.

getAction

public GenuineAction getAction(java.lang.String actionId)

Must return an instance of GenuineAction for each action identifier that is refered to in the module's definition of the application's configuration file.

The module manager will call this method to create menu items and tool bar buttons.

createVisualComponent

public VisualComponent createVisualComponent(java.lang.String componentId,
                                             java.lang.String instanceId)
                                      throws ConfigurationException

If the XML configuration data for the module includes visual components, the component manager will call this method to fetch the components. Visual components may only be created in this method!

Genuine supports both visual components that are unique and visual components for which there may be multiple instances. Whether there should be only one instance or multiple instances can be set in the XML configuration data for the visual component. The attribute "instances" has to be left or set to "single" to enforce a single instance. The attribute value "multiple" leads to creating many instances. See the application.dtd file for more information.

If a component should have only a single instance, the component manager creates that instance at application start up by calling this method once for the corresponding component. If there may be multiple instances of a component, the component manager creates another instance whenever ComponentManager.showComponent(String, String) is called.

An instance identifier is passend regardless whether there are multiple instances.

Parameters:

componentId - The id of the component as given in the XML configuration data

Throws:

ConfigurationException

getService

public Service getService(java.lang.Class serviceType)

If the module has defined to provide services in its configuration file, the service broker will call this method with the defined classes as parameter to fetch the service instances.

postInitialize

public void postInitialize()
                    throws ConfigurationException

Called by the module manager when all modules have been fully initialized but the organizer frame is not yet visible. May be used by a module to perform operations that can only be performed when all modules are alive. All other initialization activities should be performed inside initialize(String, ModuleManager, Map).

Throws:

ConfigurationException - Thrown by the module if a severe error occurs during its post initialization so that the module cannot operate.