<!--

Copyright 2000-2007 Sun Microsystems, Inc. All Rights Reserved.
Portions copyright 1999 Netscape Communications Corporation. All
Rights Reserved.

The contents of this document are subject to the terms of the
Creative Commons Attribution-ShareAlike 2.5 license or any later
version (the "License"). You may not use this document except in
compliance with the License.

See the License for the specific language governing
permissions and limitations under the License. You can obtain
a copy of the License at
http://creativecommons.org/licenses/by-sa/2.5/legalcode.

-->
<chapter id="comparing"><title>Comparing Attribute Values With &DirectorySDKForJava;</title>
<indexterm>
<primary>attributes</primary>
<secondary>comparing values</secondary>
</indexterm><indexterm>
<primary>comparing attribute values</primary>
</indexterm><highlights>
<para>This chapter explains how to compare the value of an attribute in an
entry against a specified value.</para>
<itemizedlist>
<para>This chapter covers the following topics:</para>
<listitem><para><olink targetptr="compare-specify-attr-value">Specifying the
Attribute and Value With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="compare-perform">Performing the Comparison
With Directory SDK for Java</olink></para></listitem>
<listitem><para><olink targetptr="compare-example">Example Attribute Value
Comparison With Directory SDK for Java</olink></para></listitem>
</itemizedlist>
<para>The LDAP Java classes allow you to compare a specified value against
the value of an entry in the directory. For example, you can check to see
if the <literal>mail</literal> attribute of an entry contains the value <literal>
bjensen@example.com</literal>.</para>
<orderedlist>
<para>To compare a specified value against an attribute of an entry in the
directory, you need to follow this general procedure.</para>
<listitem><para>Specify the name of the attribute that you want to check and
the value that you want to use for comparison.</para></listitem>
<listitem><para>Use the distinguished name of the entry to find the entry
in the directory. The entry that is found is then used to perform the comparison.
</para></listitem></orderedlist>
</highlights>
<sect1 id="compare-specify-attr-value"><title>Specifying the Attribute and
Value With &DirectorySDKForJava;</title>
<para>Use an <classname>LDAPAttribute</classname> object to specify the name
of the attribute to check. Also use the object to specify the value to use
in the comparison.</para>
<programlisting>LDAPAttribute attr = new LDAPAttribute("mail", "bjensen@example.com");
</programlisting>
</sect1>
<sect1 id="compare-perform"><title>Performing the Comparison With &DirectorySDKForJava;</title>
<para>To perform the comparison, use the <literal>compare</literal> method
of the <classname>LDAPConnection</classname> object. Specify the distinguished
name of the entry that you want to compare. The method returns <literal>true</literal> if
the attribute contains the specified value.</para>
<programlisting>try {
    LDAPConnection ld = new LDAPConnection();
    ld.connect("localhost", LDAPv3.DEFAULT_PORT); 
    LDAPAttribute attr = new LDAPAttribute("mail", "bjensen@example.com");
    if (ld.compare("uid=bjensen,ou=People,dc=example,dc=com", attr)) {
        System.out.println("Found a match.");
    }
} catch (LDAPException e) {
    System.err.println("Error:" + e.toString());
}</programlisting>
</sect1>
<sect1 id="compare-example"><title>Example Attribute Value Comparison With &DirectorySDKForJava;</title>
<para>The following example compares values for the <literal>objectclass</literal> attribute
with values on Barbara Jensen's entry.</para>
<programlisting>import netscape.ldap.*;
import java.util.*;
 
public class Compare {
    public static void main(String[] args) {
            try {
                UserArgs userArgs = new UserArgs("Compare", args, false);
                LDAPConnection ld = new LDAPConnection();
                ld.connect(userArgs.getHost(), userArgs.getPort());
 
                /* Entry to compare */
                String ENTRYDN = "uid=bjensen,ou=People,dc=example,dc=com";
 
                /* Compare the value "person" and the attr. "objectclass" */
                LDAPAttribute attr =
                    new LDAPAttribute("objectclass", "person");
                boolean ok = ld.compare(ENTRYDN, attr);
                reportResults(ok, attr);
 
                /* Compare the value "xyzzy" and the attr. objectclass */
                attr = new LDAPAttribute("objectclass", "xyzzy");
                ok = ld.compare(ENTRYDN, attr);
                reportResults(ok, attr);
 
                ld.disconnect();
            } catch(LDAPException e) {
                System.out.println("Error: " + e.toString());
            }
        }
 
    private static void reportResults(boolean ok, LDAPAttribute attr) {
        String result;
        if (ok) {
            result = new String();
        } else {
            result = new String("not ");
        }
        Enumeration en = attr.getStringValues();
        if (en != null) {
            String val = (String)en.nextElement();
            System.out.println(
                "The value *" + val + "* is " + result +
                "contained in the " + attr.getName() + " attribute.");
        }
    }
}</programlisting>
</sect1>
</chapter>
