public class ShimHost
extends java.lang.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: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:ShimHost
instance, supplying a class name.init()
methods.
start()
to construct the shim object and cause the shim's initialization methods to be calledshutdown()
to cause the shim's DriverShim.shutdown()
method to be called and the shim object to
be made available for garbage collection.ShimConfig
class.ShimConfig.createInitDocs()
to get the initialization documents needed for the call to
ShimHost.start()
.com.novell.nds.dirxml.driver.TraceInterface
(e.g., ConsoleTraceImpl
or FileTraceImpl
).com.novell.nds.dirxml.driver.Trace
class.ShimHost
instance, supplying the shim's class name from the ShimConfig
instance,
and supplying the constructed Trace
instance.setPublisherEventHandler()
to register a handler for published documents from the shim.
start()
to construct and initialize the application shim.execute()
to submit commands to the Subscriber shim.shutdown()
to shut down the shim and clean up resources.ShimHost
has two Publisher-channel behaviors to facilitate using the Remote Loader:
ShimHost
instance will
return a fabricated <instance> element containing a Public Key value.ShimHost
instance will
call any DriverPasswordCheck
implementation that has been set via
setDriverPasswordCheck()
and return the result in a <status> element.
XmlCommandProcessor
implementation that has been set via setPublisherEventHandler()
.ShimConfig
,
ConsoleTraceImpl
,
FileTraceImpl
Modifier and Type | Class and Description |
---|---|
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.
|
Modifier and Type | Field and Description |
---|---|
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 java.lang.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 and Description |
---|
ShimHost(java.lang.String className)
Construct a
ShimHost instance for the passed class name. |
ShimHost(java.lang.String className,
Trace tracer)
Construct a
ShimHost instance for the passed class name using the passed
Trace facility. |
Modifier and Type | Method and Description |
---|---|
static void |
checkForFatalError(org.w3c.dom.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().
|
org.w3c.dom.Document |
execute(org.w3c.dom.Document commandDocument,
XmlQueryProcessor queryProcessor)
Cause the Subscriber thread to submit the passed command document to the
shim's
SubscriptionShim.execute() method. |
java.lang.String |
getClassName()
Return the class name associationed with this instance.
|
int |
getRunningState()
Return the current state of this instance
|
org.w3c.dom.Document |
getSchema(org.w3c.dom.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(java.lang.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. |
org.w3c.dom.Document[] |
shutdown(org.w3c.dom.Document reasonDoc)
Cause the Subscriber thread to call the shim's
DriverShim.shutdown() method. |
org.w3c.dom.Document[] |
start(org.w3c.dom.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.
|
public static final int DRIVER_INIT_DOC
DriverShim.init()
in start()
method's initDocs
parameter.public static final int SUBSCRIBER_INIT_DOC
SubscriptionShim.init()
in start()
method's initDocs
parameter.public static final int PUBLISHER_INIT_DOC
PublicationShim.init()
in start()
method's initDocs
parameter.public static final int DRIVER_INIT_RETURN
DriverShim.init()
in return from start()
method.public static final int SUBSCRIBER_INIT_RETURN
SubscriptionShim.init()
in return from start()
method.public static final int PUBLISHER_INIT_RETURN
PublicationShim.init()
in return from start()
method.public static final int DRIVER_SHUTDOWN_RETURN
DriverShim.shutdown()
in return from shutdown()
method.public static final int PUBLISHER_START_RETURN
PublicationShim.start()
in return from shutdown()
method.public static final int DRIVER_STATE
stateElements
array passed to
StateListener.notifyShimState()
method.ShimHost.StateListener
,
Constant Field Valuespublic static final int SUBSCRIBER_STATE
stateElements
array passed to
StateListener.notifyShimState()
method.ShimHost.StateListener
,
Constant Field Valuespublic static final int PUBLISHER_STATE
stateElements
array passed to
StateListener.notifyShimState()
method.ShimHost.StateListener
,
Constant Field Valuespublic static final int STATE_FLAG_DRIVER_INITIALIZED
getRunningState()
value indicating that
DriverShim.init()
has been called and returned from.getRunningState()
,
Constant Field Valuespublic static final int STATE_FLAG_SUBSCRIBER_INITIALIZED
getRunningState()
value indicating that
SubscriptionShim.init()
has been called and returned from.getRunningState()
,
Constant Field Valuespublic static final int STATE_FLAG_PUBLISHER_INITIALIZED
getRunningState()
value indicating that
PublicationShim.init()
has been called and returned from.getRunningState()
,
Constant Field Valuespublic static final int STATE_FLAG_IN_PUBLISHER_START
getRunningState()
value indicating that
PublicationShim.start()
has been called.getRunningState()
,
Constant Field Valuespublic static final int STATE_STOPPED
getRunningState()
indicating that the shim is not running.getRunningState()
,
Constant Field Valuespublic static final int STATE_RUNNING
getRunningState()
indicating that the shim is fully initialized and running.getRunningState()
,
Constant Field Valuespublic static final java.lang.String REMOTE_SHIM_CLASS_NAME
public ShimHost(java.lang.String className) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, ShimException
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.className
- the name of the application shim's DriverShim
implementation
classjava.lang.IllegalArgumentException
- if className
is null
java.lang.ClassNotFoundException
- if the specified class can't be loadedShimException
- if the specified class's default constructor throws
a Throwable
during constructionpublic ShimHost(java.lang.String className, Trace tracer) throws java.lang.IllegalArgumentException, java.lang.ClassNotFoundException, ShimException
ShimHost
instance for the passed class name using the passed
Trace
facility.className
- the name of the application shim's DriverShim
implementation
classtracer
- an instance of Trace
to use for outputting trace messagesjava.lang.IllegalArgumentException
- if className
is nulljava.lang.ClassNotFoundException
- if the specified class can't be loadedShimException
- if the specified class's default constructor throws
a Throwable
during constructionpublic static void initialize()
public static void initialize(java.lang.ClassLoader cl)
cl
- ClassLoader instance to use for loading shim classes.public static void cleanup()
public void validateClass() throws java.lang.ClassNotFoundException
java.lang.ClassNotFoundException
public java.lang.String getClassName()
public int getRunningState()
public Trace getTracer()
Trace
object that is used by this instance for
outputting trace messages.Trace
instancepublic void setPublisherEventHandler(XmlCommandProcessor cmdProcessor)
XmlCommandProcessor
instance to receive event documents from
the shim's Publisher. Note that the XmlCommandProcessor.execute()
will be called on the Publisher thread.cmdProcessor
- XmlCommandProcessor
instance, or null
XmlCommandProcessor
public void setStateListener(ShimHost.StateListener listener)
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.listener
- StateListener
implementationShimHost.StateListener
public void setRunningStateChangeListener(ShimHost.RunningStateChangeListener listener)
listener
- object to be notifiedShimHost.RunningStateChangeListener
public void setDriverPasswordCheck(ShimHost.DriverPasswordCheck checker)
DriverPasswordCheck
implementation to check a string against
the driver object password.checker
- DriverPasswordCheck
implementationShimHost.DriverPasswordCheck
public void load() throws java.lang.ClassNotFoundException, ShimException
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.ShimException
- if the DriverShim
constructor throws
a Throwable
java.lang.ClassNotFoundException
DriverShim
public org.w3c.dom.Document getSchema(org.w3c.dom.Document initDoc) throws java.lang.IllegalStateException, java.lang.IllegalArgumentException, ShimException, java.lang.ClassNotFoundException
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.initDoc
- Document
to pass to DriverShim.getSchema()
Document
returned from DriverShim.getSchema()
java.lang.IllegalStateException
- if getRunningState()
returns other than STATE_STOPPED
java.lang.IllegalArgumentException
- if initDoc
parameter is null
ShimException
- if DriverShim.getSchema()
throws a Throwable
java.lang.ClassNotFoundException
- if load()
has not yet been called, and a ClassNotFoundException
is
thrown during the attempt to load the shimgetRunningState()
,
load()
,
DriverShim.getSchema(com.novell.nds.dirxml.driver.XmlDocument)
public org.w3c.dom.Document[] start(org.w3c.dom.Document[] initDocs) throws java.lang.IllegalStateException, java.lang.IllegalArgumentException, ShimException, java.lang.ClassNotFoundException
load()
has not yet been called, load()
is called
to create the DriverShim
implementation.DriverShim.init()
is called.SubscriptionShim.init()
is called.PublicationShim.init()
is called.PublicationShim.start()
is called.shutdown()
.initDocs
- array of 3 initialization Document
s to pass to
DriverShim.init()
, SubscriptionShim.init()
, and
PublicationShim.init()
DriverShim.init()
,
SubscriptionShim.init()
, and
PublicationShim.init()
java.lang.IllegalStateException
- if getRunningState()
returns other than STATE_STOPPED
java.lang.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" statusjava.lang.ClassNotFoundException
- if load()
has not yet been called, and a
ClassNotFoundException
is
thrown during the attempt to load the shimgetRunningState()
,
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
public org.w3c.dom.Document execute(org.w3c.dom.Document commandDocument, XmlQueryProcessor queryProcessor) throws java.lang.IllegalStateException, ShimException
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.commandDocument
- Document
containing commands for Subscriber shimqueryProcessor
- 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.Document
from the Subscriber shimjava.lang.IllegalStateException
- if getRunningState()
doesn't return STATE_RUNNING
ShimException
- if SubscriptionShim.execute()
throws a Throwable
getRunningState()
,
SubscriptionShim.execute(com.novell.nds.dirxml.driver.XmlDocument, com.novell.nds.dirxml.driver.XmlQueryProcessor)
,
XmlQueryProcessor.query(com.novell.nds.dirxml.driver.XmlDocument)
public org.w3c.dom.Document[] shutdown(org.w3c.dom.Document reasonDoc) throws java.lang.IllegalStateException, ShimException
DriverShim.shutdown()
method.
The start()
method must have been previously called.reasonDoc
- a Document
containing information on the purpose of the shutdown (may be null
)Document
s returned from DriverShim.shutdown()
and PublicationShim.start()
java.lang.IllegalStateException
- if getRunningState()
returns STATE_STOPPED
ShimException
- if DriverShim.shutdown()
throws a Throwable
DriverShim.shutdown(com.novell.nds.dirxml.driver.XmlDocument)
,
PublicationShim.start(com.novell.nds.dirxml.driver.XmlCommandProcessor)
,
getRunningState()
,
DRIVER_SHUTDOWN_RETURN
,
PUBLISHER_START_RETURN
public static void checkForFatalError(XmlDocument doc) throws FatalShimException
ShimHost
class, and is provided for
users of the ShimHost
class as well.doc
- XmlDocument
from shimFatalShimException
- if there is one or more <status> element with
the level attribute set to "fatal"public static void checkForFatalError(org.w3c.dom.Document returnDoc) throws FatalShimException
ShimHost
class, and is provided for
users of the ShimHost
class as well.returnDoc
- Document
from shimFatalShimException
- if there is one or more <status> element with
the level attribute set to "fatal"