/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Netscape Public License * Version 1.0 (the "NPL"); you may not use this file except in * compliance with the NPL. You may obtain a copy of the NPL at * http://www.mozilla.org/NPL/ * * Software distributed under the NPL is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL * for the specific language governing rights and limitations under the * NPL. * * The Initial Developer of this code under the NPL is Netscape * Communications Corporation. Portions created by Netscape are * Copyright (C) 1998 Netscape Communications Corporation. All Rights * Reserved. */ package netscape.ldap; import java.util.*; import java.io.*; /** * This interface summarizes the basic functionality available in the * Lightweight Directory Access Protocol (LDAP) version 2. (See * RFC 1777 * for the definition of the protocol.) *

* * In the general model for this protocol, objects exist under a directory * in a particular server. Objects are identified by unique, hierarchical names * called Distinguished Names, commonly abreviated "DN". An example of a DN: * 

 *  cn=Barbara Jensen,ou=Product Development,o=Ace Industry,c=us
 *
* Objects have attributes, of the form * 
 *  attributeName = attributeValue(s)
 *
* Attribute names must be Strings, and attribute values can be any 8-bit * sequence (Strings or binary values). * * @version 1.0 */ public interface LDAPv2 { /** * The default port number for LDAP servers. You can specify * this identifier when calling the LDAPConnection.connect * method to connect to an LDAP server. * @see netscape.ldap.LDAPConnection#connect */ public final static int DEFAULT_PORT = 389; /** * Option specifying how aliases are dereferenced. *

* * This option can have one of the following values: *

*

* * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int DEREF = 2; /** * Option specifying the maximum number of search results that * can be returned. *

* * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int SIZELIMIT = 3; /** * Option specifying the maximum number of milliseconds to * wait for an operation to be completed. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int TIMELIMIT = 4; /** * Option specifying whether or not referrals to other LDAP * servers are followed automatically. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption * @see netscape.ldap.LDAPRebind * @see netscape.ldap.LDAPRebindAuth */ public static final int REFERRALS = 8; /** * Option specifying the object containing the method for * getting authentication information (the distinguished name * and password) used during a referral. For example, when * referred to another LDAP server, your client uses this object * to obtain the DN and password. Your client authenticates to * the LDAP server using this DN and password. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption * @see netscape.ldap.LDAPRebind * @see netscape.ldap.LDAPRebindAuth */ public static final int REFERRALS_REBIND_PROC = 9; /** * Option specifying the maximum number of referrals to follow * in a sequence when requesting an LDAP operation. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int REFERRALS_HOP_LIMIT = 10; /** * Option specifying the version of the LDAP protocol * used by your client when interacting with the LDAP server. * If no version is set, the default version is 2. If you * are planning to use LDAP v3 features (such as controls * or extended operations), you should set this version to 3 * or specify version 3 as an argument to the authenticate * method of the LDAPConnection object. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption * @see netscape.ldap.LDAPConnection#authenticate(int, java.lang.String, java.lang.String) */ public static final int PROTOCOL_VERSION = 17; /** * Option specifying the number of results to return at a time. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int BATCHSIZE = 20; /* * Valid options for Scope */ /** * Specifies that the scope of a search includes * only the base DN (distinguished name). * @see netscape.ldap.LDAPConnection#search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints) */ public static final int SCOPE_BASE = 0; /** * Specifies that the scope of a search includes * only the entries one level below the base DN (distinguished name). * @see netscape.ldap.LDAPConnection#search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints) */ public static final int SCOPE_ONE = 1; /** * Specifies that the scope of a search includes * the base DN (distinguished name) and all entries at all levels * beneath that base. * @see netscape.ldap.LDAPConnection#search(java.lang.String, int, java.lang.String, java.lang.String[], boolean, netscape.ldap.LDAPSearchConstraints) */ public static final int SCOPE_SUB = 2; /* * Valid options for Dereference */ /** * Specifies that aliases are never dereferenced. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int DEREF_NEVER = 0; /** * Specifies that aliases are dereferenced when searching the * entries beneath the starting point of the search (but * not when finding the starting entry). * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int DEREF_SEARCHING = 1; /** * Specifies that aliases are dereferenced when finding the * starting point for the search (but not when searching * under that starting entry). * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int DEREF_FINDING = 2; /** * Specifies that aliases are always dereferenced. * @see netscape.ldap.LDAPConnection#getOption * @see netscape.ldap.LDAPConnection#setOption */ public static final int DEREF_ALWAYS = 3; /** * Connects to the LDAP server. * @param host Hostname of the LDAP server. * @param port Port number of the LDAP server. To specify the * default, well-known port, use DEFAULT_PORT. * @exception LDAPException Failed to connect to the server. */ public void connect (String host, int port) throws LDAPException; /** * Connects and authenticates to the LDAP server. * @param host Hostname of the LDAP server. * @param port Port number of the LDAP server. To specify the * default, well-known port, use DEFAULT_PORT. * @param dn Distinguished name to use for authentication. * @param passwd Password for authentication. * @exception LDAPException Failed to connect and authenticate to the server. */ public void connect (String host, int port, String dn, String passwd) throws LDAPException; /** * Disconnects from the LDAP server. Subsequent operational calls * will first try to re-establish the connection to the same LDAP server. * @exception LDAPException Failed to disconnect from the server. */ public void disconnect() throws LDAPException; /** * Authenticates user with the LDAP server. * @param Dn Distinguished name to use for authentication. * @param passwd Password for authentication. * @exception LDAPException Failed to authenticate to the server. */ public void authenticate (String DN, String passwd) throws LDAPException; /** * Read the entry corresponding to the specified distinguished name (DN). * @param DN Distinguished name of the entry to retrieve. * @exception LDAPException Failed to retrieve the specified entry. */ public LDAPEntry read (String DN) throws LDAPException; /** * Read the entry corresponding to the specified distinguished name (DN), * and retrieve only the specified attributes. * @param DN Distinguished name of the entry to retrieve. * @param attrs Names of attributes to retrieve. * @exception LDAPException Failed to retrieve the specified entry. */ public LDAPEntry read (String DN, String attrs[]) throws LDAPException; /** * Read the entry corresponding to the specified distinguished name (DN), * and retrieve only the specified attributes. * @param DN Distinguished name of the entry to retrieve. * @param attrs Names of attributes to retrieve. * @param cons The constraints set for the read operation. * @exception LDAPException Failed to retrieve the specified entry. */ public LDAPEntry read (String DN, String attrs[], LDAPSearchConstraints cons) throws LDAPException; /** * Searches for entries in the directory. * @param base Starting point for the search in the directory * (distinguished name). * @param scope Indicates whether the scope of the search includes * only the base DN (equivalent to a read operation), only the entries * one level below the base DN, or all entries at all levels beneath * the base DN (including the base DN itself). * @param filter String which describes the search criteria. The format * of the string is described fully in * RFC 1558. * @param attrs Names of the attributes to return for each matching * directory entry. If null, all attributes are returned. * @param attrsOnly If true, the search will return only the names of * the attributes (and not their values). * @exception LDAPException Failed to complete the requested search. */ public LDAPSearchResults search (String base, int scope, String filter, String[] attrs, boolean attrsOnly) throws LDAPException; /** * Searches for entries in the directory. * @param base Starting point for the search in the directory * (distinguished name). * @param scope Indicates whether the scope of the search includes * only the base DN (equivalent to a read operation), only the entries * one level below the base DN, or all entries at all levels beneath * the base DN (including the base DN itself). * @param filter String which describes the search criteria. The format * of the string is described fully in * RFC 1558. * @param attrs Names of the attributes to return for each matching * directory entry. If null, all attributes are returned. * @param attrsOnly If true, the search will return only the names of * the attributes (and not their values). * @param cons Constraints specific to the search (for example, the maximum number * of entries to return or the maximum time to wait for the search operation to complete). * @exception LDAPException Failed to complete the requested search. */ public LDAPSearchResults search (String base, int scope, String filter, String[] attrs, boolean attrsOnly, LDAPSearchConstraints cons) throws LDAPException; /** * Compares the given entry's attribute value to the specified * attribute value. * @param DN Distinguished name of the entry that you want compared * against the specified attribute value. * @param attr Attribute name and value to use in the comparison. * @exception LDAPException Failed to perform the comparison. */ public boolean compare (String DN, LDAPAttribute attr) throws LDAPException; /** * Compares the given entry's attribute value to the specified * attribute value. * @param DN Distinguished name of the entry that you want compared * against the specified attribute value. * @param attr Attribute name and value to use in the comparison. * @param cons The constraints set for the compare operation. * @exception LDAPException Failed to perform the comparison. */ public boolean compare (String DN, LDAPAttribute attr, LDAPSearchConstraints cons) throws LDAPException; /** * Adds an entry to the directory. * @param entry New entry to add to the directory. * @exception LDAPException Failed to add the entry to the directory. */ public void add (LDAPEntry entry) throws LDAPException; /** * Adds an entry to the directory. * @param entry New entry to add to the directory. * @param cons The constraints set for the add operation. * @exception LDAPException Failed to add the entry to the directory. */ public void add (LDAPEntry entry, LDAPSearchConstraints cons) throws LDAPException; /** * Modifies an attribute of a directory entry. * @param DN Distinguished name identifying the entry to be modified. * @param mod The modification to be made. * @exception LDAPException Failed to modify the specified entry. */ public void modify (String DN, LDAPModification mod) throws LDAPException; /** * Modifies an attribute of a directory entry. * @param DN Distinguished name identifying the entry to be modified. * @param mod The modification to be made. * @param cons The constraints set for the modify operation. * @exception LDAPException Failed to modify the specified entry. */ public void modify (String DN, LDAPModification mod, LDAPSearchConstraints cons) throws LDAPException; /** * Modifies the attributes of a directory entry. * @param DN Distinguished name identifying the entry to be modified. * @param mod List of the modifications to be made. * @exception LDAPException Failed to modify the specified entry. */ public void modify (String DN, LDAPModificationSet mods ) throws LDAPException; /** * Modifies the attributes of a directory entry. * @param DN Distinguished name identifying the entry to be modified. * @param mod List of the modifications to be made. * @param cons The constraints set for the modify operation. * @exception LDAPException Failed to modify the specified entry. */ public void modify (String DN, LDAPModificationSet mods, LDAPSearchConstraints cons ) throws LDAPException; /** * Removes an entry from the directory. * @param DN Distinguished name identifying the entry to remove. * @exception LDAPException Failed to remove the entry from the directory. */ public void delete( String DN ) throws LDAPException; /** * Removes an entry from the directory. * @param DN Distinguished name identifying the entry to remove. * @param cons The constraints set for the delete operation. * @exception LDAPException Failed to remove the entry from the directory. */ public void delete( String DN, LDAPSearchConstraints cons ) throws LDAPException; /** * Changes the name of an entry in the directory. * @param DN Original distinguished name (DN) of entry. * @param newRDN New relative distinguished name (RDN) of the entry. * @param deleteOldRDN Specifies whether or not the original RDN remains * as an attribute of the entry. If true, the original RDN * is no longer an attribute of the entry. * @exception LDAPException Failed to rename the entry in the directory. */ public void rename ( String DN, String newRDN, boolean deleteOldRDN ) throws LDAPException; /** * Changes the name of an entry in the directory. * @param DN Original distinguished name (DN) of entry. * @param newRDN New relative distinguished name (RDN) of the entry. * @param deleteOldRDN Specifies whether or not the original RDN remains * as an attribute of the entry. If true, the original RDN * is no longer an attribute of the entry. * @param cons The constraints set for the rename operation. * @exception LDAPException Failed to rename the entry in the directory. */ public void rename ( String DN, String newRDN, boolean deleteOldRDN, LDAPSearchConstraints cons ) throws LDAPException; /** * Retrieves an option that applies to the connection. * The particular meaning may be implementation-dependent. * The standard options are the search options described by * the LDAPSearchConstraints class. * @exception LDAPException Failed to retrieve the value of the specified option. */ public Object getOption( int option ) throws LDAPException; /** * Sets an option that applies to the connection. * The particular meaning may be implementation-dependent. * The standard options are the search options described by * the LDAPSearchConstraints class. * @exception LDAPException Failed to set the specified option. */ public void setOption( int option, Object value ) throws LDAPException; }