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.DirectoryService;
26 import org.apache.directory.server.core.authn.LdapPrincipal;
27 import org.apache.directory.shared.ldap.ldif.LdifEntry;
28
29
30 /**
31 * A facade for the change log subsystem. It exposes the functionality
32 * needed to interact with the facility to query for changes, take snapshots,
33 * and revert the server to an earlier revision.
34 *
35 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
36 * @version $Rev$, $Date$
37 */
38 public interface ChangeLog
39 {
40 /**
41 * Checks whether or not the change log has been enabled to track changes.
42 *
43 * @return true if the change log is tracking changes, false otherwise
44 */
45 boolean isEnabled();
46
47
48 void setEnabled( boolean enabled );
49
50
51 ChangeLogStore getChangeLogStore();
52
53
54 void setChangeLogStore( ChangeLogStore store );
55
56
57 /**
58 * Gets the current revision for the server.
59 *
60 * @return the current revision
61 * @throws Exception if there is a problem accessing this information
62 */
63 long getCurrentRevision() throws Exception;
64
65
66 /**
67 * Records a change as a forward LDIF, a reverse change to revert the change and
68 * the authorized principal triggering the revertable change event.
69 *
70 * @param principal the authorized LDAP principal triggering the change
71 * @param forward LDIF of the change going to the next state
72 * @param reverse LDIF (anti-operation): the change required to revert this change
73 * @return the new revision reached after having applied the forward LDIF
74 * @throws Exception if there are problems logging the change
75 */
76 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception;
77
78
79 /**
80 * Records a change as a forward LDIF, some reverse changes to revert the change and
81 * the authorized principal triggering the revertable change event.
82 *
83 * @param principal the authorized LDAP principal triggering the change
84 * @param forward LDIF of the change going to the next state
85 * @param reverses LDIF (anti-operation): the changes required to revert this change
86 * @return the new revision reached after having applied the forward LDIF
87 * @throws Exception if there are problems logging the change
88 */
89 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception;
90
91
92 /**
93 * Returns whether or not this ChangeLogService supports searching for changes.
94 *
95 * @return true if log searching is supported, false otherwise
96 */
97 boolean isLogSearchSupported();
98
99
100 /**
101 * Returns whether or not this ChangeLogService supports searching for snapshot tags.
102 *
103 * @return true if snapshot tag searching is supported, false otherwise
104 */
105 boolean isTagSearchSupported();
106
107
108 /**
109 * Returns whether or not this ChangeLogService stores snapshot tags.
110 *
111 * @return true if this ChangeLogService supports tag storage, false otherwise
112 */
113 boolean isTagStorageSupported();
114
115
116 /**
117 * Gets the change log query engine which would be used to ask questions
118 * about what changed, when, how and by whom. It may not be supported by
119 * all implementations. Some implementations may simply log changes without
120 * direct access to those changes from within the server.
121 *
122 * @return the change log query engine
123 * @throws UnsupportedOperationException if the change log is not searchable
124 */
125 ChangeLogSearchEngine getChangeLogSearchEngine();
126
127
128 /**
129 * Gets the tag search engine used to query the snapshots taken. If this ChangeLogService
130 * does not support a taggable and searchable store then an UnsupportedOperationException
131 * will result.
132 *
133 * @return the snapshot query engine for this store
134 * @throws UnsupportedOperationException if the tag searching is not supported
135 */
136 TagSearchEngine getTagSearchEngine();
137
138
139 /**
140 * Creates a tag for a snapshot of the server in a specific state at a revision.
141 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it
142 * does not then it's up to callers to track this tag since it will not be stored
143 * by this service.
144 *
145 * @param revision the revision to tag the snapshot
146 * @return the Tag associated with the revision
147 * @throws Exception if there is a problem taking a tag
148 * @throws IllegalArgumentException if the revision is out of range (less than 0
149 * and greater than the current revision)
150 */
151 Tag tag( long revision ) throws Exception;
152
153
154 /**
155 * Creates a tag for a snapshot of the server in a specific state at a revision.
156 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it
157 * does not then it's up to callers to track this tag since it will not be stored
158 * by this service.
159 *
160 * @param revision the revision to tag the snapshot
161 * @param description some information about what the snapshot tag represents
162 * @return the Tag associated with the revision
163 * @throws Exception if there is a problem taking a tag
164 * @throws IllegalArgumentException if the revision is out of range (less than 0
165 * and greater than the current revision)
166 */
167 Tag tag( long revision, String description ) throws Exception;
168
169
170 /**
171 * Creates a snapshot of the server at the current revision.
172 *
173 * @param description some information about what the snapshot tag represents
174 * @return the revision at which the tag is created
175 * @throws Exception if there is a problem taking a tag
176 */
177 Tag tag( String description ) throws Exception;
178
179
180 /**
181 * Creates a snapshot of the server at the current revision.
182 *
183 * @return the revision at which the tag is created
184 * @throws Exception if there is a problem taking a tag
185 */
186 Tag tag() throws Exception;
187
188 Tag getLatest() throws Exception;
189
190 void init( DirectoryService service ) throws Exception;
191
192 void sync() throws Exception;
193
194 void destroy() throws Exception;
195
196 /**
197 * Exposes the contents of ChangeLog to clients if set to true. Default setting is false.
198 *
199 * @param exposeChangeLog true to expose the contents, false to not expose.
200 */
201 void setExposeChangeLog( boolean exposeChangeLog );
202
203 boolean isExposeChangeLog();
204
205 /**
206 * The prefix of the partition. Default value is <i>ou=changelog</i>.
207 *
208 * @param suffix suffix value to be set for the changelog partition
209 */
210 void setPartitionSuffix( String suffix );
211
212 /**
213 * The name of the revisions container under the partition. Default value is ou=revisions
214 *
215 * @param revContainerName the name of the revisions container
216 */
217 void setRevisionsContainerName( String revContainerName );
218
219 /**
220 * The name of the tags container under the partition. Default value is ou=tags
221 *
222 * @param tagContainerName the name of the revisions container
223 */
224 void setTagsContainerName( String tagContainerName );
225 }