NDS 8 creates multiple indexes for the objects that are found in the replicas stored on the server. These indexes sort objects based on their attributes. For example, one index sorts the objects by base class (object class used to create the object) and then alphabetically by the object's RDN.
The eDirectory libraries emulate the index functionality on eDirectory servers not running NDS 8. Hence, a number of differences exist between how true indexes and emulated indexes work.
The information about index features has been divided into the following topics:
The eDirectory iterator object can be configured to use one of the following indexes.
Two of the attributes, "CN" and "UniqueID," contain substring indexes on their values. Substring indexes contain multiple keys for each value so that searching for a specific substring of a value is optimized. For example, a search string of
*ary
would quickly find the values
Hillary
Mary
Scary
The index can find these values without comparing the substring value of "ary" with every string in the index.
A positionable iterator is an iterator object that has information about where an entry is positioned in the list. A positionable iterator can be positioned with the NWDSItrSetPosition function and can return its position with the NWDSItrGetPosition function. Iterators that are nonpositionable can return information about entries but can't return information about an entry's location in the list.
Whether an iterator is positionable depends upon the interaction between the search filter and the index (see Search Filters). The NWDSItrGetInfo function returns whether an existing iterator is positionable.
The objects returned by the iterators can be restricted by applying a search filter. The NWDSItrCreateList function uses two parameters for its search filter:
className can be used to restrict the list to objects of a specified base class. Wildcards cannot be used to specify the base class.
subordinateName can be used to restrict the list to objects that match a specified RDN. This name can include wildcards.
The NWDSItrCreateSearch function uses the same type of search filter as the NWDSSearch function, with a few restrictions on attributes and wildcards. For complete information on creating a search filter, see Search Requests
(NDK: Novell eDirectory Core Services).
Object Class Attribute. This attribute should not be used in the search filter. This attribute is a multivalued attribute that contains the object's base class and all its super classes. For example, the Object Class attribute for User contains the following objects: User, Organizational Person, Person, and Top. A search filter of "Object Class=User" is not efficient since eDirectory must search through multiple values in the attribute for every object in the container. The "BaseClass" string allows for an efficient search of an object's base class and should be used to restrict a search to a specific base class.
Other eDirectory Attributes. For positionable iterators, an attribute should not be included in the search filter unless it is an attribute of the index. The following table lists the indexes and the attributes that can be used to produce a positionable iterator.
For nonpositionable iterators, any eDirectory attribute can be included in the filter. For example, the following filter produces a nonpositionable iterator:
"BaseClass=User AND Telephone Number=571*"
Also, ANDing the same attribute together with multiple values produces a nonpositionable iterator. For example, the following filter produces a nonpositionable iterator:
"CN=J* AND CN=S*"
eDirectory sometimes appends criteria to the search request. For example, the criteria might ensure that the selected entries are not in a deleted state or that the results are limited to a particular container in the eDirectory tree. These criteria can cause an iterator, which meets the other rules for positionable, to be nonpositionable.
If your application requires a positionable iterator, use the NWDSItrGetInfo function to verify that functionality.
Wildcards. Wildcards can be used in any text attribute except for BaseClass. Wildcards can be used in any combination. Search filters ending in a single wildcard are very efficient with any index. Leading wildcard searches, such as "*sen" depend on the index and the size of the container. On large containers with nonsubstring indexes ("_BaseClass, _RDN", "Given Name", and "Surname"), leading wildcard searches do not produce an efficient search query.
On substring indexes ("CN" and "UniqueID"), leading wildcard searches are efficient. However, the sort order is unpredictable. For example, a search filter of CN=*a* produces a random list of names that contain the letter, such as Jane, David, and Anna. Also, such an iterator object is not positionable.
RDN String. The schema uses multiple naming attributes (for example, CN, L, OU, or O) for the object classes. The RDN string specifies an object's name and uses the FTOK_RDN token in the search filter. The search expression "RDN=S*" uses the following node expressions in constructing a search filter:
FTOK_RDN, NULL, 0
FTOK_ANAME, "S*", SYN_DIST_NAME
BaseClass String. The BaseClass string uses the FTOK_BASECLS token in the search filter. The search expression "BaseClass=User" uses the following node expressions:
FTOK_BASECLS, NULL, 0
FTOK_ANAME "User", SYN_CLASS_NAME
The eDirectory schema has many multivalued attributes. The only index using such an attribute is the "CN" index. The eDirectory search on an NDS 8 server returns duplicate entries when a multivalued attribute has more than one value. Since CN is such an attribute and most leaf objects in an eDirectory tree use CN as their naming attribute, most leaf objects can have more than one name. The indexes contain an entry for each name. For example, if a User object has Angela as its first CN value with additional values of Mary and Zella, the object appears three times in the list, once with the A's, once with the M's, and once with the Z's. In addition, since entry display is by first value, most applications would display Angela in all three locations.
True iterators require NDS 8 servers, which automatically create indexes for every container object in the replicas that they store. Thus, when a request comes in to create an iterator for a container, the server already has a sorted, indexed list to use for the iterator.
On eDirectory servers not running NDS 8, the libraries emulate this sorting and indexing functionality so that applications using these APIs work in both environments. If an iterator is created in the emulation mode, the workstation retrieves the entire result set, sorts it, and stores it in memory. The creation function thus takes longer and is not advised for very large lists.
An iterator with an emulated index has the following characteristics:
It is always positionable.
The sortKey parameter can use any eDirectory attribute as well as the defined BaseClass and RDN strings.
The search filter can use any eDirectory attribute.
Duplicate entries are not returned. Only the first value of an attribute is added to the sorted list.