DSMLv2 Parser

IBM Tivoli Directory Integrator

DSMLv2 Parser

The Directory Services Markup Language v1.0 (DSMLv1) enables the representation of directory structural information as an XML document. DSMLv2 goes further, providing a method for expressing directory queries and updates (and the results of these operations) as XML documents. DSMLv2 documents can be used in a variety of ways. IBM TDI provides a Parser that can parse and create DSMLv2 request and response messages.

The DSMLv2 Parser is initialized with a DSMLv2 batch request or DSMLv2 batch response. Individual calls to read or write Entries will result in parsing or creation of individual DSML requests or responses (as parts of the batch request or response).

The Parser supports Delta tagging at the Entry level and the Attribute level. See also Multiple Attribute modifications.

Modes

The DSMLv2 Parser operates either in Server or in Client mode:

In Server mode the Parser reads and parses DSMLv2 requests; and writes and creates DSMLv2 responses
In Client mode the Parser reads and parses DSMLv2 responses; and writes and creates DSMLv2 requests.

Operations

The DSMLv2 Parser supports Modify, Add, Delete, Search, ModifyDN, Compare, Auth and Extended operations.

Attention: The following TDI 6.0 DSMLv2 Parser custom helper objects from the ITIM DSML library are no longer supported:

dsml.request - for all request operations.
dsml.response - for all response operations.

Modify Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Modify Requests:

Table 37.

Attribute Value

dsml.operation set to "modifyRequest"
dsml.base holds the "dn" XML attribute of the DSML "modifyRequest" element
$dn holds the "dn" XML attribute of the DSML "modifyRequest" element

Attribute	Value
dsml.operation	set to "modifyRequest"
dsml.base	holds the "dn" XML attribute of the DSML "modifyRequest" element
$dn	holds the "dn" XML attribute of the DSML "modifyRequest" element

Additionally, for each modification item: a TDI attribute named as the "name" XML attribute of the DSML "modification" element, with the values specified for the "modification" DSML element and TDI attribute's operation set as the "operation" XML attribute of the DSML "modification" element.

Modify Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Modify Responses:

Table 38.

Attribute Value

dsml.operation modifyResponse
$dn holds the "matchedDN" XML attribute of the DSML "modifyResponse" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "addResponse" element

Attribute	Value
dsml.operation	modifyResponse
$dn	holds the "matchedDN" XML attribute of the DSML "modifyResponse" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "addResponse" element

Search Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Search Requests:

Table 39.

Attribute Value

dsml.operation set to "searchRequest"
$dn holds the "matchedDN" XML attribute of the DSML "compareResponse" element
dsml.base holds the "dn" XML attribute of the DSML "searchRequest" element
dsml.scope holds the value of the "scope" attribute of the DSML "searchRequest" element
dsml.filter the LDAP filter that corresponds to the "filter" element of the DSML request
dsml.attributes the value of this attribute is a Vector or String whose elements hold the names of the attributes listed in the "attributes" element of the DSML request.
dsml.derefAliases holds the value of the "derefAliases" attribute of the DSML "searchRequest" element
dsml.sizeLimit holds the value of the "sizeLimit" attribute of the DSML "searchRequest" element
dsml.timeLimit holds the value of the "timeLimit" attribute of the DSML "searchRequest" element
dsml.typesOnly holds the value of the "typesOnly" attribute of the DSML "searchRequest" element

Attribute	Value
dsml.operation	set to "searchRequest"
$dn	holds the "matchedDN" XML attribute of the DSML "compareResponse" element
dsml.base	holds the "dn" XML attribute of the DSML "searchRequest" element
dsml.scope	holds the value of the "scope" attribute of the DSML "searchRequest" element
dsml.filter	the LDAP filter that corresponds to the "filter" element of the DSML request
dsml.attributes	the value of this attribute is a Vector or String whose elements hold the names of the attributes listed in the "attributes" element of the DSML request.
dsml.derefAliases	holds the value of the "derefAliases" attribute of the DSML "searchRequest" element
dsml.sizeLimit	holds the value of the "sizeLimit" attribute of the DSML "searchRequest" element
dsml.timeLimit	holds the value of the "timeLimit" attribute of the DSML "searchRequest" element
dsml.typesOnly	holds the value of the "typesOnly" attribute of the DSML "searchRequest" element

Search Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Search Responses:

Table 40.

Attribute Value

dsml.operation set to "searchResponse"
$dn holds the "matchedDN" XML attribute of the DSML "searchResultDone" element of the DSML response
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
resultEntries a multi-valued attribute, each of its values is a TDI Entry whose attributes correspond to the "attr" elements of the corresponding "searchResultEntry" element.
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.

Attribute	Value
dsml.operation	set to "searchResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "searchResultDone" element of the DSML response
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
resultEntries	a multi-valued attribute, each of its values is a TDI Entry whose attributes correspond to the "attr" elements of the corresponding "searchResultEntry" element.
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.

Add Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Add Requests:

Table 41.

Attribute Value

dsml.operation set to "addRequest"
dsml.base holds the "dn" XML attribute of the DSML "addRequest" element
$dn holds the "dn" XML attribute of the DSML "addRequest" element

Attribute	Value
dsml.operation	set to "addRequest"
dsml.base	holds the "dn" XML attribute of the DSML "addRequest" element
$dn	holds the "dn" XML attribute of the DSML "addRequest" element

Additionally, for each DSML attr element: a TDI Attribute named as the "name" XML attribute of the DSML "attr" element and as values specified for the "attr" DSML element.

Add Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Add Responses:

Table 42.

Attribute Value

dsml.operation set to "addResponse"
"$dn holds the "matchedDN" XML attribute of the DSML "addResponse" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "addResponse" element

Attribute	Value
dsml.operation	set to "addResponse"
"$dn	holds the "matchedDN" XML attribute of the DSML "addResponse" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "addResponse" element

Delete Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Delete Requests:

Table 43.

Attribute Value

dsml.operation set to "deleteRequest"
dsml.base holds the "dn" XML attribute of the DSML "delRequest" element
$dn holds the "dn" XML attribute of the DSML "delRequest" element

Attribute	Value
dsml.operation	set to "deleteRequest"
dsml.base	holds the "dn" XML attribute of the DSML "delRequest" element
$dn	holds the "dn" XML attribute of the DSML "delRequest" element

Delete Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Delete Responses:

Table 44.

Attribute Value

dsml.operation set to "deleteResponse"
$dn holds the "matchedDN" XML attribute of the DSML "delRequest" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "addResponse" element

Attribute	Value
dsml.operation	set to "deleteResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "delRequest" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "addResponse" element

ModifyDN Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for ModifyDN Requests:

Table 45.

Attribute Value

dsml.operation set to "modDnRequest"
dsml.base holds the "dn" XML attribute of the DSML "modDNRequest" element
$dn holds the "dn" XML attribute of the DSML "modDNRequest" element
newrdn holds the "newrdn" XML attribute of the DSML "modDNRequest" element
dsml.newSuperior holds the "newSuperior" XML attribute of the DSML "modDNRequest" element
dsml.deleteOldRDN holds the "deleteoldrdn" XML attribute of the DSML "modDNRequest" element

Attribute	Value
dsml.operation	set to "modDnRequest"
dsml.base	holds the "dn" XML attribute of the DSML "modDNRequest" element
$dn	holds the "dn" XML attribute of the DSML "modDNRequest" element
newrdn	holds the "newrdn" XML attribute of the DSML "modDNRequest" element
dsml.newSuperior	holds the "newSuperior" XML attribute of the DSML "modDNRequest" element
dsml.deleteOldRDN	holds the "deleteoldrdn" XML attribute of the DSML "modDNRequest" element

ModifyDN Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for ModifyDN Responses:

Table 46.

Attribute Value

dsml.operation set to "modDnResponse"
$dn holds the "matchedDN" XML attribute of the DSML "modDNResponse" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "addResponse" element

Attribute	Value
dsml.operation	set to "modDnResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "modDNResponse" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "addResponse" element

Compare Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Compare Requests:

Table 47.

Attribute Value

dsml.operation set to "compareRequest"
dsml.base holds the "dn" XML attribute of the DSML "compareRequest" element
$dn holds the "dn" XML attribute of the DSML "compareRequest" element
dsml.compare_name holds the "name" XML attribute of the "assertion" element of the DSML request
dsml.compare_value holds the value of the "assertion" element of the DSML request

Attribute	Value
dsml.operation	set to "compareRequest"
dsml.base	holds the "dn" XML attribute of the DSML "compareRequest" element
$dn	holds the "dn" XML attribute of the DSML "compareRequest" element
dsml.compare_name	holds the "name" XML attribute of the "assertion" element of the DSML request
dsml.compare_value	holds the value of the "assertion" element of the DSML request

Compare Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Compare Responses:

Table 48.

Attribute Value

dsml.operation set to "compareResponse"
$dn holds the "matchedDN" XML attribute of the DSML "compareResponse" element
dsml.compare_result either "true" of "false" depending on whether the compare found match or not. When the Parser is used to create a DSML response, this attribute is required and depending on its value the Parser sets the right result code value.
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "addResponse" element

Attribute	Value
dsml.operation	set to "compareResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "compareResponse" element
dsml.compare_result	either "true" of "false" depending on whether the compare found match or not. When the Parser is used to create a DSML response, this attribute is required and depending on its value the Parser sets the right result code value.
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "addResponse" element

Auth Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Auth Requests:

Table 49.

Attribute Value

dsml.operation set to "authRequest"
dsml.principal holds the "principal" XML attribute of the DSML "authRequest" element

Attribute	Value
dsml.operation	set to "authRequest"
dsml.principal	holds the "principal" XML attribute of the DSML "authRequest" element

Auth Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Auth Responses:

Table 50.

Attribute Value

dsml.operation set to " authResponse"
$dn holds the "matchedDN" XML attribute of the DSML "authResponse" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response.
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "authResponse" element

Attribute	Value
dsml.operation	set to " authResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "authResponse" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response.
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "authResponse" element

Extended Request

Entries with the following structure are parsed (on read) and created (on write) by the parser for Extended Requests:

Table 51.

Attribute Value

dsml.operation set to "extendedRequest"
dsml.extended.requestname holds the "requestName" XML attribute of the DSML "extendedRequest" element
dsml.extended.requestvalue holds the "requestValue" XML attribute of the DSML "extendedRequest" element

Attribute	Value
dsml.operation	set to "extendedRequest"
dsml.extended.requestname	holds the "requestName" XML attribute of the DSML "extendedRequest" element
dsml.extended.requestvalue	holds the "requestValue" XML attribute of the DSML "extendedRequest" element

Extended Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Extended Response:

Table 52.

Attribute Value

dsml.operation set to "extendedResponse"
$dn holds the "matchedDN" XML attribute of the DSML "extendedResponse" element
dsml.resultcode holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral holds a vector containing all referral URIs of the DSML "extendedResponse" element
dsml.responseName holds the "responseName" XML attribute of the DSML "extendedResponse" element
dsml.response holds byte array containing string which represents the response from an "extendedResponse" operation

Attribute	Value
dsml.operation	set to "extendedResponse"
$dn	holds the "matchedDN" XML attribute of the DSML "extendedResponse" element
dsml.resultcode	holds the "code" XML attribute of the "resultCode" XML element of the DSML response
dsml.resultdescr	holds the "descr" XML attribute of the "resultCode" XML element of the DSML response
dsml.error	the presence of this attribute indicates an error condition and holds the value of the "errorMessage" XML element of the DSML response
dsml.exception	holds a javax.naming.NamingException object that is used to automatically fill in the "code" and "descr" XML attributes of the "resultCode" XML element of the DSML response; if this attribute is specified, any values set to the "dsml.resultcode" and "dsml.resultdescr" Entry Attributes are ignored and replaced with data retrieved through the exception object.
dsml.referral	holds a vector containing all referral URIs of the DSML "extendedResponse" element
dsml.responseName	holds the "responseName" XML attribute of the DSML "extendedResponse" element
dsml.response	holds byte array containing string which represents the response from an "extendedResponse" operation

All invalid XML characters (as per the XML specification) are removed from the "dsml.error" Entry Attribute before serializing this attribute into DSML.

Error Response

Entries with the following structure are parsed (on read) and created (on write) by the parser for Error Response:

Table 53.

Attribute Value

dsml.operation set to "errorResponse"
dsml.errorType holds the value of the "type" XML attribute of the DSML response XML element; must be one of "notAttempted", "couldNotConnect", "connectionClosed", "malformedRequest", "gatewayInternalError", "authenticationFailed", "unresolvableURI" or "other"
dsml.message holds the text value of the "message" XML element of the DSML response
dsml.details holds the value of the "detail" XML element of the DSML response

Attribute	Value
dsml.operation	set to "errorResponse"
dsml.errorType	holds the value of the "type" XML attribute of the DSML response XML element; must be one of "notAttempted", "couldNotConnect", "connectionClosed", "malformedRequest", "gatewayInternalError", "authenticationFailed", "unresolvableURI" or "other"
dsml.message	holds the text value of the "message" XML element of the DSML response
dsml.details	holds the value of the "detail" XML element of the DSML response

Binary and non-String Attributes

When parsing DSML messages, attributes tagged as binary by the Binary Attributes Parser parameter are Base64 decoded, that is, the string value from the DSML message is Base64 decoded to Java byte array.

When creating DSML messages, all Attributes whose value is Java byte array are Base64 encoded to String before being written in the DSML message.

If when creating a DSML message an Attribute is passed whose value's type is neither String nor Java byte array, the value is converted to String by calling the object's "toString()" method and this String value is written in the DSML message.

Optional Attributes

The following optional attributes, when present, are parsed (on read) and created (on write) by the parser for all DSMLv2 Requests and Responses:

Table 54.

Attribute Value

dsml.requestID corresponds to the DSMLv2 "requestID" attribute.
dsml.controls holds Vector of raw com.ibm.ldap.dsml.DsmlControl objects.

Attribute	Value
dsml.requestID	corresponds to the DSMLv2 "requestID" attribute.
dsml.controls	holds Vector of raw com.ibm.ldap.dsml.DsmlControl objects.

DSMLv2 controls must be Base64 encoded

When reading, the Parser expects the values of DSMLv2 controls to be Base64 encoded. For example instead of a control element like this one:

<control type="1.2.840.113556.1.4.619" criticality="true">   <controlValue xsi:type="xsd:string">mycontrolvalue</controlValue> 
</control>

we need to provide a control element like the following:

<control type="1.2.840.113556.1.4.619" criticality="true">     <controlValue xsi:type="xsd:base64Binary">bXljb250cm9sdmFsdWU==</controlValue> 
</control>

This is a limitation of the underlying DSML library from IBM Directory Server (com.ibm.ldap.dsml.*). The DSMLv2 XML Schema (http://www.oasis-open.org/committees/dsml/docs/DSMLv2.xsd) allows controlValue elements to be of xsd:anyType. However, the IBM DS DSMLv2 library (obtained from TDS 6.1) ignores the xsi:type attribute and always attempts to base64 decode the value.

Setting result code and result description

When setting the "dsml.resultcode" Attribute for DSML Response messages, allowed types are: java.lang.Integer and java.lang.String containing an integer value as string. This value corresponds to the integer "code" XML attribute of the "resultCode" DSML element and it is required by the DSMLv2 specification.

We can optionally set the "dsml.resultdescr" Attribute for DSML Response messages. This value corresponds to the "descr" XML attribute of the "resultCode" DSML element. It is not required by the DSMLv2 specification. When you assign a value to this attribute it is placed in the DSML response as is - no validation of the value (which is an enumerated string is done) and no check is performed whether this value corresponds to the mandatory integer "dsml.resultcode" Attribute.

The "code" and "descr" XML attributes of the "resultCode" DSML element can also be set through the "dsml.exception" Entry Attribute for DSML Response messages. This attribute can only accept javax.naming. NamingException objects. When "dsml.exception" attribute is set, the "code" and "descr" XML attributes of the "resultCode" DSML element are overwritten with new values extracted from the exception object. For example when the "dsml.exception" attribute is set to a javax.naming.AuthenticationException object, the "code" attribute will be set to the LDAP code of "49" and the "descr" attribute will be set to the LDAP description "inappropriateAuthentication".

Multiple Attribute modifications

The DSMLv2 Parser (and LDIF Parser) does not support multiple modifications over a single Attribute - the values from a modification are accumulated in the Attribute and the operation from the last modification is set as the operation tag for the Attribute. Therefore, the Parsers need to merge the modifications in an Entry in such way that the resulting Attribute modification be equivalent to the modifications for that Attribute in the modify operation. This can be achieved by using Attribute.ATTRIBUTE_MOD - a TDI-specific tagging at the Attribute level and by using AttributeValue level tagging - AttributeValue.AV_ADD, AttributeValue.AV_DELETE.

The following data flow rules will be used when accumulating modifications in an Attribute object:

On modification "Add" - the value(s) will be added with AttributeValue.AV_ADD to the Attribute; also the Attribute will be tagged as Attribute.ATTRIBUTE_MOD unless it is already tagged as Attribute.ATTRIBUTE_REPLACE
If the Attribute is already tagged with Attribute.ATTRIBUTE_REPLACE in a previous modification this tag will not be changed
On modification "Delete" with value(s) - the value(s) will be added with AttributeValue.AV_DELETE to the Attribute; also the Attribute will be tagged as Attribute.ATTRIBUTE_MOD unless it is already tagged as Attribute.ATTRIBUTE_REPLACE; if the Attribute is tagged as Attribute.ATTRIBUTE_REPLACE for each value in the "Delete" modification the value will be removed from the Attribute if that value is present in the Attribute
On modification "Delete" without values - the Attribute values from previous modifications will be cleared and the Attribute will be tagged as Attribute.ATTRIBUTE_REPLACE
On modification "Replace" - the Attribute values from previous modifications will be cleared and the new ones will be added; also the Attribute will be tagged as Attribute.ATTRIBUTE_REPLACE.

Configuration

The Parser needs the following parameters:

Character Encoding

Specifies the XML character encoding; for example, UTF-8 or ASCII.

This Parser extends the Simple XML Parser; therefore, the same notices with regards to Character Encoding apply.

Mode

Specifies whether the Parser operates in Server or in Client mode - possible values are "Server" and "Client". In Server mode, requests are read and responses are written. In Client mode, requests are written and responses are read.

Binary Attributes

Specifies a comma delimited list of attributes that will be treated by the Parser as binary attributes.

The following attributes are specified as binary by default (but we can change this list):

photo
personalSignature
audio
jpegPhoto
javaSerializedData
thumbnailPhoto
thumbnailLogo
userPassword
userCertificate
authorityRevocationList
certificateRevocationList
crossCertificatePair
x500UniqueIdentifier
objectGUID
objectSid

On Error

A BatchRequest element can contain the XML-attribute onError, which determines how the server responds to failures while processing request elements. The valid values are: exit and resume. The default value is exit.

Processing

Sets the value of the "processing" DSML attribute for Batch Requests.

Response Order

Influences how the server orders individual responses within the BatchResponse. The values of this parameter are sequential and unordered. The default value is sequential. If the Response Order value is set to sequential, the server must return a BatchResponse in which the individual responses maintain a positional correspondence with the individual requests.

Omit XML Declaration

Determines whether XML declaration omitting is enabled or disabled. By default, this parameter is disabled.

Indent Output

If checked, the output will be indented according to the depth of the statement lines. This is cosmetic only; it has no bearing upon the semantic content of the output file.

Soap Binding

When turned on, the parser processed and creates SOAP DSML message. Otherwise the DSML messages are not wrapped in SOAP.

Detailed Log

If checked, more detailed log messages will be generated.

Examples

Parsing a DSMLv2 AddRequest in Server mode

If the DSMLv2 Parser is configured to run in "server" (read) mode and is passed the following DSMLv2 request:

<batchRequest onError="exit" processing="sequential"
    responseOrder="sequential" xmlns="urn:oasis:names:tc:DSML:2:0:core"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">    
    <addRequest requestID = "3" dn="cn=chavdar kovachev,o=ibm,c=us">    
        <attr name="objectclass">             <value>person</value>
        </attr>
        <attr name="telephoneNumber">             <value>555</value>
        </attr>
        <attr name="sn">             <value>kovachev</value>
        </attr>
        <attr name="cn">             <value>chavdar kovachev</value>
        </attr>
    </addRequest> 
</batchRequest>

it will generate an Entry object with the following Attributes:

sn: 'kovachev'
$dn: 'cn=chavdar kovachev,o=ibm,c=us'
telephoneNumber: '555'
objectclass: 'person'
dsml.operation: 'addRequest'
dsml.requestID: '3'
cn: 'chavdar kovachev'
dsml.base: 'cn=chavdar kovachev,o=ibm,c=us'

Creating a DSMLv2 SearchRequest in Client mode

If the DSMLv2 Parser is configured to run in "client" (write) mode and is passed an Entry with the following Attributes:

$dn: "o=ibm,c=us"
dsml.derefAliases: 'neverDerefAliases'
dsml.sizeLimit: '0'
dsml.operation: 'searchRequest'
dsml.timeLimit: '0'
dsml.typesOnly: 'false'
dsml.requestID: '7'
dsml.attributes: '[cn, sn]'
dsml.scope: 'wholeSubtree'
dsml.base: 'o=ibm,c=us'
dsml.filter: '(sn=*)'

it will generate the following DSMLv2 request:

<?xml version="1.0" encoding="UTF-8"?>
<batchRequest onError="exit" processing="sequential"
    responseOrder="sequential" xmlns="urn:oasis:names:tc:DSML:2:0:core"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">      <searchRequest requestID="7" derefAliases="neverDerefAliases"
        dn="o=ibm,c=us" scope="wholeSubtree" sizeLimit="0"
        timeLimit="0" typesOnly="false">        <filter>
            <present name="sn"/>
       </filter>
       <attributes>
            <attribute name="cn"/>
            <attribute name="sn"/>
       </attributes>
    </searchRequest>
</batchRequest>