检索过滤器

和基本检索不同的是，可以使用一个检索过滤器进行检索操作。检索过滤器的检索语句是通过逻辑表达式的形式表示的。检索过滤器的语法在RFC 2254中进行了定义，DirContext.search()方法接受符合这个语法的过滤器。

下面的检索过滤器指定了合法的实体必须具有sn属性，并且其值为Geisel以及一个值为任意的mail属性：(&(sn=Geisel)(mail=*))

下面的代码创建了一个过滤器和一个默认的检索控制，SearchControls，并使用它们来进行检索操作。这个检索和基本检索中的功能是一样的。

// Create default search controls

SearchControls ctls = new SearchControls();

// Specify the search filter to match

// Ask for objects with attribute sn == Geisel and which have

// the "mail" attribute.

String filter = "(&(sn=Geisel)(mail=*))";

// Search for objects using filter

NamingEnumeration answer = ctx.search("ou=People", filter, ctls);

// Print the answer

while (answer.hasMore()) {

SearchResult sr = (SearchResult) answer.next();

System.out.println(">>>" + sr.getName());

GetattrsAll.printAttrs(sr.getAttributes());

}

检索返回的结果和基本检索的结果是一样的。

检索过滤器语法一览

检索过滤器语法基本上就是逻辑运算符作为前缀的逻辑表达式，下图是一些逻辑运算符号及其说明：

过滤器中的每一项都由属性标识符和属性值或者上述的运算符号组成。例如，”sn=Geisel”表示必须具有sn属性，并且sn属性的值必须为Geisel，”mail=*”则表示mail属性只要存在就可以了。

每一项都必须使用括号括起来使用。逻辑运算符可以组合使用，通过使用括号进行分割。例如

(| (& (sn=Geisel) (mail=*)) (sn=L*))

关于更完整的语法描述，参见RFC 2254。

返回指定属性

可以通过设置SearchControls的setReturningAttributes()方法来设置需要返回的特定属性：

// Specify the ids of the attributes to return

String[] attrIDs = { "sn", "telephonenumber", "golfhandicap","mail" };

ctls.setReturningAttributes(attrIDs);

其返回的结果和基本认证返回的一致。

检索控制

在上面的检索过滤器中如何使用SearchControls参数来选择需要返回的属性。还可以是SearchControls参数来控制检索的其他方面，下面是一些可用的控制：

¨         返回的属性

¨         检索的范围

¨         返回的最大结果数

¨         等待最大时间(毫秒)，即超时时间

¨         是否返回和实体相关联的Java对象

¨         在检索时是否废除JNDI链接

其中后两部分在之后的教程中介绍，本部分教程介绍前四种控制：

检索范围

通过使用SearchControls.setSearchScope(int scope)方法来设置检索范围，检索范围由三种，分别如下：

static int OBJECT_SCOPE
                            检索指定的对象

static int ONELEVEL_SCOPE
                            检索指定对象及其直接子实体

static int SUBTREE_SCOPE
                            在以指定对象为根的子树中进行检索

下图摘自ApacheDS网站对于检索范围的说明，比较易懂：

数量限制

有的时候，需要限制查询返回结果的数量，这个时候需要使用检索控制的数量限制。默认情况下，检索操作返回所有符合条件的检索结果，可以使用SearchControls.setCountLimit()方法设置检索结果的数量。下面的代码将检索结果数量设置为1：

// Set search controls to limit count to 'expected'

SearchControls ctls = new SearchControls();

ctls.setCountLimit(expected);

如果程序要获取大于最大数量的结果，那么将抛出一个SizeLimitExceededException。所以当设置数量限制的时候，应该将这个异常和NamingExceptions异常相区分，或者根据数量限制请求结果(不要超过最大数量)。

指定检索结果的数量是一种控制程序消耗资源的方法，比如内存或者网络带宽。其他控制资源消耗的办法有实用查询过滤器、在适当的上下文中查询以及使用适当的检索范围。

设置超时

设置超时是为了不至于等待太长的时间，如果超过时间限制，操作还没有执行完的话，将抛出TimeLimitExceededException，下面的代码设置了时间限制：

ctls.setTimeLimit(1000); //set time limit to 1 second

为了使这个程序运行，需要做一些特殊的设置，例如使用较慢的服务器或者检索范围使用SUB_TREE检索，并且服务器最好包含大量的实体。

当设置时间限制为0的时候，则表示没有时间限制。