001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 *
019 */
020package org.apache.directory.api.ldap.model.message.controls;
021
022
023import org.apache.directory.api.ldap.model.message.Control;
024import org.apache.directory.api.ldap.model.name.Dn;
025
026
027/**
028 * A response control that may be returned by Persistent Search entry responses.
029 * It contains addition change information to describe the exact change that
030 * occurred to an entry. The exact details of this control are covered in section
031 * 5 of this (yes) expired draft: <a
032 * href="http://www3.ietf.org/proceedings/01aug/I-D/draft-ietf-ldapext-psearch-03.txt">
033 * Persistent Search Draft v03</a> which is printed out below for convenience:
034 *
035 * <pre>
036 *    5.  Entry Change Notification Control
037 *
038 *    This control provides additional information about the change the caused
039 *    a particular entry to be returned as the result of a persistent search.
040 *    The controlType is &quot;2.16.840.1.113730.3.4.7&quot;.  If the client set the
041 *    returnECs boolean to TRUE in the PersistentSearch control, servers MUST
042 *    include an EntryChangeNotification control in the Controls portion of
043 *    each SearchResultEntry that is returned due to an entry being added,
044 *    deleted, or modified.
045 *
046 *               EntryChangeNotification ::= SEQUENCE
047 *               {
048 *                         changeType ENUMERATED
049 *                         {
050 *                                 add             (1),
051 *                                 delete          (2),
052 *                                 modify          (4),
053 *                                 modDN           (8)
054 *                         },
055 *                         previousDN   LDAPDN OPTIONAL,     -- modifyDN ops. only
056 *                         changeNumber INTEGER OPTIONAL     -- if supported
057 *               }
058 *
059 *    changeType indicates what LDAP operation caused the entry to be
060 *    returned.
061 *
062 *    previousDN is present only for modifyDN operations and gives the Dn of
063 *    the entry before it was renamed and/or moved.  Servers MUST include this
064 *    optional field only when returning change notifications as a result of
065 *    modifyDN operations.
066 *
067 *    changeNumber is the change number [CHANGELOG] assigned by a server for
068 *    the change.  If a server supports an LDAP Change Log it SHOULD include
069 *    this field.
070 * </pre>
071 *
072 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
073 */
074public interface EntryChange extends Control
075{
076    /** No defined change number */ 
077    int UNDEFINED_CHANGE_NUMBER = -1;
078
079    /** The EntryChange control */
080    String OID = "2.16.840.1.113730.3.4.7";
081
082
083    /**
084     * @return The ChangeType
085     */
086    ChangeType getChangeType();
087
088
089    /**
090     * Set the ChangeType
091     *
092     * @param changeType Add, Delete; Modify or ModifyDN
093     */
094    void setChangeType( ChangeType changeType );
095
096
097    /**
098     * @return The previous DN
099     */
100    Dn getPreviousDn();
101
102
103    /**
104     * Sets the previous DN
105     * 
106     * @param previousDn The previous DN
107     */
108    void setPreviousDn( Dn previousDn );
109
110
111    /**
112     * @return The change number
113     */
114    long getChangeNumber();
115
116
117    /**
118     * Sets the ChangeNumber
119     * 
120     * @param changeNumber The ChanegNumber
121     */
122    void setChangeNumber( long changeNumber );
123}