DriverShim init
Initializes the DirXML driver object.
XmlDocument init(
XmlDocument initParameters);
#include "NativeInterface.h"
XmlDocument * METHOD_CALL init(
XmlDocument *initParameters);
Returns an XML document containing a status report on the initialization process. The status can be "success", "warning", "error" or "fatal". If "fatal" is returned, the driver start is aborted.
The init method in the driver is typically where the subscriber and publisher objects are created. It is also where the initialization parameters are parsed for channel-independent configuration parameters such as application server name or IP address and for authentication parameters required for logging in to the application.
The initParameters argument is an XML document containing initialization data such as authentication information, driver-specific parameters, and driver state. The format of individual driver-specific parameters and driver state are specific to your driver.
When the DirXML engine calls the DriverShim init method, it sends an XML document similar to the following.
<nds dtdversion="1.0" ndsversion="8.5">
<source>
<product version="1.0">DirXML</product>
<contact>Novell, Inc.</contact>
</source>
<input>
<init-params src-dn="\PERIN-TAO\novell\Driver Set\Java Skeleton Driver">
<authentication-info>
<server>server.app:400</server>
<user>User1</user>
<password><!-- content suppressed --></password>
</authentication-info>
<driver-options>
<option-1 display-name="Sample String option">
This is a string</option-1>
<option-2 display-name="Sample int option (enter
an integer)">10</option-2>
</driver-options>
</init-params>
</input>
</nds>
Most of the information in the initialization document corresponds to information configured using ConsoleOne in the DirXML-Driver object properties dialog.
The src-dn attribute in the <init-params> element is the distinguished name of the DirXML-Driver object that is used to contain configuration information for the skeleton driver.
The content of the <authentication-info> element corresponds to the driver authentication parameters found in the properties dialog. The content of the <password> element is suppressed because the trace facility suppresses sensitive data (as defined by DirXML). The actual password value is available to the driver.
The content of the <driver-options> element corresponds to driver-specific options specified in the properties dialog. Driver-specific options are specified using an XML file that describes the options. The following example is an XML file used for the skeleton driver:
<?xml version="1.0" encoding="UTF-8"?>
<driver-config name="Skeleton Driver">
<driver-options>
<option-1 display-name="Sample String option">This is a string</option-1>
<option-2 display-name="Sample int option (enter an integer)">10</option-2>
</driver-options>
<subscriber-options>
<sub-1 display-name="Sample Subscriber option">String for Subscriber</sub-1>
</subscriber-options>
<publisher-options>
<pub-1 display-name="Sample Publisher option">String for Publisher</pub-1>
<polling-interval display-name="Polling interval in seconds">4</polling-interval>
</publisher-options>
</driver-config>
Using such an XML file to describe driver-specific configuration parameters allows the administrator to easily configure your driver using existing eDirectory management tools such as ConsoleOne.
The driver must return a status document as the response to the init method. The following are examples of potential status documents.
<nds dtdversion="1.0" ndsversion="8.5">
<output>
<status level="success"/>
</output>
</nds>
<nds dtdversion="1.0" ndsversion="8.5">
<output>
<status level="warning">No authentication information</status>
</output>
</nds>
The following code from the Java skeleton driver sets up a trace message, gets the authentication and configuration parameters from the initParameters document, creates the subscriber and publisher objects, and returns a status document.
public XmlDocument init(XmlDocument initParameters )
{
try
{
tracer.trace("init");
//create an output document for returning
//status to DirXML
Element output = createOutputDocument();
//setup the shared authentication information
authParams = getAuthenticationParams( initParameters.getDocument());
//If we don’t have any authentication parameters,
//report a warning. This is intended to serve as an
//example of how to report a warning or an error.
//A real driver may or may not need information
//in the authentication parameters.
if (authParams.authenticationId == null &&
authParams.authenticationContext == null &&
authParams.applicationPassword == null)
{
//a real driver would probably want to report
//a fatal error if required parameters
//are not supplied
addStatusElement(output,STATUS_WARNING,"No authentication information",null);
}
//get any non-authentication options from
//the init document
params = getShimParams(initParameters.getDocument(), "driver",DRIVER_PARAMS);
//create the objects that do the real work
subscriptionShim = new SkeletonSubscriptionShim (authParams);
publicationShim = new SkeletonPublicationShim (authParams);
//if we didn’t already add a status element,
//add a success
if (output.getElementsByTagName("status").item(0) == null)
{
addStatusElement(output,STATUS_SUCCESS,null,null);
}
//return the status document
return new XmlDocument(output.getOwnerDocument());
} catch (Throwable t)
{
//something bad happened...
return createStatusDocument(STATUS_FATAL, t.getMessage());
}
}
In the DirXML sample code, see the init method in the SolutionDriverShim.java file and the DriverShimImpl.java file.
The following code from the skeleton driver sets up a trace message, gets the authentication and configuration parameters from the initParmeters document, creates the subscriber and publisher objects, and returns a status document.
XmlDocument * METHOD_CALL CSkeletonDriver::init(
XmlDocument * initParameters)
{
try
{
common.tracer->trace("init");
//NOTE: only trace this here to test the trace facility.
//The document is already traced by the engine
//so it will appear twice in the trace screen
common.tracer->trace(initParameters);
//create an output document for returning status to DirXML
Element * output = NdsDtd_newOutputDocument();
//setup the shared authentication information
authParams = common.getAuthenticationParams(initParameters->getDocument());
//If we don't have any authentication parameters, report a warning.
//This is intended to serve as an example of how to report a warning
//or an error. A real driver may or may not need information
//in the authentication parameters.
if (authParams->authenticationId == 0 &&
authParams->authenticationContext == 0 &&
authParams->applicationPassword == 0)
{
//A real driver would probably want to report a fatal error if required
//parameters are not supplied
NdsDtd_addStatus(output,STATUS_LEVEL_WARNING,MSG_NO_AUTH_INFO,0);
}
//get any non-authentication options from the init document
params = common.getShimParams(initParameters->getDocument(),TEXT_DRIVER,DRIVER_PARAMS);
//create the objects that do the real work
subscriptionShim = new SkeletonSubscriber(authParams);
publicationShim = new SkeletonPublisher(authParams);
//if we didn't already add a status element, add a success
if (output->getElementsByTagName(common.ndsDtd->TAG_STATUS)->item(0) == 0)
{
NdsDtd_addStatus(output,STATUS_LEVEL_SUCCESS,0,0);
}
//return the status document
return common.setReturnDocument(output->getOwnerDocument());
} catch (ShimException e)
{
return common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,e.getMessage()));
} catch (...)
{
//something bad happened...
return common.setReturnDocument(common.createStatusDocument(STATUS_LEVEL_FATAL,MSG_BAD));
}
}
In the sample code, see the init method in the DriverShimImpl file and the parseInitParams method in the CommonImpl.cpp file.