com.novell.nds.dirxml.shimhost
Class ShimHost

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

public class ShimHost

extends Object

ShimHost is a class that will load and communicate with a DirXML application shim. It is designed to be a building block for applications that use DirXML application shims outside of the DirXML Engine.

ShimHost supplies some default behavior that can be used to simplify what needs to be done to run an application shim:

• Handling for events submitted by the publisher shim: The default behavior is to simply return a "success" status to the publisher shim for each event found in the event document.
• Handling for queries submitted by the subscriber shim during the processing of commands. The default behavior is to return a "success" status as the result of the query.

The default behaviors can be overridden by supplying handlers for the cases listed. See setPublisherEventHandler() and execute().

There are a number of classes in the com.novell.nds.dirxml.shimhost package designed to help with assembling and formatting the data necessary to run a shim. However, the most important is the ShimConfig class which is used to load and save the configuration information for a shim to and from an XML document. The ShimConfig class also provides methods for constructing the initialization documents needed by the shim init() methods from the shim configuration data.

The minimum steps required to load and run a shim are:

1. Construct a ShimHost instance, supplying a class name.
2. Construct initialization documents for the shim's init() methods.
3. Call start() to construct the shim object and cause the shim's initialization methods to be called
4. Call shutdown() to cause the shim's DriverShim.shutdown() method to be called and the shim object to be made available for garbage collection.

A more realistic scenario is:

1. Load shim configuration information from an XML document using an instance of the ShimConfig class.
2. Call ShimConfig.createInitDocs() to get the initialization documents needed for the call to ShimHost.start().
3. Register an implementation of com.novell.nds.dirxml.driver.TraceInterface (e.g., ConsoleTraceImpl or FileTraceImpl).
4. Construct an instance of the com.novell.nds.dirxml.driver.Trace class.
5. Construct a ShimHost instance, supplying the shim's class name from the ShimConfig instance, and supplying the constructed Trace instance.
6. Call setPublisherEventHandler() to register a handler for published documents from the shim.
7. Call start() to construct and initialize the application shim.
8. Call execute() to submit commands to the Subscriber shim.
9. Call shutdown() to shut down the shim and clean up resources.

Remote Loader Support

ShimHost has two Publisher-channel behaviors to facilitate using the Remote Loader:

1. If the only element under <input> in the Publisher-submitted document is a <query> command that reads the driver object's Public Key attribute then the ShimHost instance will return a fabricated <instance> element containing a Public Key value.
2. If the only element under <input> in the Publisher-submitted document is a &check-password> command then the ShimHost instance will call any DriverPasswordCheck implementation that has been set via setDriverPasswordCheck() and return the result in a <status> element.

Note that the above behaviors preclude sending the two commands to any XmlCommandProcessor implementation that has been set via setPublisherEventHandler().

See Also:

ShimConfig, ConsoleTraceImpl, FileTraceImpl

Nested Class Summary

static interface	ShimHost.DriverPasswordCheck Interface to handle <check-password> commands received on the Publisher channel.
class	ShimHost.MethodException Extension of ShimException, used to encapsulate a Throwable that is thrown by a shim method.
static interface	ShimHost.PublisherFatalErrorListener
static interface	ShimHost.RunningStateChangeListener Interface through which notification of changes to the shim's running state are made.
static interface	ShimHost.StateListener Interface to receive notification of shim state elements when state elements appear in documents from the shim.

Field Summary

static int	DRIVER_INIT_DOC Array index of initialization document for DriverShim.init() in start() method's initDocs parameter.
static int	DRIVER_INIT_RETURN Array index of return document from DriverShim.init() in return from start() method.
static int	DRIVER_SHUTDOWN_RETURN Array index of return document from DriverShim.shutdown() in return from shutdown() method.
static int	DRIVER_STATE Array index of <driver-state> element in stateElements array passed to StateListener.notifyShimState() method.
static int	PUBLISHER_INIT_DOC Array index of initialization document for PublicationShim.init() in start() method's initDocs parameter.
static int	PUBLISHER_INIT_RETURN Array index of return document from PublicationShim.init() in return from start() method.
static int	PUBLISHER_START_RETURN Array index of return document from PublicationShim.start() in return from shutdown() method.
static int	PUBLISHER_STATE Array index of <publisher-state> element in stateElements array passed to StateListener.notifyShimState() method.
static String	REMOTE_SHIM_CLASS_NAME Name of the Remote Interface Shim class.
static int	STATE_FLAG_DRIVER_INITIALIZED Bit flag for getRunningState() value indicating that DriverShim.init() has been called and returned from.
static int	STATE_FLAG_IN_PUBLISHER_START Bit flag for getRunningState() value indicating that PublicationShim.start() has been called.
static int	STATE_FLAG_PUBLISHER_INITIALIZED Bit flag for getRunningState() value indicating that PublicationShim.init() has been called and returned from.
static int	STATE_FLAG_SUBSCRIBER_INITIALIZED Bit flag for getRunningState() value indicating that SubscriptionShim.init() has been called and returned from.
static int	STATE_RUNNING Value returned by getRunningState() indicating that the shim is fully initialized and running.
static int	STATE_STOPPED Value returned by getRunningState() indicating that the shim is not running.
static int	SUBSCRIBER_INIT_DOC Array index of initialization document for SubscriptionShim.init() in start() method's initDocs parameter.
static int	SUBSCRIBER_INIT_RETURN Array index of return document from SubscriptionShim.init() in return from start() method.
static int	SUBSCRIBER_STATE Array index of <subscriber-state> element in stateElements array passed to StateListener.notifyShimState() method.

Constructor Summary

ShimHost(String className)
Construct a ShimHost instance for the passed class name.

ShimHost(String className, Trace tracer)
Construct a ShimHost instance for the passed class name using the passed Trace facility.

Method Summary

static void	checkForFatalError(Document returnDoc) Examine a shim document for any <status> element with level="fatal".
static void	checkForFatalError(XmlDocument doc) Examine a shim document for any <status> element with level="fatal".
static void	cleanup() Perform static class cleanup().
Document	execute(Document commandDocument, XmlQueryProcessor queryProcessor) Cause the Subscriber thread to submit the passed command document to the shim's SubscriptionShim.execute() method.
String	getClassName() Return the class name associationed with this instance.
int	getRunningState() Return the current state of this instance
Document	getSchema(Document initDoc) Call the shim's DriverShim.getSchema() method.
Trace	getTracer() Get the Trace object that is used by this instance for outputting trace messages.
static void	initialize() Perform static class initialization.
static void	initialize(ClassLoader cl) Perform static class initialization.
void	load() Construct the instance of the DriverShim implementation class to be used.
void	setDriverPasswordCheck(ShimHost.DriverPasswordCheck checker) Method to set a DriverPasswordCheck implementation to check a string against the driver object password.
void	setPublisherEventHandler(XmlCommandProcessor cmdProcessor) Set an XmlCommandProcessor instance to receive event documents from the shim's Publisher.
void	setRunningStateChangeListener(ShimHost.RunningStateChangeListener listener) Method to set a RunningStateChangeListener implementation to be notified when the shim starts or stops.
void	setStateListener(ShimHost.StateListener listener) Method to set a StateListener implementation to be notified of shim state changes when reported by the shim in a shim document.
Document[]	shutdown(Document reasonDoc) Cause the Subscriber thread to call the shim's DriverShim.shutdown() method.
Document[]	start(Document[] initDocs) Cause the Subscriber thread to initialize the shim and start the publisher.
void	validateClass() Validate that the class name with which this instance was created can be found.

Methods inherited from class java.lang.Object

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

Field Detail

DRIVER_INIT_DOC

public static final int DRIVER_INIT_DOC

Array index of initialization document for DriverShim.init() in start() method's initDocs parameter.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

SUBSCRIBER_INIT_DOC

public static final int SUBSCRIBER_INIT_DOC

Array index of initialization document for SubscriptionShim.init() in start() method's initDocs parameter.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

PUBLISHER_INIT_DOC

public static final int PUBLISHER_INIT_DOC

Array index of initialization document for PublicationShim.init() in start() method's initDocs parameter.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

DRIVER_INIT_RETURN

public static final int DRIVER_INIT_RETURN

Array index of return document from DriverShim.init() in return from start() method.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

SUBSCRIBER_INIT_RETURN

public static final int SUBSCRIBER_INIT_RETURN

Array index of return document from SubscriptionShim.init() in return from start() method.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

PUBLISHER_INIT_RETURN

public static final int PUBLISHER_INIT_RETURN

Array index of return document from PublicationShim.init() in return from start() method.

See Also:

start(org.w3c.dom.Document[]), Constant Field Values

DRIVER_SHUTDOWN_RETURN

public static final int DRIVER_SHUTDOWN_RETURN

Array index of return document from DriverShim.shutdown() in return from shutdown() method.

See Also:

shutdown(org.w3c.dom.Document), Constant Field Values

PUBLISHER_START_RETURN

public static final int PUBLISHER_START_RETURN

Array index of return document from PublicationShim.start() in return from shutdown() method.

See Also:

shutdown(org.w3c.dom.Document), Constant Field Values

DRIVER_STATE

public static final int DRIVER_STATE

Array index of <driver-state> element in stateElements array passed to StateListener.notifyShimState() method.

See Also:

ShimHost.StateListener, Constant Field Values

SUBSCRIBER_STATE

public static final int SUBSCRIBER_STATE

Array index of <subscriber-state> element in stateElements array passed to StateListener.notifyShimState() method.

See Also:

ShimHost.StateListener, Constant Field Values

PUBLISHER_STATE

public static final int PUBLISHER_STATE

Array index of <publisher-state> element in stateElements array passed to StateListener.notifyShimState() method.

See Also:

ShimHost.StateListener, Constant Field Values

STATE_FLAG_DRIVER_INITIALIZED

public static final int STATE_FLAG_DRIVER_INITIALIZED

Bit flag for getRunningState() value indicating that DriverShim.init() has been called and returned from.

See Also:

getRunningState(), Constant Field Values

STATE_FLAG_SUBSCRIBER_INITIALIZED

public static final int STATE_FLAG_SUBSCRIBER_INITIALIZED

Bit flag for getRunningState() value indicating that SubscriptionShim.init() has been called and returned from.

See Also:

getRunningState(), Constant Field Values

STATE_FLAG_PUBLISHER_INITIALIZED

public static final int STATE_FLAG_PUBLISHER_INITIALIZED

Bit flag for getRunningState() value indicating that PublicationShim.init() has been called and returned from.

See Also:

getRunningState(), Constant Field Values

STATE_FLAG_IN_PUBLISHER_START

public static final int STATE_FLAG_IN_PUBLISHER_START

Bit flag for getRunningState() value indicating that PublicationShim.start() has been called.

See Also:

getRunningState(), Constant Field Values

STATE_STOPPED

public static final int STATE_STOPPED

Value returned by getRunningState() indicating that the shim is not running.

See Also:

getRunningState(), Constant Field Values

STATE_RUNNING

public static final int STATE_RUNNING

Value returned by getRunningState() indicating that the shim is fully initialized and running.

See Also:

getRunningState(), Constant Field Values

REMOTE_SHIM_CLASS_NAME

public static final String REMOTE_SHIM_CLASS_NAME

Name of the Remote Interface Shim class.

See Also:

Constant Field Values

Constructor Detail

ShimHost

public ShimHost(String className)
         throws IllegalArgumentException,
                ClassNotFoundException,
                ShimException

Construct a ShimHost instance for the passed class name. This overload will set up com.novell.nds.dirxml.shimhost.ConsoleTraceImpl as the trace facility for the constructed instance, meaning that all trace messages will be delivered to System.out.

Parameters:

className - the name of the application shim's DriverShim implementation class

Throws:

IllegalArgumentException - if className is null

ClassNotFoundException - if the specified class can't be loaded

ShimException - if the specified class's default constructor throws a Throwable during construction

ShimHost

public ShimHost(String className,
                Trace tracer)
         throws IllegalArgumentException,
                ClassNotFoundException,
                ShimException

Construct a ShimHost instance for the passed class name using the passed Trace facility.

Parameters:

className - the name of the application shim's DriverShim implementation class

tracer - an instance of Trace to use for outputting trace messages

Throws:

IllegalArgumentException - if className is null

ClassNotFoundException - if the specified class can't be loaded

ShimException - if the specified class's default constructor throws a Throwable during construction

Method Detail

initialize

public static void initialize()

Perform static class initialization.

initialize

public static void initialize(ClassLoader cl)

Perform static class initialization.

Parameters:

cl - ClassLoader instance to use for loading shim classes.

cleanup

public static void cleanup()

Perform static class cleanup().

validateClass

public void validateClass()
                   throws ClassNotFoundException

Validate that the class name with which this instance was created can be found.

Throws:

ClassNotFoundException

getClassName

public String getClassName()

Return the class name associationed with this instance.

Returns:

class name

getRunningState

public int getRunningState()

Return the current state of this instance

Returns:

state

See Also:

STATE_STOPPED, STATE_RUNNING, STATE_FLAG_DRIVER_INITIALIZED, STATE_FLAG_SUBSCRIBER_INITIALIZED, STATE_FLAG_PUBLISHER_INITIALIZED, STATE_FLAG_IN_PUBLISHER_START

getTracer

public Trace getTracer()

Get the Trace object that is used by this instance for outputting trace messages.

Returns:

Trace instance

setPublisherEventHandler

public void setPublisherEventHandler(XmlCommandProcessor cmdProcessor)

Set an XmlCommandProcessor instance to receive event documents from the shim's Publisher. Note that the XmlCommandProcessor.execute() will be called on the Publisher thread.

Parameters:

cmdProcessor - XmlCommandProcessor instance, or null

See Also:

XmlCommandProcessor

setStateListener

public void setStateListener(ShimHost.StateListener listener)

Method to set a StateListener implementation to be notified of shim state changes when reported by the shim in a shim document. The StateListener.notifyShimState() method may be called on either the Publisher or the Subscriber thread.

Parameters:

listener - StateListener implementation

See Also:

ShimHost.StateListener

setRunningStateChangeListener

public void setRunningStateChangeListener(ShimHost.RunningStateChangeListener listener)

Method to set a RunningStateChangeListener implementation to be notified when the shim starts or stops. The listener will be notified only when the shim transitions from stopped to running and vice versa.

Parameters:

listener - object to be notified

See Also:

ShimHost.RunningStateChangeListener

setDriverPasswordCheck

public void setDriverPasswordCheck(ShimHost.DriverPasswordCheck checker)

Method to set a DriverPasswordCheck implementation to check a string against the driver object password.

Parameters:

checker - DriverPasswordCheck implementation

See Also:

ShimHost.DriverPasswordCheck

load

public void load()
          throws ClassNotFoundException,
                 ShimException

Construct the instance of the DriverShim implementation class to be used. Calling this method is not strictly necessary as it will be called when needed by the getSchema() and start() methods. It is provided for testing and completeness.

This method causes the Subscriber thread to actually construct the DriverShim instance. This method will not return until the Subscriber thread has completed the construction.

Throws:

ShimException - if the DriverShim constructor throws a Throwable

ClassNotFoundException

See Also:

DriverShim

getSchema

public Document getSchema(Document initDoc)
                   throws IllegalStateException,
                          IllegalArgumentException,
                          ShimException,
                          ClassNotFoundException

Call the shim's DriverShim.getSchema() method.

This method causes the Subscriber thread to call DriverShim.getSchema(). This method will not return until the Subscriber thread has completed the call and returned the resulting document to the calling thread.

Parameters:

initDoc - Document to pass to DriverShim.getSchema()

Returns:

Document returned from DriverShim.getSchema()

Throws:

IllegalStateException - if getRunningState() returns other than STATE_STOPPED

IllegalArgumentException - if initDoc parameter is null

ShimException - if DriverShim.getSchema() throws a Throwable

ClassNotFoundException - if load() has not yet been called, and a ClassNotFoundException is thrown during the attempt to load the shim

See Also:

getRunningState(), load(), DriverShim.getSchema(com.novell.nds.dirxml.driver.XmlDocument)

start

public Document[] start(Document[] initDocs)
                 throws IllegalStateException,
                        IllegalArgumentException,
                        ShimException,
                        ClassNotFoundException

Cause the Subscriber thread to initialize the shim and start the publisher.

This method will cause the following actions on the Subscriber thread:

1. If load() has not yet been called, load() is called to create the DriverShim implementation.
2. DriverShim.init() is called.
3. SubscriptionShim.init() is called.
4. The Publisher thread is started
5. PublicationShim.init() is called.
6. PublicationShim.start() is called.

If an error occurs in any of the above steps the start process is aborted and the shim is shut down by calling shutdown().

Parameters:

initDocs - array of 3 initialization Documents to pass to DriverShim.init(), SubscriptionShim.init(), and PublicationShim.init()

Returns:

array of 3 return Documents from DriverShim.init(), SubscriptionShim.init(), and PublicationShim.init()

Throws:

IllegalStateException - if getRunningState() returns other than STATE_STOPPED

IllegalArgumentException - if the initDocs parameter is null, or one of the array elements is null

ShimException - if one of the shim methods throws a Throwable, or if one of the shim methods returns a "fatal" status

ClassNotFoundException - if load() has not yet been called, and a ClassNotFoundException is thrown during the attempt to load the shim

See Also:

getRunningState(), load(), DriverShim.init(com.novell.nds.dirxml.driver.XmlDocument), SubscriptionShim.init(com.novell.nds.dirxml.driver.XmlDocument), PublicationShim.init(com.novell.nds.dirxml.driver.XmlDocument), PublicationShim.start(com.novell.nds.dirxml.driver.XmlCommandProcessor), DRIVER_INIT_DOC, SUBSCRIBER_INIT_DOC, PUBLISHER_INIT_DOC, DRIVER_INIT_RETURN, SUBSCRIBER_INIT_RETURN, PUBLISHER_INIT_RETURN

execute

public Document execute(Document commandDocument,
                        XmlQueryProcessor queryProcessor)
                 throws IllegalStateException,
                        ShimException

Cause the Subscriber thread to submit the passed command document to the shim's SubscriptionShim.execute() method.

If the shim issues a call-back query via the queryProcessor parameter, the XmlQueryProcessor.query() method will be called on the thread used to call this method.

Note that the start() method must have been previously called, and that the shutdown() method must not yet have been called.

Parameters:

commandDocument - Document containing commands for Subscriber shim

queryProcessor - implementation of XmlQueryProcessor to handler queries from the Subscriber shim. This parameter may be null, in which case the behavior is to return a "success" status as the result of any query.

Returns:

result Document from the Subscriber shim

Throws:

IllegalStateException - if getRunningState() doesn't return STATE_RUNNING

ShimException - if SubscriptionShim.execute() throws a Throwable

See Also:

getRunningState(), SubscriptionShim.execute(com.novell.nds.dirxml.driver.XmlDocument, com.novell.nds.dirxml.driver.XmlQueryProcessor), XmlQueryProcessor.query(com.novell.nds.dirxml.driver.XmlDocument)

shutdown

public Document[] shutdown(Document reasonDoc)
                    throws IllegalStateException,
                           ShimException

Cause the Subscriber thread to call the shim's DriverShim.shutdown() method.

The start() method must have been previously called.

Parameters:

reasonDoc - a Document containing information on the purpose of the shutdown (may be null)

Returns:

array of 2 Documents returned from DriverShim.shutdown() and PublicationShim.start()

Throws:

IllegalStateException - if getRunningState() returns STATE_STOPPED

ShimException - if DriverShim.shutdown() throws a Throwable

See Also:

DriverShim.shutdown(com.novell.nds.dirxml.driver.XmlDocument), PublicationShim.start(com.novell.nds.dirxml.driver.XmlCommandProcessor), getRunningState(), DRIVER_SHUTDOWN_RETURN, PUBLISHER_START_RETURN

checkForFatalError

public static void checkForFatalError(XmlDocument doc)
                               throws FatalShimException

Examine a shim document for any <status> element with level="fatal".

This method is used internally by the ShimHost class, and is provided for users of the ShimHost class as well.

Parameters:

doc - XmlDocument from shim

Throws:

FatalShimException - if there is one or more <status> element with the level attribute set to "fatal"

checkForFatalError

public static void checkForFatalError(Document returnDoc)
                               throws FatalShimException

Examine a shim document for any <status> element with level="fatal".

This method is used internally by the ShimHost class, and is provided for users of the ShimHost class as well.

Parameters:

returnDoc - Document from shim

Throws:

FatalShimException - if there is one or more <status> element with the level attribute set to "fatal"