com.novell.service.nds
Interface NdsIteratorFactory

public interface NdsIteratorFactory

Generates NdsIterator objects used to create a large virtual list based on a set of parameters. Five createIterator() methods are defined, each passing in a different set of parameters used in generating the NdsIterator objects.

See Also:

NdsIterator, NdsIteratorControls, NdsIteratorInfo, NdsIteratorResult

Method Summary

NdsIterator	createIterator(java.lang.String name, javax.naming.directory.Attributes matchingAttributes) Creates an NdsIterator object based on two parameters.
NdsIterator	createIterator(java.lang.String name, javax.naming.directory.Attributes matchingAttributes, java.lang.String[] attributesToReturn) Creates an NdsIterator object based on three parameters.
NdsIterator	createIterator(java.lang.String name, NdsIteratorControls cons, java.lang.String className, java.lang.String subordinateName) Creates an NdsIterator object based on four parameters.
NdsIterator	createIterator(java.lang.String name, java.lang.String filter, NdsIteratorControls cons) Creates an NdsIterator object based on three parameters.
NdsIterator	createIterator(java.lang.String name, java.lang.String filterExpr, java.lang.Object[] filterArgs, NdsIteratorControls cons) Creates an NdsIterator object based on four parameters.

Method Detail

createIterator

public NdsIterator createIterator(java.lang.String name,
                                  javax.naming.directory.Attributes matchingAttributes,
                                  java.lang.String[] attributesToReturn)
                           throws com.novell.service.jncp.NSIException

Creates an NdsIterator object based on three parameters. The parameters passed in are the name of the context to search (name), the attributes for which to search (matchingAttributes), and the attributes to return (attributesToReturn).

This NdsIterator() method searches in a single context for objects that contain a specified set of attributes, and then returns the entries or objects with the attributes specified by the attributesToReturn parameter in an NdsIterator object. The search is performed using the default NdsIteratorControls settings.

For an object to be selected, each attribute in the matchingAttributes parameter must match some attribute of the object. If matchingAttributes is empty or NULL, all objects in the target context are returned. The precise definition of equality used in comparing attribute values is defined by the underlying directory service. It might use the Java Object.equals method, or it might use a schema to specify a different equality operation.

Parameters:

name - The non-NULL name of the context to search.

matchingAttributes - The attributes for which to search. If empty or NULL, all objects in the target context are returned.

attributesToReturn - The attributes to return. NULL indicates that all attributes should be returned. An empty array indicates that no attributes are to be returned.

Returns:

The objects with all their attributes in an NdsIterator.

Throws:

com.novell.service.jncp.NSIException - If a naming exception occurs. NSIException is a standard NJCL exception for working on top of XPlat libraries.

See Also:

NdsIteratorControls, NdsIteratorResult

createIterator

public NdsIterator createIterator(java.lang.String name,
                                  javax.naming.directory.Attributes matchingAttributes)
                           throws com.novell.service.jncp.NSIException

Creates an NdsIterator object based on two parameters. The parameters passed in are the name of the context to search (name), and the attributes for which to search (matchingAttributes).

This NdsIterator() method searches in a single context for objects that contain a specified set of attributes, and then returns the objects with all their attributes in an NdsIterator. It is equivalent to supplying NULL for the attributesToReturn parameter.

Parameters:

name - The non-NULL name of the context to search.

matchingAttributes - The attributes for which to search (possibly NULL).

Returns:

The objects with all their attributes in an NdsIterator.

Throws:

com.novell.service.jncp.NSIException - If a naming exception occurs. NSIException is a standard NJCL exception for working on top of XPlat libraries.

See Also:

NdsIteratorControls, NdsIteratorResult

createIterator

public NdsIterator createIterator(java.lang.String name,
                                  java.lang.String filter,
                                  NdsIteratorControls cons)
                           throws com.novell.service.jncp.NSIException

Creates an NdsIterator object based on three parameters. The parameters passed in are the name of the context to search (name), the filter expression to use for the search (filter), and the iterator controls that control the search (cons).

This NdsIterator() method searches in the named context or named object for entries that satisfy the given search filter and then returns the objects with all their attributes in an NdsIterator. It performs the search as specified by the iterator controls cons parameter, as defined in the NdsIteratorControls constructor.

After a call to NdsIterator.next or NdsIterator.previous, the result returned is an NdsIterator. Each NdsIteratorResult contains the name of the object and other information about the object (see NdsIteratorResult). The name is either relative to the target context of the search, which is named by the name parameter, or it is a URL string. If the target context is included in the enumeration (as is possible when the cons parameter specifies a search scope of NdsIteratorControls.OBJECT_SCOPE), its name is the empty string.

Parameters:

name - The non-NULL name of the context or object at which to perform the search.

filter - The non-NULL filter expression to use for the search.

cons - The iterator controls that control the search. If NULL, it is equivalent to using the NULL NdsIteratorControls constructor.

Returns:

The objects with all their attributes in an NdsIterator.

Throws:

com.novell.service.jncp.NSIException - If a naming exception occurs. NSIException is a standard NJCL exception for working on top of XPlat libraries.

InvalidSearchFilterException - The search filter specified is not supported or understood by the underlying directory.

InvalidSearchControlsException - The iterator controls contains invalid settings.

See Also:

NdsIteratorControls, NdsIteratorResult

createIterator

public NdsIterator createIterator(java.lang.String name,
                                  java.lang.String filterExpr,
                                  java.lang.Object[] filterArgs,
                                  NdsIteratorControls cons)
                           throws com.novell.service.jncp.NSIException

Creates an NdsIterator object based on four parameters. The parameters passed in are the name of the context to search (name), the filter expression to use for the search (filterExpr), an array of filter arguments (filterArgs), and the iterator controls that control the search (cons).

This NdsIterator() method searches in the named context or named object for entries that satisfy the given search filter and then returns the objects with all their attributes in an NdsIterator. It performs the search as specified by the iterator controls cons parameter, which is defined in the NdsIteratorControls constructor.

After a call to NdsIterator.next or NdsIterator.previous, this method returns an NdsIterator, which contains the name of the object and other information about the object (see NdsIteratorResult). The name is either relative to the target context of the search, which is named by the name parameter, or it is a URL string. If the target context is included in the enumeration (as is possible when the cons parameter specifies a search scope of NdsIteratorControls.OBJECT_SCOPE), its name is an empty string.

Parameters:

name - The non-NULL name of the context or object at which to perform the search.

filterExpr - The non-NULL filter expression to use for the search. The expression may contain variables of the form {i} where i is an integer.

filterArgs - The array of arguments (possibly NULL) to substitute for the variables in filterExpr. The value of filterArgs[i] will replace each occurrence of {i}.

cons - The iterator controls that control the search. If NULL, it is equivalent to using the no arguments NdsIteratorControls constructor.

Returns:

The objects with all their attributes in an NdsIterator.

Throws:

com.novell.service.jncp.NSIException - If a naming exception occurs. NSIException is a standard NJCL exception for working on top of XPlat libraries.

ArrayIndexOutOfBoundsException - If filterExpr contains {i} expressions where i is outside the bounds of the array filterArgs.

InvalidSearchControlsException - If the cons parameter contains invalid settings.

InvalidSearchFilterException - If filterExpr and filterArgs expresses an invalid search filter.

See Also:

NdsIteratorControls

createIterator

public NdsIterator createIterator(java.lang.String name,
                                  NdsIteratorControls cons,
                                  java.lang.String className,
                                  java.lang.String subordinateName)
                           throws com.novell.service.jncp.NSIException

Creates an NdsIterator object based on four parameters. The parameters passed in are the name of the context to search (name), the iterator controls that control the search (cons), the name of the object class (className) and the name of the subordinate in which to search.

This NdsIterator() method lists subordinates in the named context or named object for entries that satisfy the given filter of class and subordinate names, then returns the objects without attribute names or values in an NdsIterator.

Of the items stored in the NdsIteratorControls, the items that apply to the list iterator with their default values are:

1. scalability = NdsIteratorControls.DS_ITR_PREFER_SCALABLE
2. timeout = 0
3. retObj = false

The name given for the className filter is the name of an object class, such as User, Computer, or Server. The value given for subordinateName filter can be one of the following:

• The left-most name of an object, such as Adam or Graphics Printer.
• A string with asterisks (*), such as A* or Gr*.
• NULL, which means any name is valid.

The location of the subordinate object(s) in the NDS tree is immediately subordinate to the object specified by objectName. The relationship between className and subordinateName is an AND relationship. When className and subordinateName are provided, a list of immediate subordinate objects restricted by both filters is returned. When className is NULL and subordinateName is NULL, a list of all immediate subordinates is returned. When className is provided and subordinateName is NULL, a list of immediate subordinates restricted only by the className filter is returned. When className is NULL and subordinateName is provided, a list of immediate subordinates restricted only by the subordinateName filter is returned.

The following examples show how to use wildcards for untyped names:

• c* - Any object whose left-most name begins with a "c" character.
• M*y - Any object beginning with "M" and ending with "y" such as Mary.

If the wildcard name specified for subordinateName includes a type, such as CN, the name must include the equals (=) sign. The following examples show how to use wildcards for typed names:

• cn=* - Any object whose left-most name is a common name.
• cn=c* - Any object whose left-most name is a common name and begin with "c."
• o*=* - Any object whose left-most name has a naming attribute beginning with an "o," such as O or OU.
• o*=c* - Any object whose left-most name has a naming attribute beginning with an "o," and whose name begins with "c."

Parameters:

name - The non-NULL name of the context or object at which to perform the search.

cons - The iterator controls that control the search. If NULL, it is equivalent to using the no arguments NdsIteratorControls constructor.

className - The name of the object class filter.

subordinateName - The name of the subordinate filter.

Returns:

The subordinate objects in an NdsIterator.

Throws:

com.novell.service.jncp.NSIException - If a naming exception occurs. NSIException is a standard NJCL exception for working on top of XPlat libraries.

InvalidSearchControlsException - If the cons parameter contains invalid settings. see NdsIteratorControls