com.ibm.di.config.interfaces
Class MetamergeConfigFactory

java.lang.Object
  com.ibm.di.config.interfaces.MetamergeConfigFactory

public class MetamergeConfigFactory
extends java.lang.Object

The MetamergeConfigFactory class provides a number of static methods for use by applications to obtain MetamergeConfig objects. Each MetamergeConfig object is registered in the global namespace with a unique name. This namespace is used by MetamergeConfig objects when they refer to object in other configurations. The resolving of names is also provided by this class. Typically, a MetamergeConfig object will always call the isNameLocal() method to determine whether a name is handled by itself or another MetamergeConfig object. In the latter case a subsequent call to the lookup() method will cause this class to resolve, and potentially load, the MetamergeConfig object that is able to access the named object.

Getting MetamergeConfig Objects

An application should use either getFileInstance(Object) or getInstance(Hashtable) to obtain a MetamergeConfig object. The first variant is a convenience method that calls getInstance(Hashtable) by setting key/value pairs in the hashtable. The following keywords are reserved:

Name	Description
javax.naming.Context.PROVIDER_URL	The URL the driver uses to locate the configuration store
MetamergeConfigFactory.MC_DRIVER	The class name for the MetamergeConfig implementation
MetamergeConfigFactory.MC_CREATE	Specifies wether the driver should create the endpoint if it does not exist
MetamergeConfigFactory.MC_PARSER	The class name for the parser (if the driver needs one)
MetamergeConfigFactory.MC_DEBUG	true/false to set the debug flag in the driver

Names

All applications and MetamergeConfig implementations should use the parseName() method to convert a name to a javax.naming.Name instance. The name syntax used by MetamergeConfigFactory and MetamergeConfig objects are words separated by a slash (/). An example would be AssemblyLines/MyAL which would point to an object called MyAL in a folder named AssemblyLines. To facilitate references to objects in other configuration stores a namespace ID can also be part of a name. If the first component in a Name ends with a colon (:) it is considered to be a namespace reference. The following name system:/Connectors/ibmdi.LDAP refers to /Connectors/ibmdi.LDAP in the MetamergeConfig object registered as system in this class. The words system and internal are reserved for use by IBM DI.

Resolving Names

When a MetamergeConfig object calls MetamergeConfigFactory.lookup() with a non-local reference it will first search the global namespace for the named MetamergeConfig object. If no such object exists, this class will look in the caller MetamergeConfig's namespace folder for a namespace that matches the requested name. If a namespace reference is found in the caller's namespace folder, it is loaded and registered in the global namespace. The name registered in the global namespace is the File/URL for the loaded MetamergeConfig and not the requested namespace itself.

For example, if A calls lookup using ext:Properties as name and A also has a namespace (e.g. external reference) named ext defined, this class will load the MetamergeConfig as defined by A's local namespace definition. Assuming A's namespace definition looks like this: ext ---> d:/mm/ext.cfg then that file will be loaded and registered in the global namespace as d:/mm/ext.cfg. The local namespace reference is only valid for the calling MetamergeConfig object but the MetamergeConfig object it refers to may be used by other MetamergeConfig objects as well. For example, B might have a similar configuration but instead of ext it may refer to d:/mm/ext.cfg as library. When B then calls lookup with library:Properties this class will then find out that the file (d:/mm/ext.cfg) is already loaded and that instance is reused for B as well. Thus, there are local namespace references and global namespace references. Local namespace references are valid only in the MetamergeConfig object they are defined whereas global namespace references (like system) are globally available.

Field Summary

static java.lang.String	ADAPTERS_NAMESPACE Reserved namespace ID for adapters
static java.lang.String	DEFAULT_DRIVER This is the default driver class if none is discovered/specified.
static Log	logger This is the Log object used by this class and other configuration drivers.
static java.lang.String	MC_CREATE Driver parameter - Specify "true" or "false" to tell the driver whether a configuration URL should be created
static java.lang.String	MC_DEBUG Driver parameter - Specify "true" or "false" to set the debug mode option for the driver
static java.lang.String	MC_DRIVER MetamergeConfigFactory parameter - Specifies the driver class name to use.
static java.lang.String	MC_ENCRYPT Force use of server public key encryption by setting this prop to "true".
static java.lang.String	MC_NAMESPACE The namespace, which a given MetamergeConfig object represents.
static java.lang.String	MC_NO_DEFAULT_FOLDERS Used to avoid creating default folders.
static java.lang.String	MC_PARSER Driver parameter - If driver needs a parser this parameter specifies the class to use
static java.lang.String	MC_URL MetamergeConfigFactory parameter - Specifies the URL
static java.lang.String	STDFORMS_NAMESPACE Reserved namespace ID for standard forms etc ...
static java.lang.String	SYSTEM_NAMESPACE Reserved namespace ID for installed components etc ...

Constructor Summary

MetamergeConfigFactory()

Method Summary

static void	addNamespaceListener(java.awt.event.ActionListener listener) Adds listener to the list of object to notify when namespaces are added/removed
static java.lang.String	addPackage(java.lang.String path) Adds a package to the packages namespace.
static java.util.List<java.lang.String>	addPackages(java.util.List<java.lang.String> packages) Adds a list of packages to the packages namespace.
static boolean	canRemoveNamespace(java.lang.String namedURL)
static void	copy(BaseConfiguration input, MetamergeConfig dest, javax.naming.Name destName) Recursively copy input configuration to another MetamergeConfig object
static void	copy(BaseConfiguration input, MetamergeConfig dest, javax.naming.Name destName, boolean overwrite) Recursively copy input configuration to another MetamergeConfig object
static void	copyFolder(MetamergeFolder folder, MetamergeConfig dest, javax.naming.Name destName) Recursively copies a folder to another MetamergeConfig object.
static void	copyFolder(MetamergeFolder folder, MetamergeConfig dest, javax.naming.Name destName, boolean overwrite) Recursively copies a folder to another MetamergeConfig object.
static void	copyObject(BaseConfiguration source, BaseConfiguration dest) Recursively copies an object to another MetamergeConfig object.
static MetamergeConfig	createSysInstance(java.util.Vector<java.lang.String> paths) Gets an combined instance for a Vector of files.
static boolean	garbageCollect() Removes the MetamergeConfig objects from the global namespace if there are no more references to it.
static MetamergeConfig	getCFGFileInstance(java.lang.Object path) Gets an instance of the driver for old-style config files.
static MetamergeConfig	getCFGFileInstance(java.lang.Object path, java.lang.String password) Gets an instance of the driver for old-style config files
static MetamergeConfig	getFileInstance(java.lang.Object path) Returns an instance of a MetamergeConfig driver using path as parameter
static MetamergeConfig	getInstance(java.util.Hashtable env) Returns an instance of a MetamergeConfig driver using env as parameter
static MetamergeConfig	getLocalNamespace(MetamergeConfig referent, java.lang.Object name) Returns the MetamergeConfig associated with the provided namespace.
static java.lang.Object	getLocalNamespaceFor(MetamergeConfig referent, BaseConfiguration config) Returns the local namespace for a component.
static MetamergeConfig	getNamespace(java.lang.Object name) Returns the MetamergeConfig associated with the provided namespace.
static java.lang.Object	getNamespaceFor(BaseConfiguration config) Returns the namespace to which a configuration object belongs or null if the object does not belong to a registered namespace.
static java.lang.Object[]	getNamespaces() Returns a list of registered namespaces.
static java.util.Properties	getNameSyntax() Gets the javax.naming NameSyntax properties used in Metamerge configuration drivers.
static java.util.List<MetamergeConfig>	getPackages() Returns a list of packaged config files
static ResourceHash	getResHash()
static boolean	getUseConfigListeners()
static boolean	isNameLocal(MetamergeConfig mc, java.lang.Object name) Returns true if the name is local to the given MetamergeConfig.
static boolean	isStandardObject(java.lang.Object objname) Returns true if the object name represents a standard object in the configuration space.
static MetamergeConfig	loadNamespace(NamespaceConfig nc) Returns a MetamergeConfig object for the provided NamespaceConfig.
static MetamergeConfig	loadNamespace(java.lang.String url) Returns a MetamergeConfig object for the provided url.
static void	logmsg(java.lang.String msg) Convenience method to log a message to the system log.
static java.lang.Object	lookup(MetamergeConfig mc, java.lang.Object name) Performs a lookup in the global namespace for name.
static void	namespaceChanged(java.lang.String ns, MetamergeConfig mc, boolean added)
static javax.naming.Name	parseName(java.lang.Object name) This method parses a name which can either be an instance of javax.naming.Name or any object implementing the toString() method.
static void	registerNamespace(java.lang.Object name, MetamergeConfig mc) Registers a MetamergeConfig object in the global namespace.
static void	removeNamespace(java.lang.Object name) Returns the MetamergeConfig associated with the provided namespace.
static void	removeNamespaceListener(java.awt.event.ActionListener listener)
static boolean	removePackage(MetamergeConfig mc) Removes a package from the in-memory list of packages.
static MetamergeConfig	resolve(MetamergeConfig mc, javax.naming.Name name) Resolves a namespace reference into a Metamergeconfig object.
static void	setUseConfigListeners(boolean value) Enable/disable the use of configuration listeners in the JVM.
static void	unregisterNamespace(java.lang.Object ns) Puts a MetamergeConfig object onto the unloadPending stack and calls garbageCollect.
static void	verifyInheritanceChain(BaseConfiguration config, java.lang.Object inheritFrom) Verify that inheritance chain does not loop.

Methods inherited from class java.lang.Object

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

Field Detail

SYSTEM_NAMESPACE

public static final java.lang.String SYSTEM_NAMESPACE

Reserved namespace ID for installed components etc ...

See Also:

Constant Field Values

STDFORMS_NAMESPACE

public static final java.lang.String STDFORMS_NAMESPACE

Reserved namespace ID for standard forms etc ...

See Also:

Constant Field Values

ADAPTERS_NAMESPACE

public static final java.lang.String ADAPTERS_NAMESPACE

Reserved namespace ID for adapters

See Also:

Constant Field Values

MC_PARSER

public static final java.lang.String MC_PARSER

Driver parameter - If driver needs a parser this parameter specifies the class to use

See Also:

Constant Field Values

MC_DEBUG

public static final java.lang.String MC_DEBUG

Driver parameter - Specify "true" or "false" to set the debug mode option for the driver

See Also:

Constant Field Values

MC_CREATE

public static final java.lang.String MC_CREATE

Driver parameter - Specify "true" or "false" to tell the driver whether a configuration URL should be created

See Also:

Constant Field Values

MC_DRIVER

public static final java.lang.String MC_DRIVER

MetamergeConfigFactory parameter - Specifies the driver class name to use.

See Also:

Constant Field Values

MC_URL

public static final java.lang.String MC_URL

MetamergeConfigFactory parameter - Specifies the URL

See Also:

Constant Field Values

MC_ENCRYPT

public static final java.lang.String MC_ENCRYPT

Force use of server public key encryption by setting this prop to "true". Force no encryption by setting the prop to "false". If this prop is neither "true" nor "false", the default behavior is to use encryption only when the server is running in secure mode.

See Also:

Constant Field Values

MC_NAMESPACE

public static final java.lang.String MC_NAMESPACE

The namespace, which a given MetamergeConfig object represents. If this parameter is not specified, the URL will be used as namespace.

See Also:

Constant Field Values

MC_NO_DEFAULT_FOLDERS

public static final java.lang.String MC_NO_DEFAULT_FOLDERS

Used to avoid creating default folders. For internal use.

See Also:

Constant Field Values

DEFAULT_DRIVER

public static final java.lang.String DEFAULT_DRIVER

This is the default driver class if none is discovered/specified.

See Also:

Constant Field Values

logger

public static final Log logger

This is the Log object used by this class and other configuration drivers.

Constructor Detail

MetamergeConfigFactory

public MetamergeConfigFactory()

Method Detail

getResHash

public static ResourceHash getResHash()

getNameSyntax

public static java.util.Properties getNameSyntax()

Gets the javax.naming NameSyntax properties used in Metamerge configuration drivers.

Returns:

The nameSyntax value

getFileInstance

public static MetamergeConfig getFileInstance(java.lang.Object path)
                                       throws java.lang.Exception

Returns an instance of a MetamergeConfig driver using path as parameter

Parameters:

path - input file/parh/url ....

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

getInstance

public static MetamergeConfig getInstance(java.util.Hashtable env)
                                   throws java.lang.Exception

Returns an instance of a MetamergeConfig driver using env as parameter

Parameters:

env - Table of parameters

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

getCFGFileInstance

public static MetamergeConfig getCFGFileInstance(java.lang.Object path)
                                          throws java.lang.Exception

Gets an instance of the driver for old-style config files.

Parameters:

path - CFG file/url name

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

getCFGFileInstance

public static MetamergeConfig getCFGFileInstance(java.lang.Object path,
                                                 java.lang.String password)
                                          throws java.lang.Exception

Gets an instance of the driver for old-style config files

Parameters:

path - CFG file/url

password - Password to access path

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

createSysInstance

public static MetamergeConfig createSysInstance(java.util.Vector<java.lang.String> paths)

Gets an combined instance for a Vector of files.

Parameters:

paths - A Vector containing Strings, each representing an URL.

Returns:

The combined MetamergeConfig object

getNamespace

public static MetamergeConfig getNamespace(java.lang.Object name)

Returns the MetamergeConfig associated with the provided namespace.

Parameters:

name - The namespace name

Returns:

The MetamergeConfig object or null if name was not found

removeNamespace

public static void removeNamespace(java.lang.Object name)

Returns the MetamergeConfig associated with the provided namespace.

Parameters:

name - The namespace name

getLocalNamespace

public static MetamergeConfig getLocalNamespace(MetamergeConfig referent,
                                                java.lang.Object name)

Returns the MetamergeConfig associated with the provided namespace. If not found, searches the referent's namespace table for a match.

Parameters:

name - The namespace name

Returns:

The MetamergeConfig object or null if name was not found

getNamespaceFor

public static java.lang.Object getNamespaceFor(BaseConfiguration config)

Returns the namespace to which a configuration object belongs or null if the object does not belong to a registered namespace.

Parameters:

config - Configuration object obtained from a MetamergeConfig object

Returns:

The namespace (a String) or null if not found

getLocalNamespaceFor

public static java.lang.Object getLocalNamespaceFor(MetamergeConfig referent,
                                                    BaseConfiguration config)

Returns the local namespace for a component. This method searches the referent object that owns the configuration object by looking at the referent's local namespace definitions. The returned namespace is valid only in the context of the referent.

Parameters:

referent - The MetamergeConfig object to search for local namespaces

config - The configuration object

Returns:

The local namespace value

getNamespaces

public static java.lang.Object[] getNamespaces()

Returns a list of registered namespaces.

Returns:

The namespace values

isNameLocal

public static boolean isNameLocal(MetamergeConfig mc,
                                  java.lang.Object name)
                           throws java.lang.Exception

Returns true if the name is local to the given MetamergeConfig. If not, the name refers to another MetamergeConfig which can be obtained through the lookup() method.

Parameters:

mc - A MetamergeConfig object

name - The name of the MetamergeConfig object

Returns:

true if name is local to mc

Throws:

java.lang.Exception

parseName

public static javax.naming.Name parseName(java.lang.Object name)
                                   throws javax.naming.InvalidNameException

This method parses a name which can either be an instance of javax.naming.Name or any object implementing the toString() method. In case of a Name, the method returns a clone of name. In case of a string, the string is parsed according to the internal configuration of names. If name is null, a new javax.naming.Name object is returned.

Parameters:

name - null, javax.namgin.Name or an object having a toString() method

Returns:

A Name instance representing the name parameter

Throws:

javax.naming.InvalidNameException

registerNamespace

public static void registerNamespace(java.lang.Object name,
                                     MetamergeConfig mc)

Registers a MetamergeConfig object in the global namespace.

Parameters:

name - Unique name

mc - MetamergeConfig object

unregisterNamespace

public static void unregisterNamespace(java.lang.Object ns)

Puts a MetamergeConfig object onto the unloadPending stack and calls garbageCollect.

Parameters:

ns -

garbageCollect

public static boolean garbageCollect()

Removes the MetamergeConfig objects from the global namespace if there are no more references to it.

canRemoveNamespace

public static boolean canRemoveNamespace(java.lang.String namedURL)

loadNamespace

public static MetamergeConfig loadNamespace(java.lang.String url)
                                     throws java.lang.Exception

Returns a MetamergeConfig object for the provided url. If the Url needs to be loaded it also registers the url/config in the global namespace table.

Parameters:

url - URL to load/locate

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

loadNamespace

public static MetamergeConfig loadNamespace(NamespaceConfig nc)
                                     throws java.lang.Exception

Returns a MetamergeConfig object for the provided NamespaceConfig. If loading is needed, also register the url/config in the global namespace table.

Parameters:

nc - NamespaceConfig to load/locate

Returns:

MetamergeConfig object

Throws:

java.lang.Exception

resolve

public static MetamergeConfig resolve(MetamergeConfig mc,
                                      javax.naming.Name name)
                               throws java.lang.Exception

Resolves a namespace reference into a Metamergeconfig object. This method will try to create a new instance of a MetamergeConfig driver for any unresolved URLs.

Parameters:

mc - The MetamergeConfig object requesting name

name - The name to resolve

Returns:

The MetamergeConfig object owning name

Throws:

java.lang.Exception

lookup

public static java.lang.Object lookup(MetamergeConfig mc,
                                      java.lang.Object name)
                               throws java.lang.Exception

Performs a lookup in the global namespace for name. The name parameter is resolved using resolve and the local part of name is then searched for in the metamergeconfig returned by resolve. This method is used by MetamergeConfig drivers when it encounters a name that is not local to itself.

Parameters:

mc - Calling MetamergeConfig

name - The name to lookup

Returns:

The configuration object returned by the resolved MetamergeConfig object

Throws:

java.lang.Exception

copy

public static void copy(BaseConfiguration input,
                        MetamergeConfig dest,
                        javax.naming.Name destName)
                 throws java.lang.Exception

Recursively copy input configuration to another MetamergeConfig object

Parameters:

input - Object to copy

dest - MetamergeConfig object to receive copy

destName - Name of copied object in dest config

Throws:

java.lang.Exception

copy

public static void copy(BaseConfiguration input,
                        MetamergeConfig dest,
                        javax.naming.Name destName,
                        boolean overwrite)
                 throws java.lang.Exception

Recursively copy input configuration to another MetamergeConfig object

Parameters:

input - Object to copy

dest - MetamergeConfig object to receive copy

destName - Name of copied object in dest config

overwrite - flag indicating whether to overwrite in case of copying folder

Throws:

java.lang.Exception

copyFolder

public static void copyFolder(MetamergeFolder folder,
                              MetamergeConfig dest,
                              javax.naming.Name destName)
                       throws java.lang.Exception

Recursively copies a folder to another MetamergeConfig object. Existing objects are overwritten.

Parameters:

folder - The folder to copy

dest - The config that receives the copy

destName - The name the copy gets

Throws:

java.lang.Exception

copyFolder

public static void copyFolder(MetamergeFolder folder,
                              MetamergeConfig dest,
                              javax.naming.Name destName,
                              boolean overwrite)
                       throws java.lang.Exception

Recursively copies a folder to another MetamergeConfig object. Existing objects are overwritten.

Parameters:

folder - The folder to copy

dest - The config that receives the copy

destName - The name the copy gets

overwrite - flag indicating whether to overwrite

Throws:

java.lang.Exception

copyObject

public static void copyObject(BaseConfiguration source,
                              BaseConfiguration dest)

Recursively copies an object to another MetamergeConfig object. Existing objects are overwritten.

Parameters:

source - The object to copy

dest - The config that receives the copy

logmsg

public static void logmsg(java.lang.String msg)

Convenience method to log a message to the system log.

Parameters:

msg - The message to log

verifyInheritanceChain

public static void verifyInheritanceChain(BaseConfiguration config,
                                          java.lang.Object inheritFrom)
                                   throws java.lang.Exception

Verify that inheritance chain does not loop.

Throws:

java.lang.Exception

isStandardObject

public static boolean isStandardObject(java.lang.Object objname)

Returns true if the object name represents a standard object in the configuration space.

addPackages

public static java.util.List<java.lang.String> addPackages(java.util.List<java.lang.String> packages)

Adds a list of packages to the packages namespace. Returns the packageid or exception object for each package.

Parameters:

packages - List of absolute paths

removePackage

public static boolean removePackage(MetamergeConfig mc)
                             throws java.lang.Exception

Removes a package from the in-memory list of packages. Also, the auto-generated adapters are removed from the adapters namespace.

Parameters:

mc - The package to remove

Returns:

true the package was removed, false if the config is not a package

Throws:

java.lang.Exception

addPackage

public static java.lang.String addPackage(java.lang.String path)
                                   throws java.lang.Exception

Adds a package to the packages namespace. Returns the package ID on success.

Parameters:

path - The absolute path of the file

Throws:

java.lang.Exception

getPackages

public static java.util.List<MetamergeConfig> getPackages()
                                                   throws java.lang.Exception

Returns a list of packaged config files

Throws:

java.lang.Exception

addNamespaceListener

public static void addNamespaceListener(java.awt.event.ActionListener listener)

Adds listener to the list of object to notify when namespaces are added/removed

removeNamespaceListener

public static void removeNamespaceListener(java.awt.event.ActionListener listener)

namespaceChanged

public static void namespaceChanged(java.lang.String ns,
                                    MetamergeConfig mc,
                                    boolean added)

setUseConfigListeners

public static void setUseConfigListeners(boolean value)

Enable/disable the use of configuration listeners in the JVM. This is an optimization to turn off listeners which the CE uses, but the Server does not need.

Parameters:

value - False to disable configuration listeners.

Since:

7.0

getUseConfigListeners

public static boolean getUseConfigListeners()

Returns:

Whether configuration listeners are enabled or disabled in this JVM.

Since:

7.0

See Also:

setUseConfigListeners(boolean)