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.DirectoryService;
026 import org.apache.directory.server.core.LdapPrincipal;
027 import org.apache.directory.shared.ldap.ldif.LdifEntry;
028
029
030 /**
031 * A facade for the change log subsystem. It exposes the functionality
032 * needed to interact with the facility to query for changes, take snapshots,
033 * and revert the server to an earlier revision.
034 *
035 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
036 * @version $Rev$, $Date$
037 */
038 public interface ChangeLog
039 {
040 /**
041 * Checks whether or not the change log has been enabled to track changes.
042 *
043 * @return true if the change log is tracking changes, false otherwise
044 */
045 boolean isEnabled();
046
047
048 /**
049 * Enable or disable the ChangeLog service
050 * @param enabled true to enable the service, flase to disable it
051 */
052 void setEnabled( boolean enabled );
053
054
055 /**
056 * @return The underlying storage
057 */
058 ChangeLogStore getChangeLogStore();
059
060
061 /**
062 * Set the underlying storage
063 * @param store The storage
064 */
065 void setChangeLogStore( ChangeLogStore store );
066
067
068 /**
069 * Gets the current revision for the server.
070 *
071 * @return the current revision
072 * @throws Exception if there is a problem accessing this information
073 */
074 long getCurrentRevision() throws Exception;
075
076
077 /**
078 * Records a change as a forward LDIF, a reverse change to revert the change and
079 * the authorized principal triggering the revertable change event.
080 *
081 * @param principal the authorized LDAP principal triggering the change
082 * @param forward LDIF of the change going to the next state
083 * @param reverse LDIF (anti-operation): the change required to revert this change
084 * @return the new revision reached after having applied the forward LDIF
085 * @throws Exception if there are problems logging the change
086 */
087 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception;
088
089
090 /**
091 * Records a change as a forward LDIF, some reverse changes to revert the change and
092 * the authorized principal triggering the revertable change event.
093 *
094 * @param principal the authorized LDAP principal triggering the change
095 * @param forward LDIF of the change going to the next state
096 * @param reverses LDIF (anti-operation): the changes required to revert this change
097 * @return the new revision reached after having applied the forward LDIF
098 * @throws Exception if there are problems logging the change
099 */
100 ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception;
101
102
103 /**
104 * Returns whether or not this ChangeLogService supports searching for changes.
105 *
106 * @return true if log searching is supported, false otherwise
107 */
108 boolean isLogSearchSupported();
109
110
111 /**
112 * Returns whether or not this ChangeLogService supports searching for snapshot tags.
113 *
114 * @return true if snapshot tag searching is supported, false otherwise
115 */
116 boolean isTagSearchSupported();
117
118
119 /**
120 * Returns whether or not this ChangeLogService stores snapshot tags.
121 *
122 * @return true if this ChangeLogService supports tag storage, false otherwise
123 */
124 boolean isTagStorageSupported();
125
126
127 /**
128 * Gets the change log query engine which would be used to ask questions
129 * about what changed, when, how and by whom. It may not be supported by
130 * all implementations. Some implementations may simply log changes without
131 * direct access to those changes from within the server.
132 *
133 * @return the change log query engine
134 * @throws UnsupportedOperationException if the change log is not searchable
135 */
136 ChangeLogSearchEngine getChangeLogSearchEngine();
137
138
139 /**
140 * Gets the tag search engine used to query the snapshots taken. If this ChangeLogService
141 * does not support a taggable and searchable store then an UnsupportedOperationException
142 * will result.
143 *
144 * @return the snapshot query engine for this store
145 * @throws UnsupportedOperationException if the tag searching is not supported
146 */
147 TagSearchEngine getTagSearchEngine();
148
149
150 /**
151 * Creates a tag for a snapshot of the server in a specific state at a revision.
152 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it
153 * does not then it's up to callers to track this tag since it will not be stored
154 * by this service.
155 *
156 * @param revision the revision to tag the snapshot
157 * @return the Tag associated with the revision
158 * @throws Exception if there is a problem taking a tag
159 * @throws IllegalArgumentException if the revision is out of range (less than 0
160 * and greater than the current revision)
161 */
162 Tag tag( long revision ) throws Exception;
163
164
165 /**
166 * Creates a tag for a snapshot of the server in a specific state at a revision.
167 * If the ChangeLog has a TaggableChangeLogStore then the tag is stored. If it
168 * does not then it's up to callers to track this tag since it will not be stored
169 * by this service.
170 *
171 * @param revision the revision to tag the snapshot
172 * @param description some information about what the snapshot tag represents
173 * @return the Tag associated with the revision
174 * @throws Exception if there is a problem taking a tag
175 * @throws IllegalArgumentException if the revision is out of range (less than 0
176 * and greater than the current revision)
177 */
178 Tag tag( long revision, String description ) throws Exception;
179
180
181 /**
182 * Creates a snapshot of the server at the current revision.
183 *
184 * @param description some information about what the snapshot tag represents
185 * @return the revision at which the tag is created
186 * @throws Exception if there is a problem taking a tag
187 */
188 Tag tag( String description ) throws Exception;
189
190
191 /**
192 * Creates a snapshot of the server at the current revision.
193 *
194 * @return the revision at which the tag is created
195 * @throws Exception if there is a problem taking a tag
196 */
197 Tag tag() throws Exception;
198
199 /**
200 * @return The latest tag
201 * @throws Exception if there is a problem taking the latest tag
202 */
203 Tag getLatest() throws Exception;
204
205 /**
206 * Initialize the ChangeLog system.
207 *
208 * @param service The associated DirectoryService
209 * @throws Exception
210 */
211 void init( DirectoryService service ) throws Exception;
212
213 /**
214 * Flush the changes to disk
215 * @throws Exception If the flush failed
216 */
217 void sync() throws Exception;
218
219 /**
220 * Destroy the changeLog
221 * @throws Exception
222 */
223 void destroy() throws Exception;
224
225 /**
226 * Exposes the contents of ChangeLog to clients if set to true. Default setting is false.
227 *
228 * @param exposed true to expose the contents, false to not expose.
229 */
230 void setExposed( boolean exposed );
231
232 /**
233 * @return true if the changeLog system is visible by clients
234 */
235 boolean isExposed();
236
237 /**
238 * The prefix of the partition. Default value is <i>ou=changelog</i>.
239 *
240 * @param suffix suffix value to be set for the changelog partition
241 */
242 void setPartitionSuffix( String suffix );
243
244 /**
245 * The name of the revisions container under the partition. Default value is ou=revisions
246 *
247 * @param revContainerName the name of the revisions container
248 */
249 void setRevisionsContainerName( String revContainerName );
250
251 /**
252 * The name of the tags container under the partition. Default value is ou=tags
253 *
254 * @param tagContainerName the name of the revisions container
255 */
256 void setTagsContainerName( String tagContainerName );
257 }