com.mmoui.manager.services
Interface ConfigurationService

All Superinterfaces:

Service

public interface ConfigurationService
extends Service

Defines an OSGi service which allows for the configuration of modules. The service provides both XML serialization in a safe manner as well as a configuration panel for users to use.

Version:

$Id: ConfigurationService.java 223 2009-05-14 10:10:05Z mpdelbuono $

Author:

Matthew P. Del Buono

Nested Class Summary

static interface

ConfigurationService.XMLStreamWriter Defines an interface through which services can output XML data.

Method Summary

void	commit() Called by the core when configuration is completely loaded.
ConfigurationReader	getConfigurationReader() Obtains a ConfigurationReader object for this module.
java.awt.Component	getPanel() Gets the configuration panel provided by this ConfigurationService object.
void	saveConfiguration(ConfigurationService.XMLStreamWriter out) Requests that the module save its configuration data to the specified XML stream.

Methods inherited from interface com.mmoui.manager.services.Service

getAdvertisements, getFullProviderName, getPermissions, getShortProviderName

Method Detail

getPanel

java.awt.Component getPanel()

Gets the configuration panel provided by this ConfigurationService object. This allows the configuration service to provide a user interface inside a standardized dialog to the user.

The configuration UI is provided by a Swing layout, so if desired, a Swing component can be returned. A JPanel is the preferred component to return.

Returns:

The Component object to display inside this configuration service's frame, or null if no configuration panel is to be displayed.

getConfigurationReader

ConfigurationReader getConfigurationReader()

Obtains a ConfigurationReader object for this module. Methods from within the ConfigurationReader object are called during initialization to allow the module to read its configuration information in a secure manner.

Returns:

A ConfigurationReader object which can be used by the manager to supply configuration data, or null if no configuration is necessary.

saveConfiguration

void saveConfiguration(ConfigurationService.XMLStreamWriter out)
                       throws java.io.IOException

Requests that the module save its configuration data to the specified XML stream. If no configuration is necessary, an immediate return is permissible.

The bundle has its own section of the global XML configuration file. The bundle may use this section in any way it deems fit, however, the following identifiers are reserved for the global configuration and may not be used as element names at any time:

• <Configuration>
• <Globals>
• <Bundle>

Attempts to generate an invalid XML file may raise a XMLStreamException. If this occurs, the stream will remain stable and the module can attempt to recover. If the module fails to recover, or does not wish to recover, the module may throw an XMLStreamException from this method. The manager will catch this exception and purge the bundle's section from the global configuration file. This will result in the configuration data for the bundle being lost.

Parameters:

out - The output stream to which XML data should be written

Throws:

java.io.IOException - If an unhandled XML exception occurs during the writing process

commit

void commit()

Called by the core when configuration is completely loaded. This is called on all configuration service implementations, regardless of whether or not they had any information loaded. This serves as a final indication that all data has been loaded and the system is ready.

This method should execute very quickly to allow the system to continue with other tasks. Any further processing required should be deferred to another thread.

Since:

2.2.1