query

<query> is a command used to find and/or read objects from eDirectory or the application. Full functionality for DirXML rules, object migration, etc. depends on full implementation of the query command by the driver.

The base object of the <query> is specified by either by the dest-dn attribute or by an <association>. If both are present, the dest-dn attribute takes precedence when querying eDirectory, and <association> takes precedence when querying a connected application (other than eDirectory). If neither are present, the base object defaults to the root object in a hierarchical name space or all objects in a non-hierarchical name space.

Possible scopes for the query are:

entry
The base object only.
subordinates
The objects contained by the base object.
subtree
The objects in the subtree whose root is the base object, including the base object.

By default, all objects in the specified scope are selected. For scopes other than "entry", selected objects can be further limited by <search-class> , <search-attr> and <search-condition>. For scope "entry", the effect of <search-attr> , <search-class> and <search-condition> are undefined.

When there are <search-class> elements, only objects whose base class matches one of the <search-class> elements will be selected.

When there are <search-attr> elements, only objects with attributes matching all of the values specified by all of the <search-attr> elements will be selected.

When there is only one <search-condition> element, only objects that satisfy the given condition will be selected.

When there are a combination of <search-condition> and <search-attr> elements, only the objects that satisfy the conditions defined in the <search-condition> elements and match all the attribute values specified in the <search-attr> elements will be selected.

By default all, object attributes for the selected objects are to be read. The attributes to be read can be limited by <read-attr>. To read none of the object attributes, a single nameless <read-attr> should be specified.

The <parent> of the selected selected objects will also be read if and only if <read-parent> is specified.

The <parent> of the selected selected objects will also be read if and only if <read-parent> is specified.

A response to <query> should include an <instance> for each of the selected objects.

A response to <query> should also include a <status> indicating whether or not the <query> was processed successfully. It should not be considered an error if no objects exist that match the search criteria!

When the attribute return-on-first-match = true , the incoming query will be interpreted into multiple search criteria(i.e each of <search-condition> or <search-attr> will be treated as a seperate search criteria and expected to have the attribute search-criteria-id set) and are executed sequentially in the same order as received.

As and when a non-empty result is received for particular search criteria or sub query, the associated search-criteria-id will be appended to the instance documents and returned. We exit from the query execution i.e we will not proceed to the next search-criteria when a match has been found.

Example

<!-- search the whole application for a User object with the Surname of Jones -->
<!-- don't read any attributes but read the parent -->
<query class-name="User" event-id="0" scope="subtree">
<search-class class-name="User"/>
<search-attr attr-name="Surname">
<value type="string">Jones</value>
</search-attr>
<read-attr/>
<read-parent/>
</query>

<!-- read the User object whose foreign key is 1011 -->
<!-- read Surname,cn,Given Name and Telephone Number attributes -->
<query class-name="User" event-id="1" scope="entry">
<association>1011</association>
<read-attr attr-name="Surname"/>
<read-attr attr-name="cn"/>
<read-attr attr-name="Given Name"/>
<read-attr attr-name="Telephone Number"/>
</query>

<!--Search for user whose Surname is Smith or -->
<!--belong to the department(OU) IAM and not a Software Engineer -->
<query class-name="User" scope="subtree">
<search-class class-name="User"/>
<search-condition name="or">
<search-attr attr-name="Surname">
<value type="string">Smith</value>
</search-attr>
<search-condition name="and">
<search-attr attr-name="OU">
<value type="string">IAM</value>
</search-attr>
<search-condition name="not">
<search-attr attr-name="Title">
<value type="string">Software Engineer</value>
</search-attr>
</search-condition>
</search-condition>
</search-condition>
<read-attr/>
</query>

<query scope="subtree" return-on-first-match="true">
<search-attr name="CN" search-criteria-id="FullNameMatch">
<valuetype="string">Clark Kent</value>
</search-attr>
<search-condition name="and" search-criteria-id="requiredAttributeCombination">
<search-attr name="Surname"/>
<value type="string">Clark</value>
</search-attr>
<search-attr name="Given Name"/>
<value type="string">Kent</value>
</search-attr>
</search-condition>
</query>

1. Allowed Content

association
Unique key of the application object.
search-class
Query search class filter.
search-attr
Query search attribute value filter.
read-attr
Return specified object attribute value(s).
read-parent
Return object parent/container.
search-condition
Query search condition filter.
operation-data
Operation additional custom data.
driver-operation-data
Operation additional custom data used by the drivershim.

2. Attributes

AttributeValue(s)Default Value
cached-time CDATA
The time the event was placed into the driver cache. The format is CCYYMMDDhhmmss.mmmZ, always in UTC.
#IMPLIED
class-name CDATA
The name of the base class of the object.
The class name is mapped between the application and eDirectory name spaces by the schema mapping rule so that DirXML will see the name in the eDirectory namespace and a driver will see the name in the application name space.

This is required for proper schema mapping of any attribute names specified in the search. It should not be used to limit the search.
#IMPLIED
dest-dn CDATA
The distinguished name of the target object in the namespace of the receiver.
#IMPLIED
dest-entry-id CDATA
The entry id of the target object in the namespace of the receiver.

(Reserved) Should be ignored by the driver.
#IMPLIED
event-id CDATA
An identifier used to tag the results of an event or command.
#IMPLIED
return-on-first-match true   |  false
Determines the behavior of the query.
false
scope entry   |  subordinates   |  subtree
The scope of the query.
subtree

3. Content Rule

( association ? , ( search-class | search-attr | read-attr | read-parent | search-condition ) * , operation-data ? , driver-operation-data ? )

4. Parent Elements

config-object
  eDirectory object to use for additional configuration data.
input
  Input events or commands.

Top Elements || All Elements || Tree


NDS DTD