1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.directory.server.core.changelog;
21
22
23 import java.util.List;
24
25 import org.apache.directory.server.core.authn.LdapPrincipal;
26 import org.apache.directory.server.core.cursor.Cursor;
27 import org.apache.directory.server.core.DirectoryService;
28 import org.apache.directory.shared.ldap.ldif.LdifEntry;
29
30
31
32 /**
33 * A store for change events on the directory which exposes methods for
34 * managing, querying and in general performing legal operations on the log.
35 *
36 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
37 * @version $Rev$, $Date$
38 */
39 public interface ChangeLogStore
40 {
41 void init( DirectoryService service ) throws Exception;
42
43
44 void sync() throws Exception;
45
46
47 void destroy() throws Exception;
48
49
50 /**
51 * Gets the current revision of the server (a.k.a. the HEAD revision).
52 *
53 * @return the current revision of the server
54 */
55 long getCurrentRevision();
56
57
58 /**
59 * Records a change as a forward LDIF, a reverse change to revert the change and
60 * the authorized principal triggering the revertable change event.
61 *
62 * @param principal the authorized LDAP principal triggering the change
63 * @param forward LDIF of the change going to the next state
64 * @param reverse LDIF (anti-operation): the change required to revert this change
65 * @return the new revision reached after having applied the forward LDIF
66 * @throws Exception if there are problems logging the change
67 */
68 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception;
69
70
71 /**
72 * Records a change as a forward LDIF, some reverse changes to revert the change and
73 * the authorized principal triggering the revertable change event.
74 *
75 * @param principal the authorized LDAP principal triggering the change
76 * @param forward LDIF of the change going to the next state
77 * @param reverses LDIF (anti-operation): the changes required to revert this change
78 * @return the new revision reached after having applied the forward LDIF
79 * @throws Exception if there are problems logging the change
80 */
81 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception;
82
83
84 /**
85 * Looks up the ChangeLogEvent for a revision.
86 *
87 * @param revision to get a ChangeLogEvent for
88 * @return the ChangeLogEvent associated with the revision
89 * @throws Exception if there are failures accessing the store
90 * @throws IllegalArgumentException if the revision is out of range (less than 0
91 * and greater than the current revision)
92 */
93 ChangeLogEvent lookup( long revision ) throws Exception;
94
95
96 /**
97 * Gets a Cursor over all the ChangeLogEvents within the system since
98 * revision 0.
99 *
100 * This method should exhibit isolation characteristics: meaning if the
101 * request is initiated at revision 100, then any subsequent log entries
102 * increasing the revision should not be seen.
103 *
104 * @return a Cursor over all the ChangeLogEvents
105 * @throws Exception if there are failures accessing the store
106 */
107 Cursor<ChangeLogEvent> find() throws Exception;
108
109
110 /**
111 * Gets a Cursor over the ChangeLogEvents that occurred before a revision
112 * exclusive.
113 *
114 * @param revision the revision number to get the ChangeLogEvents before
115 * @return a Cursor over the ChangeLogEvents before a revision
116 * @throws Exception if there are failures accessing the store
117 * @throws IllegalArgumentException if the revision is out of range (less than 0
118 * and greater than the current revision)
119 */
120 Cursor<ChangeLogEvent> findBefore( long revision ) throws Exception;
121
122
123 /**
124 * Finds the ChangeLogEvents that occurred after a revision exclusive.
125 *
126 * This method should exhibit isolation characteristics: meaning if the request is
127 * initiated at revision 100 then any subsequent log entries increasing the revision
128 * should not be seen.
129 *
130 * @param revision the revision number to get the ChangeLogEvents after
131 * @return a Cursor of all the ChangeLogEvents after and including the revision
132 * @throws Exception if there are failures accessing the store
133 * @throws IllegalArgumentException if the revision is out of range (less than 0
134 * and greater than the current revision)
135 */
136 Cursor<ChangeLogEvent> findAfter( long revision ) throws Exception;
137
138
139 /**
140 * Finds the ChangeLogEvents that occurred between a revision range inclusive.
141 *
142 * @param startRevision the revision number to start getting the ChangeLogEvents above
143 * @param endRevision the revision number to start getting the ChangeLogEvents below
144 * @return an enumeration of all the ChangeLogEvents within some revision range inclusive
145 * @throws Exception if there are failures accessing the store
146 * @throws IllegalArgumentException if the start and end revisions are out of range
147 * (less than 0 and greater than the current revision), or if startRevision > endRevision
148 */
149 Cursor<ChangeLogEvent> find( long startRevision, long endRevision ) throws Exception;
150 }