|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.novell.nds.dirxml.shimhost.ShimHost
public class ShimHost
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
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 |
---|
public static final int DRIVER_INIT_DOC
DriverShim.init()
in start()
method's initDocs
parameter.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int SUBSCRIBER_INIT_DOC
SubscriptionShim.init()
in start()
method's initDocs
parameter.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int PUBLISHER_INIT_DOC
PublicationShim.init()
in start()
method's initDocs
parameter.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int DRIVER_INIT_RETURN
DriverShim.init()
in return from start()
method.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int SUBSCRIBER_INIT_RETURN
SubscriptionShim.init()
in return from start()
method.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int PUBLISHER_INIT_RETURN
PublicationShim.init()
in return from start()
method.
start(org.w3c.dom.Document[])
,
Constant Field Valuespublic static final int DRIVER_SHUTDOWN_RETURN
DriverShim.shutdown()
in return from shutdown()
method.
shutdown(org.w3c.dom.Document)
,
Constant Field Valuespublic static final int PUBLISHER_START_RETURN
PublicationShim.start()
in return from shutdown()
method.
shutdown(org.w3c.dom.Document)
,
Constant Field Valuespublic 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 String REMOTE_SHIM_CLASS_NAME
Constructor Detail |
---|
public ShimHost(String className) throws IllegalArgumentException, 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
class
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 constructionpublic ShimHost(String className, Trace tracer) throws IllegalArgumentException, 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 messages
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 constructionMethod Detail |
---|
public static void initialize()
public static void initialize(ClassLoader cl)
cl
- ClassLoader instance to use for loading shim classes.public static void cleanup()
public void validateClass() throws ClassNotFoundException
ClassNotFoundException
public String getClassName()
public int getRunningState()
STATE_STOPPED
,
STATE_RUNNING
,
STATE_FLAG_DRIVER_INITIALIZED
,
STATE_FLAG_SUBSCRIBER_INITIALIZED
,
STATE_FLAG_PUBLISHER_INITIALIZED
,
STATE_FLAG_IN_PUBLISHER_START
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 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
ClassNotFoundException
DriverShim
public Document getSchema(Document initDoc) throws IllegalStateException, IllegalArgumentException, ShimException, 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()
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 shimgetRunningState()
,
load()
,
DriverShim.getSchema(com.novell.nds.dirxml.driver.XmlDocument)
public Document[] start(Document[] initDocs) throws IllegalStateException, IllegalArgumentException, ShimException, 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()
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 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 Document execute(Document commandDocument, XmlQueryProcessor queryProcessor) throws 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 shim
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 Document[] shutdown(Document reasonDoc) throws 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()
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 shim
FatalShimException
- if there is one or more <status> element with
the level attribute set to "fatal"public static void checkForFatalError(Document returnDoc) throws FatalShimException
ShimHost
class, and is provided for
users of the ShimHost
class as well.
returnDoc
- Document
from shim
FatalShimException
- if there is one or more <status> element with
the level attribute set to "fatal"
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |