001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2010 Sun Microsystems, Inc.
025 *      Portions Copyright 2015 ForgeRock AS
026 */
027package org.opends.server.api;
028
029
030
031import org.opends.server.types.DirectoryException;
032import org.opends.server.types.Entry;
033
034
035
036/**
037 * This interface defines a mechanism that Directory Server components
038 * may use if they need to be notified of changes that are being made
039 * to subentries in the Directory Server.
040 * <BR><BR>
041 * Each change listener will be notified whenever an update is being
042 * made to subentry in the server, so the listener should use a very
043 * efficient mechanism for determining whether or not any action is
044 * required for the associated operation and quickly return for cases
045 * in which the update is not applicable.
046 * <BR><BR>
047 * The interface consists of two separate classes of methods. Check
048 * methods are invoked to verify that a specific operation performed
049 * on subentry is acceptable and if so the server may proceed with
050 * that operation further. Handle methods are invoked to notify that
051 * specific operation has occured on subentry thus serving purely as
052 * notification mechanism. While Check methods can affect the outcome
053 * of given operation Handle methods cannot affect the operation out-
054 * come in any way. Also note that Handle methods are invoked before
055 * any actual operation response to the client is sent.
056 * <BR><BR>
057 * This interface is intended for the server components that either
058 * require to track changes to subentries within the server or need
059 * to evaluate and take actions on specific changes being made to
060 * subentries within the server. Eg server components implementing
061 * their configuration objects as administrative subentries.
062 */
063@org.opends.server.types.PublicAPI(
064     stability=org.opends.server.types.StabilityLevel.VOLATILE,
065     mayInstantiate=false,
066     mayExtend=true,
067     mayInvoke=false)
068public interface SubentryChangeListener
069{
070  /**
071   * Performs any checking that may be required before
072   * subentry add operation.
073   * @param entry subentry being added to the server.
074   * @throws DirectoryException if operation is not
075   *         acceptable for this subentry.
076   */
077  void checkSubentryAddAcceptable(Entry entry)
078          throws DirectoryException;
079
080  /**
081   * Performs any checking that may be required before
082   * subentry delete operation.
083   * @param entry subentry being deleted in the server.
084   * @throws DirectoryException if operation is not
085   *         acceptable for this subentry.
086   */
087  void checkSubentryDeleteAcceptable(Entry entry)
088          throws DirectoryException;
089
090  /**
091   * Performs any checking that may be required before
092   * subentry modify operation.
093   * @param oldEntry subentry being modified in the server.
094   * @param newEntry subentry with modifications applied.
095   * @throws DirectoryException if operation is not
096   *         acceptable for this subentry.
097   */
098  void checkSubentryModifyAcceptable(Entry oldEntry,
099          Entry newEntry) throws DirectoryException;
100
101  /**
102   * Performs any checking that may be required before
103   * subentry modify DN operation.
104   * @param oldEntry subentry being modified in the server.
105   * @param newEntry subentry with modifications applied.
106   * @throws DirectoryException if operation is not
107   *         acceptable for this subentry.
108   */
109  void checkSubentryModifyDNAcceptable(Entry oldEntry,
110          Entry newEntry) throws DirectoryException;
111
112  /**
113   * Performs any processing that may be required after a
114   * subentry add operation.
115   *
116   * @param entry The subentry that was added to the
117   *              server.
118   */
119  void handleSubentryAdd(Entry entry);
120
121  /**
122   * Performs any processing that may be required after a
123   * subentry delete operation.
124   *
125   * @param entry The subentry that was removed from the
126   *              server.
127   */
128  void handleSubentryDelete(Entry entry);
129
130  /**
131   * Performs any processing that may be required after a
132   * subentry modify operation.
133   *
134   * @param oldEntry The subentry before it was updated.
135   * @param newEntry The subentry after it was updated.
136   */
137  void handleSubentryModify(Entry oldEntry, Entry newEntry);
138
139  /**
140   * Performs any processing that may be required after a
141   * subentry modify DN operation.
142   *
143   * @param oldEntry The subentry before it was updated.
144   * @param newEntry The subentry after it was updated.
145   */
146  void handleSubentryModifyDN(Entry oldEntry, Entry newEntry);
147}