com.novell.nds.dirxml.job
Class JobUtil

java.lang.Object
  com.novell.nds.dirxml.job.JobUtil

public abstract class JobUtil

extends Object

Collection of utility methods to make it easier to write a job.

Nested Class Summary

static class	JobUtil.Association Class representing the association value on an object that corresponds to a given driver.
static class	JobUtil.Instance Class encapsulating the information in an XDS instance element.
static class	JobUtil.StructuredValue Class to report values for structured eDirectory attribute syntaxes.

Constructor Summary

JobUtil()

Method Summary

static Element	constructXdsInputDocument() Construct an input document.
static Element	constructXdsInputDocument(String product, String productVersion, String contact) Construct an input document.
static Socket	createKMOSocket(String host, int port, String kmoName) Create a secure (SSL/TLS) client Socket based on Novell's NTLS socket implementation with the encryption keys and certificate from an eDirectory Key Material Object (KMO).
static String	generateEventID(String prefix) Construct an event-id string based on a prefix, the current time, and an event number.
static JobUtil.Association[]	getAssociationsForDriver(DirectoryObject object, DirectoryObject driver, JobManager manager) Get the associations on an eDirectory object that correspond to a driver.
static JobUtil.Association[]	getAssociationsForDriver(JobUtil.Instance instance, DirectoryObject driver) Get the associations from an Instance that correspond to a driver.
static String	getThrowableLongString(Throwable t) Get a String for a Throwable that has the stack backtrace info.
static String	getVersionFromManifest(String className) Get the "Implementation-Version" string from the jar file manifest.
static void	populateCommonEntryAttrs(Element element, JobUtil.Instance instance) Populate an element with command XDS entry attributes from an instance.
static Map	readAttributes(DirectoryObject entry, String[] attrNames, JobManager manager) Read attribute values from an eDirectory object.
static JobUtil.Instance	readEntry(DirectoryObject entry, String[] attrNames, JobManager manager) Read information from an eDirectory entry.
static JobResult	resultFromStatusElement(Element statusElement, JobManager manager) Allocate and populate a JobResult instance from the data in an XDS status element.
static JobResult[]	resultListToArray(List results) Utility method to convert JobResult instances in a List into an array.
static JobResult[]	resultsFromOutputDocument(Document outputDocument, JobManager manager) Return 0 or more JobResult instances based on <status> elements in an XDS output document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JobUtil

public JobUtil()

Method Detail

readEntry

public static JobUtil.Instance readEntry(DirectoryObject entry,
                                         String[] attrNames,
                                         JobManager manager)

Read information from an eDirectory entry.

Parameters:

entry - the eDirectory entry to read

attrNames - attributes whose values should be read. This may be null, indicating no values should be read, or it may have a single element of "*" indicating all attributes values should be read.

manager - query will be via manager.getCommandProcessor()

Returns:

encapsulation of information in the XDS instance element, or null if the entry couldn't be read.

readAttributes

public static Map readAttributes(DirectoryObject entry,
                                 String[] attrNames,
                                 JobManager manager)

Read attribute values from an eDirectory object.

The return value is a mapping from attribute names to values. The values are in the following form:

Simple attribute syntaxes: An array of Strings.
Structured attribute syntaxes: An array of StructuredValue objects.

Parameters:

entry - reference to eDir object

attrNames - array of attribute names (must not be null or empty, may have one entry of "*" meaning read all)

manager - query will be via manager.getCommandProcessor()

Returns:

mapping of attribute name to values. No values on the eDir object means there will be no entry for the attribute.

getAssociationsForDriver

public static JobUtil.Association[] getAssociationsForDriver(JobUtil.Instance instance,
                                                             DirectoryObject driver)

Get the associations from an Instance that correspond to a driver. The instance must have values for the DirXML-Associations attribute. The returned Association instances are abstractions of the association values. In particular, if an association value has no application key and is not disabled, it is not returned.

Parameters:

instance - eDirectory object representation obtained from readEntry()

driver - reference to the DirXML-Driver object.

Returns:

array of zero of more Association instances (will not be null)

getAssociationsForDriver

public static JobUtil.Association[] getAssociationsForDriver(DirectoryObject object,
                                                             DirectoryObject driver,
                                                             JobManager manager)

Get the associations on an eDirectory object that correspond to a driver. The returned Association instances are abstractions of the association values. In particular, if an association value has no application key and is not disabled, it is not returned.

Parameters:

object - reference to eDirectory object whose association values are to be returned

driver - reference to the DirXML-Driver object.

manager - query will be via manager.getCommandProcessor()

Returns:

array of zero of more Association instances (will not be null)

constructXdsInputDocument

public static Element constructXdsInputDocument()

Construct an input document. The resulting document is as follows:

 <nds dtd-version="2.0">
   <input/>
 </nds>
 

and the input Element is returned.

Returns:

input Element

constructXdsInputDocument

public static Element constructXdsInputDocument(String product,
                                                String productVersion,
                                                String contact)

Construct an input document. The resulting document is as follows:

 <nds dtd-version="2.0">
   <source>
     <product version="productVersion">product</product>
     <contact>contact</contact>
   </source>
   <input/>
 </nds>
 

and the input Element is returned.

Parameters:

product - product name (may be null)

productVersion - product version string (may be null)

contact - contact information (e.g., a URL string or email address) (may be null)

Returns:

<input> Element

populateCommonEntryAttrs

public static void populateCommonEntryAttrs(Element element,
                                            JobUtil.Instance instance)

Populate an element with command XDS entry attributes from an instance. This will populate "src-dn", "qualified-src-dn", "src-entry-id", and "class-name" if values for the XML attribute are found in the instance data.

Parameters:

element - XDS element to be populated (e.g., "modify", "add", etc.)

instance - encapsulation of entry data

resultFromStatusElement

public static JobResult resultFromStatusElement(Element statusElement,
                                                JobManager manager)

Allocate and populate a JobResult instance from the data in an XDS status element.

Status level mapping is as follows:

• "success"     -> JobResult.SUCCESS

• "retry"       -> JobResult.WARNING

• "warning"     -> JobResult.WARNING

• "error"       -> JobResult.ERROR

• "error"       -> JobResult.ERROR

• anything else -> JobResult.ERROR

Parameters:

statusElement - the status element

manager - used to allocate JobResult instance

Returns:

populated instance

resultsFromOutputDocument

public static JobResult[] resultsFromOutputDocument(Document outputDocument,
                                                    JobManager manager)

Return 0 or more JobResult instances based on <status> elements in an XDS output document. Uses resultFromStatusElement to do the heavy lifting.

Parameters:

outputDocument - XDS output document

manager - used to allocated JobResult instances

Returns:

null or an array of JobResult instances

See Also:

resultFromStatusElement(org.w3c.dom.Element,com.novell.nds.dirxml.job.JobManager)

generateEventID

public static String generateEventID(String prefix)

Construct an event-id string based on a prefix, the current time, and an event number. The event number is the number of generateEventID requests during the current second minus 1.

The string is of the form #CCYYMMDDHHmmss#0#.

Parameters:

prefix - value to prepend to generated event-id value

Returns:

event-id value

getVersionFromManifest

public static String getVersionFromManifest(String className)

Get the "Implementation-Version" string from the jar file manifest.

Parameters:

className - dot-delimited class name of job implementation

Returns:

the version string from the manifest, or "?.?.?.?" if the version couldn't be obtained.

resultListToArray

public static JobResult[] resultListToArray(List results)

Utility method to convert JobResult instances in a List into an array.

Parameters:

results - List of JobResult instances

Returns:

null if results == null or results.size() == 0, or an array of JobResult instances

createKMOSocket

public static Socket createKMOSocket(String host,
                                     int port,
                                     String kmoName)
                              throws IOException,
                                     UnknownHostException

Create a secure (SSL/TLS) client Socket based on Novell's NTLS socket implementation with the encryption keys and certificate from an eDirectory Key Material Object (KMO).

The kmoName parameter is not a DN; rather it is what is termed the "key pair" name - that part of the Key Material Object name before the '-' and server name.

Parameters:

host - host name or IP address

port - TCP port number on which to connect

kmoName - name of Key Material Object to use for encryption keys

Throws:

IOException - if an error occurs establishing the connection

UnknownHostException

getThrowableLongString

public static String getThrowableLongString(Throwable t)

Get a String for a Throwable that has the stack backtrace info. This is equivalent to:

 StringWriter	sw = new StringWriter();
 t.printStackTrace(new PrintWriter(sw, true));
 sw.flush();
 return sw.toString();
 

Parameters:

t - the Throwable object

Returns:

the string from t.printStackTrace