DriverShim shutdown
Shuts down the DirXML driver.
XmlDocument shutdown (XmlDocument
reason);
#include "NativeInterface.h"
XmlDocument * METHOD_CALL shutdown(
XmlDocument *reason);
Returns an XML document containing the results of the shutdown operation.
The DirXML engine calls this method on the subscriber thread to inform the driver that it is to cease all processing and shutdown in an orderly fashion. The shutdown method is responsible for informing the publisher (running on a different thread) that it must return from the PublicationShim start method. After the shutdown method returns, the DirXML engine waits for up to 30 seconds for the publisher thread to return from the start method.
The "reason" argument is intended so that the DirXML engine can pass an XML document detailing the reason for the shutdown (such as user action or server going down) but currently a null argument is passed. The return document is a status document detailing the success or failure of the operation. The following is an example return document from the skeleton DriverShim shutdown method:
<nds dtdversion="1.0" ndsversion="8.5">
<output>
<init-params>
<subscriber-state>
<current-association>6</current-association>
</subscriber-state>
</init-params>
<status level="success"/>
</output>
</nds>
This document contains a <subscriber-state> element. The skeleton Subscriber saves some state information between invocations and uses the return document from the shutdown method to cause the DirXML engine to write the state information. The engine returns the state information to the driver in the SubscriptionShim init method.
The following sample code from the skeleton driver calls a stop method on the publisher. It then returns an XmlDocument document that contains the status of the shutdown.
public XmlDocument shutdown(XmlDocument reason)
{
tracer.trace("shutdown");
//create an output document so the subscriber can
//write its state info
Element output = createOutputDocument();
subscriptionShim.setState(output);
// shutdown whatever needs shutting down
publicationShim.stop();
//add a successful status
addStatusElement(output,STATUS_SUCCESS,null,null);
//return the status and state to DirXML
return new XmlDocument(output.getOwnerDocument());
}
In the DirXML sample code, see the shutdown method in the SolutionDriverShim.java file and the DriverShimImpl.java file.
The following sample code from the skeleton driver sends a trace message, calls a stop method on the publisher. It then returns to the DirXML engine an XmlDocument that contains the status of the shutdown.
XmlDocument * METHOD_CALL CSkeletonDriver::shutdown(XmlDocument * reason)
{
try
{
common.tracer->trace("shutdown");
common.tracer->trace(reason);
//create an output document so the subscriber can write its state info
Element * output = NdsDtd_newOutputDocument();
subscriptionShim->setState(output);
// shutdown whatever needs shutting down
publicationShim->stop();
//add a successful status
NdsDtd_addStatus(output,STATUS_LEVEL_SUCCESS,0,0);
//return the status and state to DirXML
return common.setReturnDocument(output->getOwnerDocument());
} catch (...)
{
//something bad happened...
return common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,MSG_BAD));
}
}
In the DirXML sample code, see the shutdown method in the DriverShimImpl.cpp file.