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.api.changelog;
21
22
23 import java.util.List;
24
25 import org.apache.directory.api.ldap.model.cursor.Cursor;
26 import org.apache.directory.api.ldap.model.exception.LdapException;
27 import org.apache.directory.api.ldap.model.ldif.LdifEntry;
28 import org.apache.directory.server.core.api.DirectoryService;
29 import org.apache.directory.server.core.api.LdapPrincipal;
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 */
38 public interface ChangeLogStore
39 {
40 /**
41 * Initialize the store.
42 *
43 * @param service The associated DirectoryService
44 * @throws LdapException If the initialization failed
45 */
46 void init( DirectoryService service ) throws LdapException;
47
48
49 /**
50 * Write the changes on disk
51 *
52 * @throws LdapException If the write failed
53 */
54 void sync() throws LdapException;
55
56
57 /**
58 * Destroy the logs.
59 *
60 * @throws LdapException If we can't destroy the logs
61 */
62 void destroy() throws LdapException;
63
64
65 /**
66 * Gets the current revision of the server (a.k.a. the HEAD revision).
67 *
68 * @return the current revision of the server
69 */
70 long getCurrentRevision();
71
72
73 /**
74 * Records a change as a forward LDIF, a reverse change to revert the change and
75 * the authorized principal triggering the revertable change event.
76 *
77 * @param principal the authorized LDAP principal triggering the change
78 * @param forward LDIF of the change going to the next state
79 * @param reverse LDIF (anti-operation): the change required to revert this change
80 * @return the new revision reached after having applied the forward LDIF
81 */
82 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse );
83
84
85 /**
86 * Records a change as a forward LDIF, some reverse changes to revert the change and
87 * the authorized principal triggering the revertable change event.
88 *
89 * @param principal the authorized LDAP principal triggering the change
90 * @param forward LDIF of the change going to the next state
91 * @param reverses LDIF (anti-operation): the changes required to revert this change
92 * @return the new revision reached after having applied the forward LDIF
93 */
94 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses );
95
96
97 /**
98 * Looks up the ChangeLogEvent for a revision.
99 *
100 * @param revision to get a ChangeLogEvent for
101 * @return the ChangeLogEvent associated with the revision
102 * @throws IllegalArgumentException if the revision is out of range (less than 0
103 * and greater than the current revision)
104 */
105 ChangeLogEvent lookup( long revision );
106
107
108 /**
109 * Gets a Cursor over all the ChangeLogEvents within the system since
110 * revision 0.
111 *
112 * This method should exhibit isolation characteristics: meaning if the
113 * request is initiated at revision 100, then any subsequent log entries
114 * increasing the revision should not be seen.
115 *
116 * @return a Cursor over all the ChangeLogEvents
117 */
118 Cursor<ChangeLogEvent> find();
119
120
121 /**
122 * Gets a Cursor over the ChangeLogEvents that occurred before a revision
123 * exclusive.
124 *
125 * @param revision the revision number to get the ChangeLogEvents before
126 * @return a Cursor over the ChangeLogEvents before a revision
127 * @throws IllegalArgumentException if the revision is out of range (less than 0
128 * and greater than the current revision)
129 */
130 Cursor<ChangeLogEvent> findBefore( long revision );
131
132
133 /**
134 * Finds the ChangeLogEvents that occurred after a revision exclusive.
135 *
136 * This method should exhibit isolation characteristics: meaning if the request is
137 * initiated at revision 100 then any subsequent log entries increasing the revision
138 * should not be seen.
139 *
140 * @param revision the revision number to get the ChangeLogEvents after
141 * @return a Cursor of all the ChangeLogEvents after and including the revision
142 * @throws IllegalArgumentException if the revision is out of range (less than 0
143 * and greater than the current revision)
144 */
145 Cursor<ChangeLogEvent> findAfter( long revision );
146
147
148 /**
149 * Finds the ChangeLogEvents that occurred between a revision range inclusive.
150 *
151 * @param startRevision the revision number to start getting the ChangeLogEvents above
152 * @param endRevision the revision number to start getting the ChangeLogEvents below
153 * @return an enumeration of all the ChangeLogEvents within some revision range inclusive
154 * @throws IllegalArgumentException if the start and end revisions are out of range
155 * (less than 0 and greater than the current revision), or if startRevision > endRevision
156 */
157 Cursor<ChangeLogEvent> find( long startRevision, long endRevision );
158 }