com.ibm.di.config.interfaces
Class MetamergeConfigFactory

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

public class MetamergeConfigFactory
extends 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 String ADAPTERS_NAMESPACE
          Reserved namespace ID for adapters
static 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 String MC_CONFIG_DIRECTORY
          Used to override the location returned by MetamergeConfig.getDirectory()
static String MC_CREATE
          Driver parameter - Specify "true" or "false" to tell the driver whether a configuration URL should be created
static String MC_DEBUG
          Driver parameter - Specify "true" or "false" to set the debug mode option for the driver
static String MC_DRIVER
          MetamergeConfigFactory parameter - Specifies the driver class name to use.
static String MC_ENCRYPT
          Force use of server public key encryption by setting this prop to "true".
static String MC_NAMESPACE
          The namespace, which a given MetamergeConfig object represents.
static String MC_NO_DEFAULT_FOLDERS
          Used to avoid creating default folders.
static String MC_PARSER
          Driver parameter - If driver needs a parser this parameter specifies the class to use
static String MC_URL
          MetamergeConfigFactory parameter - Specifies the URL
static String STDFORMS_NAMESPACE
          Reserved namespace ID for standard forms etc ...
static String SYSTEM_NAMESPACE
          Reserved namespace ID for installed components etc ...
 
Constructor Summary
MetamergeConfigFactory()
           
 
Method Summary
static void addNamespaceListener(ActionListener listener)
          Deprecated.  
static String addPackage(String path)
          Adds a package to the packages namespace.
static List<String> addPackages(List<String> packages)
          Adds a list of packages to the packages namespace.
static boolean canRemoveNamespace(String namedURL)
           
static void copy(BaseConfiguration input, MetamergeConfig dest, Name destName)
          Recursively copy input configuration to another MetamergeConfig object
static void copy(BaseConfiguration input, MetamergeConfig dest, Name destName, boolean overwrite)
          Recursively copy input configuration to another MetamergeConfig object
static void copyFolder(MetamergeFolder folder, MetamergeConfig dest, Name destName)
          Recursively copies a folder to another MetamergeConfig object.
static void copyFolder(MetamergeFolder folder, MetamergeConfig dest, 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(Vector<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(Object path)
          Gets an instance of the driver for old-style config files.
static MetamergeConfig getCFGFileInstance(Object path, String password)
          Gets an instance of the driver for old-style config files
static MetamergeConfig getFileInstance(Object path)
          Returns an instance of a MetamergeConfig driver using path as parameter
static MetamergeConfig getInstance(Hashtable env)
          Returns an instance of a MetamergeConfig driver using env as parameter
static MetamergeConfig getLocalNamespace(MetamergeConfig referent, Object name)
          Returns the MetamergeConfig associated with the provided namespace.
static Object getLocalNamespaceFor(MetamergeConfig referent, BaseConfiguration config)
          Returns the local namespace for a component.
static MetamergeConfig getNamespace(Object name)
          Returns the MetamergeConfig associated with the provided namespace.
static 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 Object[] getNamespaces()
          Returns a list of registered namespaces.
static Properties getNameSyntax()
          Gets the javax.naming NameSyntax properties used in Metamerge configuration drivers.
static List<MetamergeConfig> getPackages()
          Returns a list of packaged config files
static ResourceHash getResHash()
           
static boolean getUseConfigListeners()
           
static boolean isNameLocal(MetamergeConfig mc, Object name)
          Returns true if the name is local to the given MetamergeConfig.
static boolean isStandardObject(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(String url)
          Returns a MetamergeConfig object for the provided url.
static void logmsg(String msg)
          Convenience method to log a message to the system log.
static Object lookup(MetamergeConfig mc, Object name)
          Performs a lookup in the global namespace for name.
static void namespaceChanged(String ns, MetamergeConfig mc, boolean added)
          Deprecated.  
static Name parseName(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(Object name, MetamergeConfig mc)
          Registers a MetamergeConfig object in the global namespace.
static void removeNamespace(Object name)
          Returns the MetamergeConfig associated with the provided namespace.
static void removeNamespaceListener(ActionListener listener)
          Deprecated.  
static boolean removePackage(MetamergeConfig mc)
          Removes a package from the in-memory list of packages.
static MetamergeConfig resolve(MetamergeConfig mc, 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(Object ns)
          Puts a MetamergeConfig object onto the unloadPending stack and calls garbageCollect.
static void verifyInheritanceChain(BaseConfiguration config, 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 String SYSTEM_NAMESPACE
Reserved namespace ID for installed components etc ...

See Also:
Constant Field Values

STDFORMS_NAMESPACE

public static final String STDFORMS_NAMESPACE
Reserved namespace ID for standard forms etc ...

See Also:
Constant Field Values

ADAPTERS_NAMESPACE

public static final String ADAPTERS_NAMESPACE
Reserved namespace ID for adapters

See Also:
Constant Field Values

MC_PARSER

public static final 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 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 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 String MC_DRIVER
MetamergeConfigFactory parameter - Specifies the driver class name to use.

See Also:
Constant Field Values

MC_URL

public static final String MC_URL
MetamergeConfigFactory parameter - Specifies the URL

See Also:
Constant Field Values

MC_ENCRYPT

public static final 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 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 String MC_NO_DEFAULT_FOLDERS
Used to avoid creating default folders. For internal use.

See Also:
Constant Field Values

MC_CONFIG_DIRECTORY

public static final String MC_CONFIG_DIRECTORY
Used to override the location returned by MetamergeConfig.getDirectory()

See Also:
Constant Field Values

DEFAULT_DRIVER

public static final 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 Properties getNameSyntax()
Gets the javax.naming NameSyntax properties used in Metamerge configuration drivers.

Returns:
The nameSyntax value

getFileInstance

public static MetamergeConfig getFileInstance(Object path)
                                       throws Exception
Returns an instance of a MetamergeConfig driver using path as parameter

Parameters:
path - input file/parh/url ....
Returns:
MetamergeConfig object
Throws:
Exception

getInstance

public static MetamergeConfig getInstance(Hashtable env)
                                   throws Exception
Returns an instance of a MetamergeConfig driver using env as parameter

Parameters:
env - Table of parameters
Returns:
MetamergeConfig object
Throws:
Exception

getCFGFileInstance

public static MetamergeConfig getCFGFileInstance(Object path)
                                          throws Exception
Gets an instance of the driver for old-style config files.

Parameters:
path - CFG file/url name
Returns:
MetamergeConfig object
Throws:
Exception

getCFGFileInstance

public static MetamergeConfig getCFGFileInstance(Object path,
                                                 String password)
                                          throws 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:
Exception

createSysInstance

public static MetamergeConfig createSysInstance(Vector<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(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(Object name)
Returns the MetamergeConfig associated with the provided namespace.

Parameters:
name - The namespace name

getLocalNamespace

public static MetamergeConfig getLocalNamespace(MetamergeConfig referent,
                                                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 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 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 Object[] getNamespaces()
Returns a list of registered namespaces.

Returns:
The namespace values

isNameLocal

public static boolean isNameLocal(MetamergeConfig mc,
                                  Object name)
                           throws 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:
Exception

parseName

public static Name parseName(Object name)
                      throws 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:
InvalidNameException

registerNamespace

public static void registerNamespace(Object name,
                                     MetamergeConfig mc)
Registers a MetamergeConfig object in the global namespace.

Parameters:
name - Unique name
mc - MetamergeConfig object

unregisterNamespace

public static void unregisterNamespace(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(String namedURL)

loadNamespace

public static MetamergeConfig loadNamespace(String url)
                                     throws 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:
Exception

loadNamespace

public static MetamergeConfig loadNamespace(NamespaceConfig nc)
                                     throws 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:
Exception

resolve

public static MetamergeConfig resolve(MetamergeConfig mc,
                                      Name name)
                               throws 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:
Exception

lookup

public static Object lookup(MetamergeConfig mc,
                            Object name)
                     throws 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:
Exception

copy

public static void copy(BaseConfiguration input,
                        MetamergeConfig dest,
                        Name destName)
                 throws 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:
Exception

copy

public static void copy(BaseConfiguration input,
                        MetamergeConfig dest,
                        Name destName,
                        boolean overwrite)
                 throws 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:
Exception

copyFolder

public static void copyFolder(MetamergeFolder folder,
                              MetamergeConfig dest,
                              Name destName)
                       throws 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:
Exception

copyFolder

public static void copyFolder(MetamergeFolder folder,
                              MetamergeConfig dest,
                              Name destName,
                              boolean overwrite)
                       throws 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:
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(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,
                                          Object inheritFrom)
                                   throws Exception
Verify that inheritance chain does not loop.

Throws:
Exception

isStandardObject

public static boolean isStandardObject(Object objname)
Returns true if the object name represents a standard object in the configuration space.


addPackages

public static List<String> addPackages(List<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 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:
Exception

addPackage

public static String addPackage(String path)
                         throws Exception
Adds a package to the packages namespace. Returns the package ID on success.

Parameters:
path - The absolute path of the file
Throws:
Exception

getPackages

public static List<MetamergeConfig> getPackages()
                                         throws Exception
Returns a list of packaged config files

Throws:
Exception

addNamespaceListener

public static void addNamespaceListener(ActionListener listener)
Deprecated. 

This method does nothing.


removeNamespaceListener

public static void removeNamespaceListener(ActionListener listener)
Deprecated. 

This method does nothing.


namespaceChanged

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

This method does nothing.


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)