PublicationShim start
Publishes data from the external application to eDirectory.
public XmlDocument start (
XmlCommandProcessor execute)
#include "NativeInterface.h"
XmlDocument * METHOD_CALL start (
XmlCommandProcessor *execute);
The DirXML engine calls the start method to allow the driver to monitor the application and publish application events (changes) to the DirXML engine. The publisher should not return from the start method until instructed to do so from the DriverShim shutdown method. An exception to this rule is if a fatal error occurs. If the publisher returns from the start method before the DriverShim shutdown method is called, the DirXML engine shuts down the driver.
The execute argument is an interface through which the publisher submits event documents to the DirXML engine. The XmlCommandProcessor interface has a single method named execute with the following syntax.
XmlDocument execute(
XmlDocument doc,
XmlQueryProcessor query);
XmlDocument * METHOD_CALL execute(
XmlDocument *doc,
XmlQueryProcessor *query);
The publisher constructs an XML document describing the application event and submits it through the execute method, along with an interface that the DirXML engine can use to query back to the publisher if the engine determines that it requires additional data. The DirXML engine returns an XML document containing the status of the event processing.
The skeleton driver does not publish any information to DirXML other than status documents should an error occur. However the VRTest driver does publish events, and therefore, examples from the VRTest driver will be used in this section to illustrate the publication of events. For the format of all possible input and output documents, see Section 7.0, eDirectory DTD Commands and Events.
The VRTest driver published the following document to the DirXML engine in response to a VRTest application change.
<nds dtdversion="1.0" ndsversion="8.5">
<input>
<add class-name="User Object" src-dn="\novell\JJones">
<association>27</association>
<add-attr attr-name="Family Name">
<value>James</value>
</add-attr>
<add-attr attr-name="First Name">
<value>Jones</value>
</add-attr>
<add-attr attr-name="Telephone">
<value>(801) 555-1234</value>
</add-attr>
</add>
</input>
</nds>
The above document indicates that an object of application class "User Object" with three attributes was added to the VRTest application.
The DirXML engine responded with the following document.
<nds dtdversion="1.0" ndsversion="8.5">
<source>
<product version="1.0">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<output>
<status event-id="" level="success"></status>
</output>
</nds>
The response document indicates that the event was processed by the engine according to any rules in place and that no errors occurred.
All events submitted to the DirXML engine must have an <association> value. For more information on the elements that must be included in an add event, see add.
When the object corresponding to the example above was later modified, the VRTest publisher sent the following document to the DirXML engine.
<nds dtdversion="1.0" ndsversion="8.5">
<input>
<modify class-name="User Object" src-dn="\novell\JJones">
<association>27</association>
<modify-attr attr-name="Telephone">
<add-value>
<value>(801) 555-1235</value>
</add-value>
<add-value>
<value>(801) 555-1236</value>
</add-value>
</modify-attr>
</modify>
</input>
</nds>
The above document informs DirXML that the application object associated with the eDirectory object containing the association value "27" had two values added to its "Telephone" attribute.
For more information on the elements that must be included in a modify event, see modify.
If the application object is later deleted, the publisher submits the following event document.
<nds dtdversion="1.0" ndsversion="8.5">
<input>
<delete class-name="User" src-dn="\novell\JJones">
<association>27</association>
</delete>
</input>
</nds>
For more information on the elements that must be included in a delete event, see delete.
The following code from the Java skeleton driver sends messages to DSTrace, checks to see if it has received a stop request, and returns an XMLDocument.
public XmlDocument start( XmlCommandProcessor execute)
{
//NOTE: this implements a polling method of communication with the
//application. This may not be appropriate if the application supports
//an event notification system
tracer.trace("start");
//loop until we’re told to shutdown (or some fatal error occurs)
while(!shutdown)
{
// skeleton implementation just wakes up every so often to
// see if it needs to shutdown and return.
try
{
tracer.trace("polling...");
//In a real driver, we’d do whatever was necessary to ask the
//application what changed and build an input document to publish
//the change events to DirXML.
//wait for subscriber channel thread to wake us up, or for polling
//interval to expire.
//NOTE: the use of the semaphore is highly recommended. It prevents
//a long polling interval from interfering with the orderly
//shutdown of the driver.
synchronized(semaphore)
{
//our pollingInterval value is in seconds,
//The Object.wait() takes milliseconds
semaphore.wait(pollingInterval * 1000);
}
}
catch(InterruptedException ie)
{
}
}
tracer.trace("stopping");
return createSuccessDocument();
}
In the DirXML sample code, see the start method in the SolutionPublicationShim.java file and the PublicationShimImpl.java file.
The following code from the skeleton driver sends messages to DSTrace, checks to see if it has received a stop request, and returns an XmlDocument.
XmlDocument * METHOD_CALL SkeletonPublisher::start(
XmlCommandProcessor * ndsExecute)
{
try
{
//NOTE: this implements a polling method of communication with the
//application. This may not be appropriate if the application
//supports an event notification system
common.tracer->trace("start");
//loop until we're told to shutdown (or some fatal error occurs)
while(!shutdown && !aborted)
{
try
{
// skeleton implementation just wakes up every so often to
// see if it needs to shutdown and return.
common.tracer->trace("polling...");
//In a real driver, we'd do whatever was necessary to ask
//the application what changed and build an input document
//to publish the change events to DirXML.
//wait for subscriber channel thread to wake us up, or for
//polling interval to expire.
//NOTE: the use of the semaphore is highly recommended. It
//prevents a long polling interval from interfering with the
//orderly shutdown of the driver.
waitSemaphore(semaphore,pollingInterval * 1000);
} catch (ShimException e)
{
//some sort of error happened...publish the error to DirXML
//but don't quit (definitely don't quit if all that happened
//is we lost communication with the app...
//we should simply try and reestablish it later)
Element * input = NdsDtd_newInputDocument();
NdsDtd_addStatus(input,STATUS_LEVEL_ERROR,e.getMessage(),0);
XmlDocument * pubDoc = XmlDocument_newFromDOM(input->getOwnerDocument());
ndsExecute->execute(pubDoc,this);
XmlDocument_destroy(pubDoc);
//NOTE that we must destroy the XmlDocument and the DOM
//document separately. The XmlDocument doesn't take
//ownership of the DOM document
input->getOwnerDocument()->destroy();
//loop around to try again
}
}
if (!aborted)
{
common.tracer->trace("stopping");
common.setReturnDocument(common.createSuccessDocument());
} else
{
common.tracer->trace("aborting");
common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,MSG_ABORTED));
}
return common.getReturnDocument();
} catch (...)
{
//something bad happened...
return common.setReturnDocument(common.createStatusDocument (STATUS_LEVEL_FATAL,MSG_BAD));
}
}
In the DirXML sample code, see the start method in the PublicationShimImpl.cpp file.