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    }