com.metamatrix.common.extensionmodule
Class ExtensionModuleManager

java.lang.Object
  com.metamatrix.common.extensionmodule.ExtensionModuleManager

public class ExtensionModuleManager
extends java.lang.Object

This class is the mechanism to manage the MetaMatrix extension modules.

An "extension module" (formerly known as an "extension source") is a utility file or other source of information. Different types will be supported: JAR files containing Java class files, an XML file of user-defined function meta data, and others. The current implementation will be to store files in binary form centrally in the MetaMatrix platform.

A module "type" is needed to distinguish JAR modules from other modules.

The CurrentConfiguration and Logging are assumed to be available by the time an instance of this class is first initialized.

This object can run standalone (which it needs to be during MetaMatrix installation). To do this, the SystemCurrentConfigBootstrap needs to be used. To do this, first set the required property (the first one listed below). Second, add all required properties to (or replace) the system properties. Third, use the getInstance() method as usual. it is recommended that this be done in it's own process, since it won't work if CurrentConfiguration has already been initialized with a different bootstrap strategy. Alternately, a different bootstrap strategy can be used for CurrentConfiguration, as long as the properties listed below are available to this object via CurrentConfiguration.getInstance().

The following properties are required:

• ExtensionModulePropertyNames.CONNECTION_FACTORY the managed connection factory class; most likely use "com.metamatrix.platform.extension.spi.jdbc.JDBCExtensionModuleTransactionFactory"

The following properties are required with use of JDBCExtensionModuleTransactionFactory:

• ExtensionModulePropertyNames.CONNECTION_DATABASE the JDBC connection database
• ExtensionModulePropertyNames.CONNECTION_DRIVER the JDBC connection driver full classname
• ExtensionModulePropertyNames.CONNECTION_USERNAME the JDBC connection username
• ExtensionModulePropertyNames.CONNECTION_PASSWORD the JDBC connection password
• ExtensionModulePropertyNames.CONNECTION_PROTOCOL the JDBC connection protocol

History: 6/14/02 - Changed to use ResourcePooling instead of the ManagedConnectionPool

Field Summary

static int	SOURCE_CONTENTS_LENGTH_LIMIT The limit, in bytes, to the size of a single extension module.
static int	SOURCE_DESCRIPTION_LENGTH_LIMIT The limit to the number of characters an extension module description can be.
static int	SOURCE_NAME_LENGTH_LIMIT The limit to the number of characters an extension module name can be.

Constructor Summary

ExtensionModuleManager()
constructor

ExtensionModuleManager(java.util.Properties p)

Method Summary

ExtensionModuleDescriptor	addSource(java.lang.String principalName, java.lang.String type, java.lang.String sourceName, byte[] source, java.lang.String description, boolean enabled) Adds an extension module to the end of the list of modules.
static long	getChecksum(byte[] data) Retrieves a checksum value for the contents of an extension module
static ExtensionModuleManager	getInstance() Return a cached ExtensionModuleManager instance for this process, fully initialized and ready for use.
ExtensionModuleTransaction	getReadTransaction()
byte[]	getSource(java.lang.String sourceName) Retrieves an extension module in byte[] form
ExtensionModuleDescriptor	getSourceDescriptor(java.lang.String sourceName) Returns the ExtensionModuleDescriptor object for the extension module indicated by sourceName
java.util.List	getSourceDescriptors() Returns List of ExtensionModuleDescriptor objects, in order of their search ordering, or empty List if no extension modules exist
java.util.List	getSourceDescriptors(java.lang.String type) Returns List of ExtensionModuleDescriptor objects of indicated type, in order of their search ordering, or empty List if no descriptors exist for that type.
java.util.List	getSourceNames() Returns List (of Strings) of all extension module names, in order of their search ordering (empty List if there are none)
java.util.Collection	getSourceTypes() Returns List (of Strings) of all extension module types currently supported.
ExtensionModuleTransaction	getWriteTransaction()
protected void	init(java.util.Properties env) Initializes this object, given the necessary Properties.
boolean	isSourceInUse(java.lang.String sourceName) Returns the ExtensionModuleDescriptor object for the extension module indicated by sourceName
void	notifyFileChanged() Notifies listeners when JDBCNames.ExtensionFilesTable.ColumnName.FILE_TYPE has changed.
void	removeSource(java.lang.String principalName, java.lang.String sourceName) Deletes a module from the list of modules.
java.util.List	setEnabled(java.lang.String principalName, java.util.Collection sourceNames, boolean enabled) Sets the "enabled" (for searching) property of all of the indicated extension modules.
java.util.List	setSearchOrder(java.lang.String principalName, java.util.List sourceNames) Sets the positions in the search order of all modules (all modules must be included or an ExtensionModuleOrderingException will be thrown) The sourceNames List parameter should indicate the new desired order.
ExtensionModuleDescriptor	setSource(java.lang.String principalName, java.lang.String sourceName, byte[] source) Updates the indicated extension module.
ExtensionModuleDescriptor	setSourceDescription(java.lang.String principalName, java.lang.String sourceName, java.lang.String description) Updates the indicated extension module's description
ExtensionModuleDescriptor	setSourceName(java.lang.String principalName, java.lang.String sourceName, java.lang.String newName) Updates the indicated extension module's source name

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SOURCE_NAME_LENGTH_LIMIT

public static final int SOURCE_NAME_LENGTH_LIMIT

The limit to the number of characters an extension module name can be.

See Also:

Constant Field Values

SOURCE_DESCRIPTION_LENGTH_LIMIT

public static final int SOURCE_DESCRIPTION_LENGTH_LIMIT

The limit to the number of characters an extension module description can be.

See Also:

Constant Field Values

SOURCE_CONTENTS_LENGTH_LIMIT

public static final int SOURCE_CONTENTS_LENGTH_LIMIT

The limit, in bytes, to the size of a single extension module.

See Also:

Constant Field Values

Constructor Detail

ExtensionModuleManager

public ExtensionModuleManager()

constructor

Throws:

ManagedConnectionException

ExtensionModuleManager

public ExtensionModuleManager(java.util.Properties p)

Method Detail

getInstance

public static ExtensionModuleManager getInstance()

Return a cached ExtensionModuleManager instance for this process, fully initialized and ready for use. This is not a singleton, it is merely cached for convenience

addSource

public ExtensionModuleDescriptor addSource(java.lang.String principalName,
                                           java.lang.String type,
                                           java.lang.String sourceName,
                                           byte[] source,
                                           java.lang.String description,
                                           boolean enabled)
                                    throws DuplicateExtensionModuleException,
                                           InvalidExtensionModuleTypeException,
                                           MetaMatrixComponentException

Adds an extension module to the end of the list of modules. All caches (of Class objects) are cleared.

Parameters:

principalName - name of principal requesting this addition

type - one of the known types of extension file

sourceName - name (e.g. filename) of extension module

source - actual contents of module

description - (optional) description of the extension module - may be null

enabled - indicates whether each extension module is enabled for being searched or not (for convenience, a module can be disabled without being removed)

Returns:

ExtensionModuleDescriptor describing the newly-added extension module

Throws:

DuplicateExtensionModuleException - if an extension module with the same sourceName already exists

InvalidExtensionTypeException - if the indicated type is not one of the currently-supported extension module types

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null or invalid

InvalidExtensionModuleTypeException

removeSource

public void removeSource(java.lang.String principalName,
                         java.lang.String sourceName)
                  throws ExtensionModuleNotFoundException,
                         MetaMatrixComponentException

Deletes a module from the list of modules. All caches (of Class objects) are cleared.

Parameters:

principalName - name of principal requesting this addition

sourceName - name (e.g. filename) of extension module

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

getSourceTypes

public java.util.Collection getSourceTypes()
                                    throws MetaMatrixComponentException

Returns List (of Strings) of all extension module types currently supported.

Returns:

unmodifiable List of the String names of the currently-supported extension module types

Throws:

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

getSourceNames

public java.util.List getSourceNames()
                              throws MetaMatrixComponentException

Returns List (of Strings) of all extension module names, in order of their search ordering (empty List if there are none)

Returns:

List (of Strings) of all extension module names, in order of their search ordering (empty List if there are none)

Throws:

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

getSourceDescriptors

public java.util.List getSourceDescriptors()
                                    throws MetaMatrixComponentException

Returns List of ExtensionModuleDescriptor objects, in order of their search ordering, or empty List if no extension modules exist

Returns:

List of ExtensionModuleDescriptor objects, in order of their search ordering, or empty List if no extension modules exist

Throws:

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

getSourceDescriptors

public java.util.List getSourceDescriptors(java.lang.String type)
                                    throws InvalidExtensionModuleTypeException,
                                           MetaMatrixComponentException

Returns List of ExtensionModuleDescriptor objects of indicated type, in order of their search ordering, or empty List if no descriptors exist for that type.

Parameters:

type - one of the known types of extension file

Returns:

List of ExtensionModuleDescriptor objects of indicated type, in order of their search ordering, or empty List if no descriptors exist for that type.

Throws:

InvalidExtensionTypeException - if the indicated type is not one of the currently-supported extension module types

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

InvalidExtensionModuleTypeException

isSourceInUse

public boolean isSourceInUse(java.lang.String sourceName)
                      throws MetaMatrixComponentException

Returns the ExtensionModuleDescriptor object for the extension module indicated by sourceName

Parameters:

sourceName - name (e.g. filename) of extension module

Returns:

the ExtensionModuleDescriptor object for the extension module indicated by sourceName

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

getSourceDescriptor

public ExtensionModuleDescriptor getSourceDescriptor(java.lang.String sourceName)
                                              throws ExtensionModuleNotFoundException,
                                                     MetaMatrixComponentException

Returns the ExtensionModuleDescriptor object for the extension module indicated by sourceName

Parameters:

sourceName - name (e.g. filename) of extension module

Returns:

the ExtensionModuleDescriptor object for the extension module indicated by sourceName

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

setSearchOrder

public java.util.List setSearchOrder(java.lang.String principalName,
                                     java.util.List sourceNames)
                              throws ExtensionModuleOrderingException,
                                     MetaMatrixComponentException

Sets the positions in the search order of all modules (all modules must be included or an ExtensionModuleOrderingException will be thrown) The sourceNames List parameter should indicate the new desired order. All caches (of Class objects) are cleared.

Parameters:

principalName - name of principal requesting this addition

sourceNames - Collection of String names of existing extension modules whose search position is to be set

Returns:

updated List of ExtensionModuleDescriptor objects, in order of their search ordering

Throws:

ExtensionModuleOrderingException - if the extension files could not be ordered as requested because another administrator had concurrently added or removed an extension file or files, or because an indicated position is out of bounds.

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

setEnabled

public java.util.List setEnabled(java.lang.String principalName,
                                 java.util.Collection sourceNames,
                                 boolean enabled)
                          throws ExtensionModuleNotFoundException,
                                 MetaMatrixComponentException

Sets the "enabled" (for searching) property of all of the indicated extension modules. All caches (of Class objects) are cleared.

Parameters:

principalName - name of principal requesting this addition

sourceNames - Collection of String names of existing extension modules whose "enabled" status is to be set

enabled - indicates whether each extension module is enabled for being searched or not (for convenience, a module can be disabled without being removed)

Returns:

updated List of ExtensionModuleDescriptor objects, in order of their search ordering

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

getSource

public byte[] getSource(java.lang.String sourceName)
                 throws ExtensionModuleNotFoundException,
                        MetaMatrixComponentException

Retrieves an extension module in byte[] form

Parameters:

sourceName - name (e.g. filename) of extension module

Returns:

actual contents of module in byte[] array form

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null

setSource

public ExtensionModuleDescriptor setSource(java.lang.String principalName,
                                           java.lang.String sourceName,
                                           byte[] source)
                                    throws ExtensionModuleNotFoundException,
                                           MetaMatrixComponentException

Updates the indicated extension module. All caches (of Class objects) are cleared.

Parameters:

principalName - name of principal requesting this addition

sourceName - name (e.g. filename) of extension module

source - actual contents of module

Returns:

ExtensionModuleDescriptor describing the newly-updated extension module

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null or invalid

setSourceName

public ExtensionModuleDescriptor setSourceName(java.lang.String principalName,
                                               java.lang.String sourceName,
                                               java.lang.String newName)
                                        throws ExtensionModuleNotFoundException,
                                               MetaMatrixComponentException

Updates the indicated extension module's source name

Parameters:

principalName - name of principal requesting this addition

sourceName - name (e.g. filename) of extension module

newName - new name for the module

Returns:

ExtensionModuleDescriptor describing the newly-updated extension module

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null or invalid

setSourceDescription

public ExtensionModuleDescriptor setSourceDescription(java.lang.String principalName,
                                                      java.lang.String sourceName,
                                                      java.lang.String description)
                                               throws ExtensionModuleNotFoundException,
                                                      MetaMatrixComponentException

Updates the indicated extension module's description

Parameters:

principalName - name of principal requesting this addition

sourceName - name (e.g. filename) of extension module

description - (optional) description of the extension module. null can be passed in to indicate no description.

Returns:

ExtensionModuleDescriptor describing the newly-updated extension module

Throws:

ExtensionModuleNotFoundException - if no extension module with name sourceName can be found

MetaMatrixComponentException - indicating a non-business-related exception (such as a communication exception)

ExtensionModuleRuntimeException - if this object wasn't initialized properly

java.lang.IllegalArgumentException - if any required parameters are null or invalid

init

protected void init(java.util.Properties env)

Initializes this object, given the necessary Properties.

Parameters:

env - the necessary Properties to initialize this class, see ExtensionModulePropertyNames

Throws:

ManagedConnectionException

getChecksum

public static long getChecksum(byte[] data)

Retrieves a checksum value for the contents of an extension module

getReadTransaction

public ExtensionModuleTransaction getReadTransaction()
                                              throws ManagedConnectionException

Throws:

ManagedConnectionException

getWriteTransaction

public ExtensionModuleTransaction getWriteTransaction()
                                               throws ManagedConnectionException

Throws:

ManagedConnectionException

notifyFileChanged

public void notifyFileChanged()

Notifies listeners when JDBCNames.ExtensionFilesTable.ColumnName.FILE_TYPE has changed.

Since:

4.2