001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2008 Sun Microsystems, Inc.
015 */
016package org.opends.server.admin.client.ldap;
017
018
019import java.util.Collection;
020
021import javax.naming.NamingException;
022import javax.naming.directory.Attributes;
023import javax.naming.ldap.LdapName;
024
025
026
027/**
028 * An LDAP connection adaptor interface which is used to perform LDAP
029 * client operations.
030 * <p>
031 * This interface is provided in order to make it easier to keep track
032 * of which JNDI DirContext methods we require and also to facilitate
033 * implementation of mock JNDI contexts for unit-testing.
034 */
035public abstract class LDAPConnection {
036
037  /**
038   * Create a new LDAP connection.
039   */
040  protected LDAPConnection() {
041    // No implementation required.
042  }
043
044
045
046  /**
047   * Creates a new entry with the specified set of attributes.
048   *
049   * @param dn
050   *          The name of the entry to be created.
051   * @param attributes
052   *          The set of attributes.
053   * @throws NamingException
054   *           If an error occurred whilst creating the entry.
055   */
056  public abstract void createEntry(LdapName dn, Attributes attributes)
057      throws NamingException;
058
059
060
061  /**
062   * Deletes the named subtree.
063   *
064   * @param dn
065   *          The name of the subtree to be deleted.
066   * @throws NamingException
067   *           If an error occurred whilst deleting the subtree.
068   */
069  public abstract void deleteSubtree(LdapName dn) throws NamingException;
070
071
072
073  /**
074   * Determines whether or not the named entry exists.
075   *
076   * @param dn
077   *          The name of the entry.
078   * @return Returns <code>true</code> if the entry exists.
079   * @throws NamingException
080   *           If an error occurred whilst making the determination.
081   */
082  public abstract boolean entryExists(LdapName dn) throws NamingException;
083
084
085
086  /**
087   * Lists the children of the named entry.
088   *
089   * @param dn
090   *          The name of the entry to list.
091   * @param filter
092   *          An LDAP filter string, or <code>null</code> indicating
093   *          the default filter of <code>(objectclass=*)</code>.
094   * @return Returns the names of the children.
095   * @throws NamingException
096   *           If an error occurred whilst listing the children.
097   */
098  public abstract Collection<LdapName> listEntries(LdapName dn, String filter)
099      throws NamingException;
100
101
102
103  /**
104   * Modifies the attributes of the named entry.
105   *
106   * @param dn
107   *          The name of the entry to be modified.
108   * @param mods
109   *          The list of attributes which need replacing.
110   * @throws NamingException
111   *           If an error occurred whilst applying the modifications.
112   */
113  public abstract void modifyEntry(LdapName dn, Attributes mods)
114      throws NamingException;
115
116
117
118  /**
119   * Reads the attributes of the named entry.
120   *
121   * @param dn
122   *          The name of the entry to be read.
123   * @param attrIds
124   *          The list of attributes to be retrievd.
125   * @return Returns the attributes of the requested entry.
126   * @throws NamingException
127   *           If an error occurred whilst reading the entry.
128   */
129  public abstract Attributes readEntry(LdapName dn, Collection<String> attrIds)
130      throws NamingException;
131
132
133
134  /**
135   * Closes the LDAP connection.
136   */
137  public abstract void unbind();
138}