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 */
020package org.apache.directory.server.core.api.changelog;
021
022
023import java.util.List;
024
025import org.apache.directory.api.ldap.model.exception.LdapException;
026import org.apache.directory.api.ldap.model.ldif.LdifEntry;
027import org.apache.directory.server.core.api.DirectoryService;
028import org.apache.directory.server.core.api.LdapPrincipal;
029
030
031/**
032 * A facade for the change log subsystem.  It exposes the functionality
033 * needed to interact with the facility to query for changes, take snapshots,
034 * and revert the server to an earlier revision.
035 *
036 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
037 */
038public 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 LdapException if there is a problem accessing this information
073     */
074    long getCurrentRevision() throws LdapException;
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 LdapException if there are problems logging the change
086     */
087    ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws LdapException;
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 LdapException if there are problems logging the change
099     */
100    ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws LdapException;
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    /**
201     * @return The latest tag
202     * @throws LdapException if there is a problem taking the latest tag
203     */
204    Tag getLatest() throws LdapException;
205
206
207    /**
208     * Initialize the ChangeLog system.
209     * 
210     * @param service The associated DirectoryService
211     * @throws LdapException If the initialization failed
212     */
213    void init( DirectoryService service ) throws LdapException;
214
215
216    /**
217     * Flush the changes to disk
218     * @throws LdapException If the flush failed
219     */
220    void sync() throws LdapException;
221
222
223    /**
224     * Destroy the changeLog
225     * 
226     * @throws LdapException If the destroy failed 
227     */
228    void destroy() throws LdapException;
229
230
231    /**
232     * Exposes the contents of ChangeLog to clients if set to true. Default setting is false.
233     *
234     * @param exposed true to expose the contents, false to not expose.
235     */
236    void setExposed( boolean exposed );
237
238
239    /**
240     * @return true if the changeLog system is visible by clients
241     */
242    boolean isExposed();
243
244
245    /**
246     * The prefix of the partition. Default value is <i>ou=changelog</i>.
247     *
248     * @param suffix suffix value to be set for the changelog partition
249     */
250    void setPartitionSuffix( String suffix );
251
252
253    /**
254     * The name of the revisions container under the partition. Default value is ou=revisions 
255     *
256     * @param revContainerName the name of the revisions container
257     */
258    void setRevisionsContainerName( String revContainerName );
259
260
261    /**
262     * The name of the tags container under the partition. Default value is ou=tags 
263     *
264     * @param tagContainerName the name of the revisions container
265     */
266    void setTagsContainerName( String tagContainerName );
267}