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 }