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     */
020    package org.apache.directory.server.core.changelog;
021    
022    
023    import java.util.List;
024    
025    import org.apache.directory.server.core.LdapPrincipal;
026    import org.apache.directory.server.core.DirectoryService;
027    import org.apache.directory.shared.ldap.cursor.Cursor;
028    import org.apache.directory.shared.ldap.ldif.LdifEntry;
029    
030    
031    
032    /**
033     * A store for change events on the directory which exposes methods for 
034     * managing, querying and in general performing legal operations on the log.
035     *
036     * @org.apache.xbean.XBean
037     *
038     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
039     * @version $Rev$, $Date$
040     */
041    public interface ChangeLogStore 
042    {
043        /**
044         * Initialize the store.
045         * 
046         * @param service The associated DirectoryService
047         * @throws Exception If the initialization failed
048         */
049        void init( DirectoryService service ) throws Exception;
050    
051    
052        /**
053         * Write the changes on disk
054         * 
055         * @throws Exception If the write failed
056         */
057        void sync() throws Exception;
058    
059    
060        /**
061         * Destroy the logs. 
062         * 
063         * @throws Exception If we can't destroy the logs
064         */
065        void destroy() throws Exception;
066    
067    
068        /**
069         * Gets the current revision of the server (a.k.a. the HEAD revision).
070         *
071         * @return the current revision of the server
072         */
073        long getCurrentRevision();
074    
075    
076        /**
077         * Records a change as a forward LDIF, a reverse change to revert the change and
078         * the authorized principal triggering the revertable change event.
079         *
080         * @param principal the authorized LDAP principal triggering the change
081         * @param forward LDIF of the change going to the next state
082         * @param reverse LDIF (anti-operation): the change required to revert this change
083         * @return the new revision reached after having applied the forward LDIF
084         * @throws Exception if there are problems logging the change
085         */
086        ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception;
087    
088        
089        /**
090         * Records a change as a forward LDIF, some reverse changes to revert the change and
091         * the authorized principal triggering the revertable change event.
092         *
093         * @param principal the authorized LDAP principal triggering the change
094         * @param forward LDIF of the change going to the next state
095         * @param reverses LDIF (anti-operation): the changes required to revert this change
096         * @return the new revision reached after having applied the forward LDIF
097         * @throws Exception if there are problems logging the change
098         */
099        ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception;
100    
101        
102        /**
103         * Looks up the ChangeLogEvent for a revision.
104         *
105         * @param revision to get a ChangeLogEvent for
106         * @return the ChangeLogEvent associated with the revision
107         * @throws Exception if there are failures accessing the store
108         * @throws IllegalArgumentException if the revision is out of range (less than 0
109         * and greater than the current revision)
110         */
111        ChangeLogEvent lookup( long revision ) throws Exception;
112    
113    
114        /**
115         * Gets a Cursor over all the ChangeLogEvents within the system since
116         * revision 0.
117         *
118         * This method should exhibit isolation characteristics: meaning if the
119         * request is initiated at revision 100, then any subsequent log entries
120         * increasing the revision should not be seen.
121         *
122         * @return a Cursor over all the ChangeLogEvents
123         * @throws Exception if there are failures accessing the store
124         */
125        Cursor<ChangeLogEvent> find() throws Exception;
126    
127    
128        /**
129         * Gets a Cursor over the ChangeLogEvents that occurred before a revision
130         * exclusive.
131         *
132         * @param revision the revision number to get the ChangeLogEvents before
133         * @return a Cursor over the ChangeLogEvents before a revision
134         * @throws Exception if there are failures accessing the store
135         * @throws IllegalArgumentException if the revision is out of range (less than 0
136         * and greater than the current revision)
137         */
138        Cursor<ChangeLogEvent> findBefore( long revision ) throws Exception;
139    
140    
141        /**
142         * Finds the ChangeLogEvents that occurred after a revision exclusive.
143         *
144         * This method should exhibit isolation characteristics: meaning if the request is
145         * initiated at revision 100 then any subsequent log entries increasing the revision
146         * should not be seen.
147         *
148         * @param revision the revision number to get the ChangeLogEvents after
149         * @return a Cursor of all the ChangeLogEvents after and including the revision
150         * @throws Exception if there are failures accessing the store
151         * @throws IllegalArgumentException if the revision is out of range (less than 0
152         * and greater than the current revision)
153         */
154        Cursor<ChangeLogEvent> findAfter( long revision ) throws Exception;
155    
156    
157        /**
158         * Finds the ChangeLogEvents that occurred between a revision range inclusive.
159         *
160         * @param startRevision the revision number to start getting the ChangeLogEvents above
161         * @param endRevision the revision number to start getting the ChangeLogEvents below
162         * @return an enumeration of all the ChangeLogEvents within some revision range inclusive
163         * @throws Exception if there are failures accessing the store
164         * @throws IllegalArgumentException if the start and end revisions are out of range
165         * (less than 0 and greater than the current revision), or if startRevision > endRevision
166         */
167        Cursor<ChangeLogEvent> find( long startRevision, long endRevision ) throws Exception;
168    }