com.metamatrix.common.config.util
Interface ConfigurationImportExportUtility

All Known Implementing Classes:

XMLConfigurationImportExportUtility

public interface ConfigurationImportExportUtility

This interface can be used to import and export configuration objects to/from InputStream instances (usually representing a File of some sort).

Method Summary

void	exportConfiguration(java.io.OutputStream stream, java.util.Collection<?> configurationObjects, java.util.Properties props) This method will write to the passed in InputStream instance a complete representation of the Collection of Configuration objects that are passed into it.
void	exportConnector(java.io.OutputStream stream, ComponentType type, java.util.Properties props) This method will generally be used to create a file representation of a Connector.
void	exportConnectorArchive(java.io.OutputStream stream, ConnectorArchive archive, java.util.Properties properties) Export the given archive into zip format and write to the the stream provided
void	exportConnectorBinding(java.io.OutputStream stream, ConnectorBinding defn, ComponentType type, java.util.Properties props) This method will generally be used to create a file representation of a Connector Binding.
void	exportConnectorBindings(java.io.OutputStream stream, ConnectorBinding[] bindings, ComponentType[] types, java.util.Properties props) This method will generally be used to create a file representation of one or more Connector Bindings.
ComponentType	importComponentType(java.io.InputStream stream, ConfigurationObjectEditor editor, java.lang.String newName) This method will be used to import a ComponentType Object from given a InputStream instance.
java.util.Collection<?>	importComponentTypes(java.io.InputStream stream, ConfigurationObjectEditor editor) This method will be used to import 1 or more a ComponentType Objects.
java.util.Collection<?>	importConfigurationObjects(java.io.InputStream stream, ConfigurationObjectEditor editor, java.lang.String newName) This method will be used to import a Collection of Configuration objects given an InputStream.
ConnectorArchive	importConnectorArchive(java.io.InputStream stream, ConfigurationObjectEditor editor) Import a connector archive (connector type and extension modules) from the given stream of zip file.
ConnectorBinding	importConnectorBinding(java.io.InputStream stream, ConfigurationObjectEditor editor, java.lang.String newName) This method will be used to import a Connector Binding Object given a ImputStream.
java.lang.Object[]	importConnectorBindingAndType(java.io.InputStream stream, ConfigurationObjectEditor editor, java.lang.String[] newName) This method will be used to import a Connector Binding and its related Component Type at the same time from the given ImputStream.
java.util.Collection<ConnectorBinding>	importConnectorBindings(java.io.InputStream stream, ConfigurationObjectEditor editor) This method will be used to import a group of Connector Bindings Objects given a ImputStream.

Method Detail

exportConfiguration

void exportConfiguration(java.io.OutputStream stream,
                         java.util.Collection<?> configurationObjects,
                         java.util.Properties props)
                         throws java.io.IOException,
                                ConfigObjectsNotResolvableException

This method will write to the passed in InputStream instance a complete representation of the Collection of Configuration objects that are passed into it. The failsafe way to build this Collection of objects is to call the getConfigurationAndDependents() method on the AdminAPI of the MetaMatrix Server. This method will retreive the Configuration and all of its dependent objects in their entirety.

In order to export an entire Configuration, the Collection passed into this method should have all of the following object references to be able to resolve the relationships between all objects referenced by a Configuration object.

 1. Configuration object
 2. all ComponentTypes that ComponentObjects reference in the
 Configuration object including the Configuration object's Component Type.
 (this includes ProductTypes) 
 3. all ProductTypes that ProductServiceConfig objects reference in the
 Configuration object
 4. all Host objects that are referenced by DeployedComponents in the
 Configuration object
 

All of the above object references must be in the collection passed into this method.

The properties object that is passed into this method may contain the following properties as defined by the ConfigurationPropertyNames class. These properties will define the values for the header of the output of this method.

 ConfigurationPropertyNames.APPLICATION_CREATED_BY
 ConfigurationPropertyNames.APPLICATION_VERSION_CREATED_BY
 ConfigurationPropertyNames.USER_CREATED_BY
 

 
Any of these properties that are not included in the properties object
 will not be included in the header Element.


Parameters:
stream - the output stream to write the Configuration Object
 representation to
configurationObjects - a Collection of configuration objects that
 represents an entire logical Configuration.
props - the properties object that contains the values for the Header
Throws:
java.io.IOException - if there is an error writing to the InputStream
ConfigObjectsNotResolvableException - if there are references
 to configuration objects not included in the Collection of configuration objects
 that cannot be resolved to other configuration objects in the passed in 
 Collection

importConfigurationObjects

java.util.Collection<?> importConfigurationObjects(java.io.InputStream stream,
                                                   ConfigurationObjectEditor editor,
                                                   java.lang.String newName)
                                                   throws java.io.IOException,
                                                          ConfigObjectsNotResolvableException,
                                                          InvalidConfigurationElementException

This method will be used to import a Collection of Configuration objects given an InputStream. If the InputStream resource does not contain enough data to recombine all of the configuration objects in the Input Stream, then a ConfigurationObjectsNotResolvableException will be thrown.

This method also allows you to rename the imported Configuration object possibly to avoid name conflicts with other Configurations already in the server.

If the name parameter submitted is null, the name of the configuration object as it exists in the InputStream will be used as the name of the resulting Configuration object in the returned collection of configuration objects.

Parameters:

editor - the ConfigurationObjectEditor to use to create the Configuration objects in the InputStream resource.

stream - the input stream to read the configuration object representations from

name - the name for the Configuration object to be created. Can be null if the name specified in the input stream is to be used.

Returns:

the configuration objects that were represented as data in the InputStream resource

Throws:

ConfigObjectsNotResolvableException - if the data representing the Configuration to be imported is incomplete.

java.io.IOException - if there is an error reading from the InputStream

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the InputStream resource, usually some type of formatting problem.

importComponentType

ComponentType importComponentType(java.io.InputStream stream,
                                  ConfigurationObjectEditor editor,
                                  java.lang.String newName)
                                  throws java.io.IOException,
                                         InvalidConfigurationElementException

This method will be used to import a ComponentType Object from given a InputStream instance.

This method also allows you to rename the imported ComponentType object possibly to avoid name conflicts with other objects already in the server.

If the name parameter submitted is null, the name of the configuration object as it exists in the InputStream will be used.

Parameters:

editor - the ConfigurationObjectEditor to use to create the Configuration objects in the InputStream resource.

stream - the input stream to read the configuration object representation from

name - the name for the ComponentType object to be created.

Returns:

the configuration object that was represented as data in the InputStream resource

Throws:

java.io.IOException - if there is an error reading from the InputStream

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the InputStream resource, usually some type of formatting problem.

importComponentTypes

java.util.Collection<?> importComponentTypes(java.io.InputStream stream,
                                             ConfigurationObjectEditor editor)
                                             throws java.io.IOException,
                                                    InvalidConfigurationElementException

This method will be used to import 1 or more a ComponentType Objects.

Parameters:

editor - the ConfigurationObjectEditor to use to create the Configuration objects.

stream - the input stream to read the configuration object representation from

Returns:

Collection of objects of type ComponentType

Throws:

java.io.IOException - if there is an error reading from the DirectoryEntry

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the DirectoryEntry resource, usually some type of formatting problem.

exportConnector

void exportConnector(java.io.OutputStream stream,
                     ComponentType type,
                     java.util.Properties props)
                     throws java.io.IOException

This method will generally be used to create a file representation of a Connector. It will write to the InputStream the representation of the ComponentType that is passed in.

We have made the assumption here that the Super and Parent Component types of Connector ComponentType objects will already be loaded in the configuration of the server. Thus we do not require that the Super and Parent ComponentType be written to the resource. This will always be the case as of the 2.0 server.

The properties object that is passed into this method may contain the following properties as defined by the ConfigurationPropertyNames class.

 ConfigurationPropertyNames.APPLICATION_CREATED_BY
 ConfigurationPropertyNames.APPLICATION_VERSION_CREATED_BY
 ConfigurationPropertyNames.USER_CREATED_BY
 

 
Any of these properties that are not included in the properties object
 will not be included in the header Element.


Parameters:
stream - the output stream to write the Configuration Object
 representation to
type - the ComponentType to be written to the InputStream
props - the properties object that contains the values for the Header
Throws:
java.io.IOException - if there is an error writing to the InputStream

exportConnectorBinding

void exportConnectorBinding(java.io.OutputStream stream,
                            ConnectorBinding defn,
                            ComponentType type,
                            java.util.Properties props)
                            throws java.io.IOException,
                                   ConfigObjectsNotResolvableException

This method will generally be used to create a file representation of a Connector Binding. It will write to the InputStream the representation of the ServiceComponentDefn object that is passed in.

Multiple ServiceComponentDefns can be written to the same InputStream by passing the same InputStream instance to this method multiple times.

The properties object that is passed into this method may contain the following properties as defined by the ConfigurationPropertyNames class.

 ConfigurationPropertyNames.APPLICATION_CREATED_BY
 ConfigurationPropertyNames.APPLICATION_VERSION_CREATED_BY
 ConfigurationPropertyNames.USER_CREATED_BY
 

 
Any of these properties that are not included in the properties object
 will not be included in the header Element.


Parameters:
stream - the output stream to write the Configuration Object
 representation to
type - the ComponentType of the ServiceComponentDefn to be written
 to the InputStream resource.
defn - the ServiceComponentDefn instance to write to the InputStream.
props - the properties object that contains the values for the Header
Throws:
java.io.IOException - if there is an error writing to the InputStream
ConfigObjectsNotResolvableException - if the passed in
 ComponentType is not the type referenced by the passed in ServiceComponentDefn.

exportConnectorBindings

void exportConnectorBindings(java.io.OutputStream stream,
                             ConnectorBinding[] bindings,
                             ComponentType[] types,
                             java.util.Properties props)
                             throws java.io.IOException,
                                    ConfigObjectsNotResolvableException

This method will generally be used to create a file representation of one or more Connector Bindings. It will write to the InputStream the representation of the ConnectorBind object that is passed in. The bindings and types are a match pair when resolving is done on the binding. Therefore, these should be matching order when passed in.

The properties object that is passed into this method may contain the following properties as defined by the ConfigurationPropertyNames class.

 ConfigurationPropertyNames.APPLICATION_CREATED_BY
 ConfigurationPropertyNames.APPLICATION_VERSION_CREATED_BY
 ConfigurationPropertyNames.USER_CREATED_BY
 

 
Any of these properties that are not included in the properties object
 will not be included in the header Element.


Parameters:
stream - the output stream to write the Configuration Object
 representation to
bindings - is an array of type ConnectorBinding to be written
 to the InputStream resource.
types - is an array of type ComponentType to be written
 to the InputStream resource.
props - the properties object that contains the values for the Header
Throws:
java.io.IOException - if there is an error writing to the InputStream
ConfigObjectsNotResolvableException - if the passed in
 ComponentType is not the type referenced by the passed in ServiceComponentDefn.

importConnectorBindings

java.util.Collection<ConnectorBinding> importConnectorBindings(java.io.InputStream stream,
                                                               ConfigurationObjectEditor editor)
                                                               throws java.io.IOException,
                                                                      ConfigObjectsNotResolvableException,
                                                                      InvalidConfigurationElementException

This method will be used to import a group of Connector Bindings Objects given a ImputStream. If the ImputStream resource does not contain enough data to recombine a complete Connector, then a ConfigurationObjectsNotResolvableException will be thrown.

This method returns a collection of objects which represent one or more Connector Bindings.

The user of this method must either commit the Connector ComponentType of this Connector Binding's or make sure that it already exists in the server configuration database before attempting to commit the Connector Binding ServiceComponentDefn object. This is because every Connector Binding ServiceComponentDefn has a reference to a corresponding Connector ComponentType

Parameters:

stream - the input stream to read the configuration object representation from *

editor - the ConfigurationObjectEditor to use to create the Configuration objects in the InputStream resource.

Returns:

the configuration objects that are represented as data in the InputStream resource. see javadoc heading for details.

Throws:

ConfigObjectsNotResolvableException - if the ServiceComponentDefn does not have a reference to a ComponentType object for which there is data to recombine in the InputStream resource.

java.io.IOException - if there is an error reading from the InputStream

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the InputStream resource, usually some type of formatting problem.

importConnectorBinding

ConnectorBinding importConnectorBinding(java.io.InputStream stream,
                                        ConfigurationObjectEditor editor,
                                        java.lang.String newName)
                                        throws java.io.IOException,
                                               ConfigObjectsNotResolvableException,
                                               InvalidConfigurationElementException

This method will be used to import a Connector Binding Object given a ImputStream. If the ImputStream resource does not contain enough data to recombine a complete Connector, then a ConfigurationObjectsNotResolvableException will be thrown.

This method returns an object which represent one Connector Bindings.

The user of this method must either commit the Connector ComponentType of this Connector Binding or make sure that it already exists in the server configuration database before attempting to commit the Connector Binding ServiceComponentDefn object. This is because every Connector Binding ServiceComponentDefn has a reference to a corresponding Connector ComponentType

Parameters:

stream - the input stream to read the configuration object representation from

editor - the ConfigurationObjectEditor to use to create the Configuration object in the InputStream resource.

Returns:

the configuration object that represent the data in the InputStream resource. see javadoc heading for details.

Throws:

ConfigObjectsNotResolvableException - if the ServiceComponentDefn does not have a reference to a ComponentType object for which there is data to recombine in the InputStream resource.

java.io.IOException - if there is an error reading from the InputStream

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the InputStream resource, usually some type of formatting problem.

importConnectorBindingAndType

java.lang.Object[] importConnectorBindingAndType(java.io.InputStream stream,
                                                 ConfigurationObjectEditor editor,
                                                 java.lang.String[] newName)
                                                 throws java.io.IOException,
                                                        ConfigObjectsNotResolvableException,
                                                        InvalidConfigurationElementException

This method will be used to import a Connector Binding and its related Component Type at the same time from the given ImputStream. If the ImputStream resource does not contain enough data to recombine a complete Connector, then a ConfigurationObjectsNotResolvableException will be thrown.

This method also allows you to rename the imported Connector object possibly to avoid name conflicts with other objects already in the server.

If the name parameter submitted is null, the name of the confiuguration object as it exists in the InputStream will be used.

This method returns an array of objects which represent a Connector Binding ServiceComponentDefn and its corresponding Connector ComponentType. The index of each is defined by the following static variables:

 ConfigurationImportExportUtility.COMPONENT_TYPE_INDEX
 ConfigurationImportExportUtility.SERVICE_COMPONENT_DEFN_INDEX
 

These array indices are also used to override the Connector ComponentType name and Connector Binding ServiceComponentDefn name with the passed in name[] String array. If either or both of these String names are null, the name of the returned configuration object will be as it exists in the InputStream resource.

The user of this method must either commit the Connector ComponentType of this Connector Binding's ServiceComponentDefn or make sure that it already exists in the server configuration database before attempting to commit the Connector Binding ServiceComponentDefn object. This is because every Connector Binding ServiceComponentDefn has a reference to a corresponding Connector ComponentType

Parameters:

editor - the ConfigurationObjectEditor to use to create the Configuration objects in the InputStream resource.

stream - the input stream to read the configuration object representation from

newNames - the name for the ServiceComponentDefn and ComponentType object to be created.

Returns:

the configuration objects that are represented as data in the InputStream resource. see javadoc heading for details.

Throws:

ConfigObjectsNotResolvableException - if the ServiceComponentDefn does not have a reference to a ComponentType object for which there is data to recombine in the InputStream resource.

java.io.IOException - if there is an error reading from the InputStream

InvalidConfigurationElementException - if there is a problem with the representation of the configuration element as it exists in the InputStream resource, usually some type of formatting problem.

importConnectorArchive

ConnectorArchive importConnectorArchive(java.io.InputStream stream,
                                        ConfigurationObjectEditor editor)
                                        throws java.io.IOException,
                                               InvalidConfigurationElementException

Import a connector archive (connector type and extension modules) from the given stream of zip file.

Parameters:

stream - - zip file stream

editor - - Configuration object to use

newName - the new name for the ConnectorType. If null, the name is derived from the file contents.

Returns:

- loaded ConnectorArchive

Throws:

java.io.IOException

InvalidConfigurationElementException

Since:

4.3.2

exportConnectorArchive

void exportConnectorArchive(java.io.OutputStream stream,
                            ConnectorArchive archive,
                            java.util.Properties properties)
                            throws java.io.IOException,
                                   ConfigObjectsNotResolvableException

Export the given archive into zip format and write to the the stream provided

Parameters:

stream - - stream to written into

archive - - archive to be exported

properties - the properties object that contains the values for the Header

Throws:

java.io.IOException

ConfigObjectsNotResolvableException

Since:

4.3.2