com.novell.nds.dirxml.shimhost
Class ShimConfig

java.lang.Object
  com.novell.nds.dirxml.shimhost.ShimConfig

All Implemented Interfaces:

ShimParams.ReferenceResolver, ShimHost.DriverPasswordCheck, ShimHost.StateListener, ConfigElement

public class ShimConfig
extends Object
implements ShimParams.ReferenceResolver, ShimHost.StateListener, ShimHost.DriverPasswordCheck, ConfigElement

Class encapsulating the DirXML shim configuration information necessary for running a shim.

The primary use of this class is the construction of initialization documents for the shim init() methods. However, it may also be useful as the back end for a configuration editor.

The ShimConfig class is designed to read and write all the configuration data from a single XML document. However, ShimConfig can also be used as an aggregator for configuration data from multiple sources. In either case, a ShimConfig instance can be used to construct XML documents to be used as parameters to shim init() methods.

Nested Class Summary

static class	ShimConfig.BadPasswordException
static class	ShimConfig.RemoteLoaderConfig Class encapsulating Remote Loader connection data.

Field Summary

static String	ATTR_SECURE Name for XML attribute 'secure'.
static String	ATTR_USE Name for XML attribute 'use'.
static String	TAG_APP_PASSWORD Tag name for XML element 'app-password'.
static String	TAG_APP_SCHEMA_DEF Tag name for XML element 'app-schema-def'.
static String	TAG_AUTH_CONTEXT Tag name for XML element 'auth-context'.
static String	TAG_AUTH_ID Tag name for XML element 'auth-id'.
static String	TAG_CLASS_NAME Tag name for XML element 'class-name'.
static String	TAG_CONNECTION_STRING Tag name for XML element 'connection-string'.
static String	TAG_DESIGNER_APP_ID Tag name for XML element 'designer-app-id'
static String	TAG_DIRXML_SCHEMA_DEF Tag name for XML element 'dirxml-schema-def'.
static String	TAG_DRIVER_DN Tag name for XML element 'driver-dn'.
static String	TAG_DRIVER_PASSWORD Tag name for XML element 'driver-password'.
static String	TAG_LOADER_PASSWORD Tag name for XML element 'loader-password'.
static String	TAG_PUBLISHER_DN Tag name for XML element 'publisher-dn'.
static String	TAG_REMOTE_LOADER Tag name for XML element 'remote-loader'.
static String	TAG_SECURE_HASH Tag name for XML element 'secure-hash'.
static String	TAG_SHIM_CONFIG Tag name for XML element 'shim-config'.
static String	TAG_SHIM_STATE Tag name for XML element 'shim-state'.
static String	TAG_SUBSCRIBER_DN Tag name for XML element 'subscriber-dn'.
static String	VAL_EMPTY_STRING ""
static String	VAL_FALSE "false"
static String	VAL_TRUE "true"

Constructor Summary

ShimConfig()
Construct a default, empty ShimConfig object.

ShimConfig(Node configParent)
Construct a ShimConfig object given parsed XML.

ShimConfig(ShimConfig source)
Construct a copy of an existing ShimConfig object.

ShimConfig(String configFilename)
Construct a ShimConfig object given a file name.

Method Summary

boolean	checkDriverPassword(String password) Method that will be called to handle a <check-password> command received on the Publisher channel.
Document	createGetSchemaInitDoc() Create an XML Document suitable for passing to DriverShim.getSchema().
Document[]	createInitDocs() Create three XML Documents suitable for passing to the DriverShim, SubscriptionShim, and PublicationShim init() methods.
Password	getAppPassword() Get the Password instance encapsulating the application password for the shim.
SchemaDef	getAppSchemaDef() Get the application SchemaDef instance associated with this instance.
String	getAuthContext() Return the "authorization context" from the configuration data.
String	getAuthID() Return the "authorization ID" from the configuration data.
String	getClassName() Return the class name from the configuration data.
char[]	getConfigPassword() Return the configuration password.
String	getDesignerAppID() Return the "Designer application ID" from the configuration data.
SchemaDef	getDirXMLSchemaDef() Get the DirXML SchemaDef instance associated with this instance.
String[]	getFakeDNs() Return an array of Strings containing the "fake" DN values in this configuration instance.
Filter	getFilter() Get the Filter instance associated with this instance.
GCDefinitions	getGCVs() Get the GCDefinitions instance associated with this instance.
NamedPasswords	getNamedPasswords() Get the NamedPasswords instance associated with this instance.
NameMap	getNameMap() Get the NameMap instance associated with this instance.
GCValue	getReferencedValue(String name) Supply a value given the name of the referenced item.
ShimConfig.RemoteLoaderConfig	getRemoteLoaderConfig() Get the RemoteLoaderConfig instance associated with this instance.
String	getShimClassName() Return the class name of the shim.
ShimConfigParams	getShimConfigParams() Get the ShimConfigParams instance associated with this instance.
ShimState	getShimState() Get the ShimState instance associated with this instance.
boolean	hasBeenModified() Return true if this instance has been modified.
boolean	isSecure() Return true if the password data and any other sensitive data associated with this instance is encrypted.
void	notifyShimState(Element[] stateElements) Method that will be notified when a <driver-state>, <subscriber-state>, or a <publisher-state> element is found in a shim document.
void	resetModified() Reset the modified flag for this instance such that hasBeenModified() will return false.
void	resetSecure() Set the sensitive data in this instance to be unencrypted.
void	setAppPassword(char[] newAppPassword) Set a new app password value for this instance.
void	setAppSchemaDef(SchemaDef newSchemaDef) Set a SchemaDef instance as application schema definition.
void	setAuthContext(String newAuthContext) Set the "authorization context" for this instance.
void	setAuthID(String newAuthID) Set the "authorization ID" for this instance.
void	setClassName(String newClassName) Set the class name for this instance.
void	setConfigPassword(char[] newConfigPassword) Set the password used to decrypt sensitive data in this instance.
void	setDesignerAppID(String newAppID) Set the "Designer application ID" for this instance.
void	setDirXMLSchemaDef(SchemaDef newSchemaDef) Set a SchemaDef instance as the DirXML schema definition.
void	setFakeDNs(String[] newFakeDNs) Set the "fake" DNs to use in building init documents.
void	setFilter(Filter newFilter) Set a Filter instance as the "live" data for this instance.
void	setGCVs(GCDefinitions newGCVs) Set a GCDefinitions instance as the "live" data for this instance.
void	setNamedPasswords(NamedPasswords newNamedPasswords) Set a NamedPasswords instance as the "live" data for this instance.
void	setNameMap(NameMap newNameMap) Set a NameMap instance as the "live" data for this instance.
void	setRemoteLoaderConfig(ShimConfig.RemoteLoaderConfig newConfig) Set a RemoteLoaderConfig instance as the "live" data for this instance.
void	setSecure(char[] newConfigPassword) Set the sensitive data in this instance to be encrypted.
void	setShimConfigParams(ShimConfigParams newConfigParams) Set a ShimConfigParams instance as the "live" data for this instance.
void	setShimState(ShimState newShimState) Set a ShimState instance as the "live" data for this instance.
Element	toXML(Node parent) Construct an XML representation of the configuration data in this instance.
void	write(File file) Serialize the configuration data in this instance as XML and write the bytes to a new file based on the passed File.
void	write(OutputStream outputStream) Serialize the configuration data in this instance as XML and write the bytes to an OutputStream.
void	write(String filename) Serialize the configuration data in this instance as XML and write the bytes to a new file with the passed file name.

Methods inherited from class java.lang.Object

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

Field Detail

TAG_SHIM_CONFIG

public static final String TAG_SHIM_CONFIG

Tag name for XML element 'shim-config'.

See Also:

Constant Field Values

TAG_CLASS_NAME

public static final String TAG_CLASS_NAME

Tag name for XML element 'class-name'.

See Also:

Constant Field Values

TAG_REMOTE_LOADER

public static final String TAG_REMOTE_LOADER

Tag name for XML element 'remote-loader'.

See Also:

Constant Field Values

TAG_CONNECTION_STRING

public static final String TAG_CONNECTION_STRING

Tag name for XML element 'connection-string'.

See Also:

Constant Field Values

TAG_LOADER_PASSWORD

public static final String TAG_LOADER_PASSWORD

Tag name for XML element 'loader-password'.

See Also:

Constant Field Values

TAG_DRIVER_PASSWORD

public static final String TAG_DRIVER_PASSWORD

Tag name for XML element 'driver-password'.

See Also:

Constant Field Values

TAG_AUTH_ID

public static final String TAG_AUTH_ID

Tag name for XML element 'auth-id'.

See Also:

Constant Field Values

TAG_AUTH_CONTEXT

public static final String TAG_AUTH_CONTEXT

Tag name for XML element 'auth-context'.

See Also:

Constant Field Values

TAG_APP_PASSWORD

public static final String TAG_APP_PASSWORD

Tag name for XML element 'app-password'.

See Also:

Constant Field Values

TAG_DRIVER_DN

public static final String TAG_DRIVER_DN

Tag name for XML element 'driver-dn'.

See Also:

Constant Field Values

TAG_SUBSCRIBER_DN

public static final String TAG_SUBSCRIBER_DN

Tag name for XML element 'subscriber-dn'.

See Also:

Constant Field Values

TAG_PUBLISHER_DN

public static final String TAG_PUBLISHER_DN

Tag name for XML element 'publisher-dn'.

See Also:

Constant Field Values

TAG_SHIM_STATE

public static final String TAG_SHIM_STATE

Tag name for XML element 'shim-state'.

See Also:

Constant Field Values

TAG_APP_SCHEMA_DEF

public static final String TAG_APP_SCHEMA_DEF

Tag name for XML element 'app-schema-def'.

See Also:

Constant Field Values

TAG_DIRXML_SCHEMA_DEF

public static final String TAG_DIRXML_SCHEMA_DEF

Tag name for XML element 'dirxml-schema-def'.

See Also:

Constant Field Values

TAG_SECURE_HASH

public static final String TAG_SECURE_HASH

Tag name for XML element 'secure-hash'.

See Also:

Constant Field Values

TAG_DESIGNER_APP_ID

public static final String TAG_DESIGNER_APP_ID

Tag name for XML element 'designer-app-id'

See Also:

Constant Field Values

ATTR_SECURE

public static final String ATTR_SECURE

Name for XML attribute 'secure'.

See Also:

Constant Field Values

ATTR_USE

public static final String ATTR_USE

Name for XML attribute 'use'.

See Also:

Constant Field Values

VAL_TRUE

public static final String VAL_TRUE

"true"

See Also:

Constant Field Values

VAL_FALSE

public static final String VAL_FALSE

"false"

See Also:

Constant Field Values

VAL_EMPTY_STRING

public static final String VAL_EMPTY_STRING

""

See Also:

Constant Field Values

Constructor Detail

ShimConfig

public ShimConfig()

Construct a default, empty ShimConfig object.

ShimConfig

public ShimConfig(ShimConfig source)

Construct a copy of an existing ShimConfig object.

Parameters:

source - existing ShimConfig instance

ShimConfig

public ShimConfig(String configFilename)
           throws IOException,
                  XMLException

Construct a ShimConfig object given a file name.

Parameters:

configFilename - name of file containing configuration XML.

Throws:

IOException - if an error occurs opening or reading the file

XMLException - if an error occurs parsing the XML

ShimConfig

public ShimConfig(Node configParent)
           throws XMLException

Construct a ShimConfig object given parsed XML.

Parameters:

configParent - DOM node that is the parent of the shim-config element.

Throws:

XMLException - if an error occurs parsing the XML

Method Detail

hasBeenModified

public boolean hasBeenModified()

Return true if this instance has been modified.

The instance is considered to have been modified if a change was made that affects the persistent representation since:

1. The instance was constructed from an XML representation.
2. resetModified() was last called

Specified by:

hasBeenModified in interface ConfigElement

Returns:

true or false

See Also:

resetModified()

resetModified

public void resetModified()

Reset the modified flag for this instance such that hasBeenModified() will return false.

Specified by:

resetModified in interface ConfigElement

See Also:

hasBeenModified()

getClassName

public String getClassName()

Return the class name from the configuration data. This is the class name irrespective of the Remote Loader configuration. If the class name to actually use is desired, use getShimClassName().

Returns:

class name (may be null)

See Also:

getShimClassName()

getShimClassName

public String getShimClassName()

Return the class name of the shim. This is either the return from getClassName() or ShimHost.REMOTE_SHIM_CLASS_NAME if the Remote Loader is being used.

Returns:

class name, null, or ShimHost.REMOTE_SHIM_CLASS_NAME

See Also:

getClassName()

setClassName

public void setClassName(String newClassName)

Set the class name for this instance.

Parameters:

newClassName - class name

getAuthID

public String getAuthID()

Return the "authorization ID" from the configuration data.

Returns:

auth ID (may be null)

setAuthID

public void setAuthID(String newAuthID)

Set the "authorization ID" for this instance.

Parameters:

newAuthID - auth ID

getAuthContext

public String getAuthContext()

Return the "authorization context" from the configuration data.

Returns:

auth context (may be null)

setAuthContext

public void setAuthContext(String newAuthContext)

Set the "authorization context" for this instance.

Parameters:

newAuthContext - auth context

getDesignerAppID

public String getDesignerAppID()

Return the "Designer application ID" from the configuration data.

The Designer application ID is the ID string that Novell's Designer for Identity Manager uses to identify applications.

Returns:

application ID (may be null)

setDesignerAppID

public void setDesignerAppID(String newAppID)

Set the "Designer application ID" for this instance.

The Designer application ID is the ID string that Novell's Designer for Identity Manager uses to identify applications.

Parameters:

newAppID - application ID String

getAppPassword

public Password getAppPassword()

Get the Password instance encapsulating the application password for the shim.

Returns:

app password instance (may be null)

setAppPassword

public void setAppPassword(char[] newAppPassword)
                    throws IllegalStateException,
                           CipherException

Set a new app password value for this instance.

If isSecure() returns true, the configuration password must have been set via setConfigPassword() if the newAppPassword parameter is non-null.

Parameters:

newAppPassword - password characters (may be null)

Throws:

IllegalStateException - if isSecure() returns true and no configuration password has been set.

CipherException - if an error occurs while encrypting the new password value

See Also:

isSecure(), setConfigPassword(char[])

getFakeDNs

public String[] getFakeDNs()

Return an array of Strings containing the "fake" DN values in this configuration instance. The fake DN values are used for the "src-dn" attribute in configuration documents for shim init() methods.

Returns:

array of three Strings: 0 is driver DN, 1 is subscriber DN, 2 is publisher DN

setFakeDNs

public void setFakeDNs(String[] newFakeDNs)
                throws IllegalArgumentException

Set the "fake" DNs to use in building init documents.

Parameters:

newFakeDNs - array of three Strings: 0 is driver DN, 1 is subscriber DN, 2 is publisher DN (any or all of which may be null, or the array itself may be null)

Throws:

IllegalArgumentException - if the array parameter is less than 3 elements in length

getRemoteLoaderConfig

public ShimConfig.RemoteLoaderConfig getRemoteLoaderConfig()

Get the RemoteLoaderConfig instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

config instance (may be null)

setRemoteLoaderConfig

public void setRemoteLoaderConfig(ShimConfig.RemoteLoaderConfig newConfig)

Set a RemoteLoaderConfig instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newConfig - config instance to use (may be null)

getFilter

public Filter getFilter()

Get the Filter instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

filter instance (may be null)

setFilter

public void setFilter(Filter newFilter)

Set a Filter instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newFilter - filter instance to use (may be null)

getNameMap

public NameMap getNameMap()

Get the NameMap instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

The NameMap instance is used to map class and attribute names in the Filter when constructing init documents.

Returns:

NameMap instance (may be null)

setNameMap

public void setNameMap(NameMap newNameMap)

Set a NameMap instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

The NameMap instance is used to map class and attribute names in the Filter when constructing init documents.

Parameters:

newNameMap - NameMap instance to use (may be null)

getShimConfigParams

public ShimConfigParams getShimConfigParams()

Get the ShimConfigParams instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

ShimConfigParams instance (may be null)

setShimConfigParams

public void setShimConfigParams(ShimConfigParams newConfigParams)

Set a ShimConfigParams instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newConfigParams - ShimConfigParams instance to use (may be null)

getGCVs

public GCDefinitions getGCVs()

Get the GCDefinitions instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

GCDefinitions instance (may be null)

setGCVs

public void setGCVs(GCDefinitions newGCVs)

Set a GCDefinitions instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newGCVs - GCDefinitions instance to use (may be null)

getNamedPasswords

public NamedPasswords getNamedPasswords()

Get the NamedPasswords instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

NamedPasswords instance (may be null)

setNamedPasswords

public void setNamedPasswords(NamedPasswords newNamedPasswords)

Set a NamedPasswords instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newNamedPasswords - NamedPasswords instance to use (may be null)

getShimState

public ShimState getShimState()

Get the ShimState instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

ShimState instance (may be null)

setShimState

public void setShimState(ShimState newShimState)

Set a ShimState instance as the "live" data for this instance. Any changes made to the passed object will be reflected in this instance's configuration data.

Parameters:

newShimState - ShimState instance to use (may be null)

getAppSchemaDef

public SchemaDef getAppSchemaDef()

Get the application SchemaDef instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

SchemaDef instance (may be null)

setAppSchemaDef

public void setAppSchemaDef(SchemaDef newSchemaDef)

Set a SchemaDef instance as application schema definition.

Parameters:

newSchemaDef - SchemaDef instance to use (may be null)

getDirXMLSchemaDef

public SchemaDef getDirXMLSchemaDef()

Get the DirXML SchemaDef instance associated with this instance. Note that if non-null, the returned instance is "live" and changes made to it will be reflected in this instance's configuration data.

Returns:

SchemaDef instance (may be null)

setDirXMLSchemaDef

public void setDirXMLSchemaDef(SchemaDef newSchemaDef)

Set a SchemaDef instance as the DirXML schema definition.

Parameters:

newSchemaDef - SchemaDef instance to use (may be null)

isSecure

public boolean isSecure()

Return true if the password data and any other sensitive data associated with this instance is encrypted.

Returns:

true or false

setSecure

public void setSecure(char[] newConfigPassword)
               throws IllegalArgumentException,
                      CipherException

Set the sensitive data in this instance to be encrypted.

This method is used to change currently unencrypted password data to encrypted data. Use setConfigPassword() to supply the password for already-encrypted data.

Parameters:

newConfigPassword - password to use in encrypting the sensitive data

Throws:

IllegalArgumentException - if newConfigPassword is null

CipherException - if an error occurs during the encryption process

See Also:

setConfigPassword(char[])

resetSecure

public void resetSecure()
                 throws CipherException

Set the sensitive data in this instance to be unencrypted.

Throws:

CipherException - if an error occurs during the decryption process

setConfigPassword

public void setConfigPassword(char[] newConfigPassword)
                       throws ShimConfig.BadPasswordException

Set the password used to decrypt sensitive data in this instance.

This method is used to supply the password for already-encrypted data, such as when the data is read from a file. Use setSecure() to secure unencrypted data.

Parameters:

newConfigPassword - password

Throws:

ShimConfig.BadPasswordException - if this ShimConfig instance is secure and the passed password isn't correct

See Also:

setSecure(char[])

getConfigPassword

public final char[] getConfigPassword()

Return the configuration password.

Returns:

null or array containing configuration password

write

public void write(String filename)
           throws IOException

Serialize the configuration data in this instance as XML and write the bytes to a new file with the passed file name. The XML is serialized with UTF-8 encoding.

Parameters:

filename - name of file

Throws:

IOException - if an error occurs while creating/opening or writing the file

write

public void write(File file)
           throws IOException

Serialize the configuration data in this instance as XML and write the bytes to a new file based on the passed File. The XML is serialized with UTF-8 encoding.

Parameters:

file - File object representing the file to use

Throws:

IOException - if an error occurs while creating/opening or writing the file

write

public void write(OutputStream outputStream)
           throws IOException

Serialize the configuration data in this instance as XML and write the bytes to an OutputStream. The XML is serialized with UTF-8 encoding.

Parameters:

outputStream - OutputStream to which to write

Throws:

IOException - if an error occurs while writing to the OutputStream

toXML

public Element toXML(Node parent)

Construct an XML representation of the configuration data in this instance.

Note that the act of creating an XML representation does not reset this instance's modified flag. It must be reset by calling resetModified().

Specified by:

toXML in interface ConfigElement

Parameters:

parent - Node under which to construct the XML representation

Returns:

constructed <>shim-config> element

See Also:

hasBeenModified(), resetModified()

createInitDocs

public Document[] createInitDocs()
                          throws ConfigException

Create three XML Documents suitable for passing to the DriverShim, SubscriptionShim, and PublicationShim init() methods.

The created documents are returned in an array suitable for use as the parameter to ShimHost.start().

Returns:

array of three Document objects: index 0, 1, and 2 are for DriverShim, SubscriptionShim, and PublicationShim, respectively.

Throws:

ConfigException - if an error occurs while constructing the documents (e.g., a password decryption error occurs)

See Also:

ShimHost.start(org.w3c.dom.Document[])

createGetSchemaInitDoc

public Document createGetSchemaInitDoc()
                                throws ConfigException

Create an XML Document suitable for passing to DriverShim.getSchema().

The created document is suitable for use as the parameter to ShimHost.getSchema().

Returns:

Document for use with DriverShim.getSchema()

Throws:

ConfigException - if an error occurs while constructing the documents (e.g., a password decryption error occurs)

See Also:

ShimHost.getSchema(org.w3c.dom.Document)

getReferencedValue

public GCValue getReferencedValue(String name)

Supply a value given the name of the referenced item. If the name isn't recognized, then the result is null.

Implementation of ShimParams.ReferenceResolver. This will look for the named GCV in any GCV definition that exists as part of this ShimConfig instance.

Specified by:

getReferencedValue in interface ShimParams.ReferenceResolver

Parameters:

name - name of referenced item

Returns:

null or the referenced item

See Also:

ShimParams.ReferenceResolver

notifyShimState

public void notifyShimState(Element[] stateElements)

Method that will be notified when a <driver-state>, <subscriber-state>, or a <publisher-state> element is found in a shim document.

This method will set the new state into the data associated with this instance.

Specified by:

notifyShimState in interface ShimHost.StateListener

Parameters:

stateElements - 3-element array containing 1 or more shim state elements.

See Also:

ShimHost.StateListener

checkDriverPassword

public boolean checkDriverPassword(String password)

Method that will be called to handle a <check-password> command received on the Publisher channel. This will only check against the driver password in the remote loader configuration, if any exists.

Specified by:

checkDriverPassword in interface ShimHost.DriverPasswordCheck

Parameters:

password - value to check

Returns:

true if password matches; false otherwise

See Also:

ShimHost.DriverPasswordCheck