com.novell.nds.dirxml.job
Interface DriverInterface

public interface DriverInterface

Interface for job code to interact with the containing DirXML driver.

Field Summary

static int	START_OPTION_AUTO Parameter value for setDriverStartOption.
static int	START_OPTION_DISABLED Parameter value for setDriverStartOption.
static int	START_OPTION_MANUAL Parameter value for setDriverStartOption.

Method Summary

boolean	isDriverEnabled() Return true if the driver start option is auto or manual, false if driver is disabled.
boolean	isDriverRunning() Return true if the driver is running, false if not.
JobResult	queueEventDocument(XmlDocument doc) Place an XML document in the subscriber channel event queue (cache) for the driver.
JobResult	setDriverStartOption(int option, boolean suppressResync) Set the driver's start option to enable or disable the driver.
JobResult	startDriver(int maxWait) Start the driver associated with the job if it is not running.
JobResult	stopDriver() Stop a driver associated with the job if it is running.
XmlDocument	submitCommandDocument(XmlDocument doc) Submit a command document to the driver and return the result from the shim.
XmlDocument	submitEventDocument(XmlDocument doc) Submit an event document to the driver and return the results from processing.

Field Detail

START_OPTION_DISABLED

static final int START_OPTION_DISABLED

Parameter value for setDriverStartOption.

See Also:

Constant Field Values

START_OPTION_MANUAL

static final int START_OPTION_MANUAL

Parameter value for setDriverStartOption.

See Also:

Constant Field Values

START_OPTION_AUTO

static final int START_OPTION_AUTO

Parameter value for setDriverStartOption.

See Also:

Constant Field Values

Method Detail

isDriverRunning

boolean isDriverRunning()

Return true if the driver is running, false if not.

Returns:

true if driver is running.

isDriverEnabled

boolean isDriverEnabled()

Return true if the driver start option is auto or manual, false if driver is disabled.

Returns:

true if driver is enabled

setDriverStartOption

JobResult setDriverStartOption(int option,
                               boolean suppressResync)
                               throws IllegalArgumentException

Set the driver's start option to enable or disable the driver.

The job must have "configure" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessConfigure attribute.

Parameters:

option - START_OPTION_DISABLED, START_OPTION_MANUAL, or START_OPTION_AUTO.

suppressResync - if true and enabling driver, no automatic resync of the driver is performed

Throws:

IllegalArgumentException

queueEventDocument

JobResult queueEventDocument(XmlDocument doc)

Place an XML document in the subscriber channel event queue (cache) for the driver. The XML must consist of a top-level "nds" element containing a single "input" element. The content of the input element is arbitrary.

If the event document contains an XDS query command then the job must have "migrate app" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessMigrate attribute.

If the event document contains other than an XDS query command then the job must have "submit command" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessSubmitCommand attribute.

Parameters:

doc - document to queue

Returns:

success, warning or error information.

See Also:

CheckPrivileges

submitCommandDocument

XmlDocument submitCommandDocument(XmlDocument doc)

Submit a command document to the driver and return the result from the shim.

Command documents are submitted directly to the Subscriber channel of the driver, bypassing the event queue (cache). Command documents also bypass much of the normal Subscriber channel rule processing for events. The command documents are processed by the Command Transformation, the Schema Mapping, and the Output Transformation rules.

The job must have "submit command" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessSubmitCommand attribute.

Parameters:

doc - the command document

Returns:

the result document (will typically contain one or more status elements).

See Also:

CheckPrivileges

submitEventDocument

XmlDocument submitEventDocument(XmlDocument doc)

Submit an event document to the driver and return the results from processing.

This method submits the event document directly to the Subscriber channel of the driver, bypassing the event queue (cache). Event documents are processed using the normal Subscriber channel rule processing, including filtering, Event Transformation rule, and the add-related rules (Matching, Create, Placement).

The job must have "submit command" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessSubmitCommand attribute.

Parameters:

doc - the event document

Returns:

the result document (will typically contain one or more status elements).

See Also:

CheckPrivileges

startDriver

JobResult startDriver(int maxWait)

Start the driver associated with the job if it is not running.

The job must have "run" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessRun attribute.

Note: if maxWait is <= 0 then this method will return success before determining if the driver has actually started. It is then the caller's responsibility to check if the driver is running or not.

Parameters:

maxWait - maximum time to wait for driver to start (in seconds)

Returns:

success or error information. An error will be reported if the driver is already running, if the job has no associated driver, or if the job has insufficient rights to start the driver.

See Also:

CheckPrivileges

stopDriver

JobResult stopDriver()

Stop a driver associated with the job if it is running.

The job must have "run" privileges to the driver. This means the DirXML-Job object must be a trustee of the DirXML-Driver object and have write privileges to the DirXML-AccessRun attribute.

Returns:

success or error information. An error will be reported if the driver is not running, if the job has no associated driver, or if the job has insufficient rights to stop the driver.

See Also:

CheckPrivileges