SubscriptionShim init
Initializes the subcriber of the DirXML driver.
public 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 DirXML engine calls the init method to allow the Subscriber object to perform any channel-specific initialization necessary before beginning the execution of commands.
The initParameters argument contains an XML document with initialization data such as authentication information, driver-specific subscriber parameters, and the subscriber channel filter.
When the DirXML engine calls the SubscriptionShim 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\Subscriber">
<authentication-info>
<server>server.app:400</server>
<user>User1</user>
<password><!-- content suppressed --></password>
</authentication-info>
<driver-filter>
<allow-class class-name="User">
<allow-attr attr-name="Given Name"/>
<allow-attr attr-name="Surname"/>
<allow-attr attr-name="Telephone Number"/>
</allow-class>
</driver-filter>
<subscriber-options>
<sub-1 display-name="Sample Subscriber option">String for Subscriber</sub-1>
</subscriber-options>
<subscriber-state>
<current-association>6</current-association>
</subscriber-state>
</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 on the <init-params> element is the distinguished name of the DirXML-Subscriber object that corresponds to the driver’s Subscriber object. The DirXML-Subscriber object is the eDirectory object that contains the Subscriber channel filter and references to the Subscriber channel rules.
The content of the <authentication-info> element corresponds to the driver authentication parameters found in the DirXML-Driver 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 <subscriber-options> element corresponds to driver-specific options specified in the DirXML-Driver properties dialog. Driver-specific options are specified using an XML file that describes the options. See DriverShim init for an example XML file used with the skeleton driver. For information about the possible elements in this document, see subscriber-options.
The <subscriber-state> element contains state information that the skeleton driver writes at driver shutdown. (For more information , see DriverShim shutdown.
The <driver-filter> element contains the subscriber filter. This filter is a list of the classes and attributes for which the subscriber receives events. For information about the possible elements in the filter, see driver-filter.
The following code from the skeleton driver retrieves the subscriber parameters, checks the document for state information and configuration parameters, and then returns a status document.
public XmlDocument init(XmlDocument initParameters )
{
try
{
tracer.trace("init");
//get any non-authentication options from
//the init document
params = getShimParams(initParameters.getDocument(), "subscriber",SUBSCRIBER_PARAMS);
//Get any state that may have been passed in.
//The skeleton driver fakes associations to DirXML so
//that it appears more like a real driver
//see addHandler()
int assocState = params.getIntParam("current-association");
if (assocState != -1)
{
//setup our fake association for handling adds
currentAssociation = assocState;
}
//perform any other initialization that might be
//required.
return createSuccessDocument();
} catch (Throwable t)
{
//something bad happened...
return createStatusDocument(STATUS_FATAL, t.getMessage());
}
}
In the DirXML sample code, see the init method in the SolutionSubscriptionShim.java file and the SubscriptionShimImpl.java file.
The following code from the skeleton driver sends a DSTrace message, retrieves the subscriber parameters, and returns a status document.
XmlDocument * METHOD_CALL SkeletonSubscriber::init(
XmlDocument * initParameters)
{
try
{
common.tracer->trace("init");
//get any non-authentication options from the init document
params = common.getShimParams(initParameters->getDocument(),TEXT_SUBSCRIBER,SUBSCRIBER_PARAMS);
//Get any state that may have been passed in.
//The skeleton driver fakes associations to DirXML so that it appears
//more like a real driver. See addHandler()
int assocState = params->getIntParam(TEXT_CURRENT_ASSOCIATION);
if (assocState != -1)
{
//setup our fake association for handling adds
currentAssociation = assocState;
}
//perform any other initialization that might be required.
return common.setReturnDocument(common.createSuccessDocument());
} 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 DirXML sample code, see the init method in the SubcriptionShimImpl.cpp file.