View Javadoc
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.exception.LdapException;
26  import org.apache.directory.api.ldap.model.ldif.LdifEntry;
27  import org.apache.directory.server.core.api.DirectoryService;
28  import org.apache.directory.server.core.api.LdapPrincipal;
29  
30  
31  /**
32   * A facade for the change log subsystem.  It exposes the functionality
33   * needed to interact with the facility to query for changes, take snapshots,
34   * and revert the server to an earlier revision.
35   *
36   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
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      /**
49       * Enable or disable the ChangeLog service
50       * @param enabled true to enable the service, flase to disable it
51       */
52      void setEnabled( boolean enabled );
53  
54  
55      /**
56       * @return The underlying storage
57       */
58      ChangeLogStore getChangeLogStore();
59  
60  
61      /**
62       * Set the underlying storage
63       * @param store The storage
64       */
65      void setChangeLogStore( ChangeLogStore store );
66  
67  
68      /**
69       * Gets the current revision for the server.
70       *
71       * @return the current revision
72       * @throws LdapException if there is a problem accessing this information
73       */
74      long getCurrentRevision() throws LdapException;
75  
76  
77      /**
78       * Records a change as a forward LDIF, a reverse change to revert the change and
79       * the authorized principal triggering the revertable change event.
80       *
81       * @param principal the authorized LDAP principal triggering the change
82       * @param forward LDIF of the change going to the next state
83       * @param reverse LDIF (anti-operation): the change required to revert this change
84       * @return the new revision reached after having applied the forward LDIF
85       * @throws LdapException if there are problems logging the change
86       */
87      ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws LdapException;
88  
89  
90      /**
91       * Records a change as a forward LDIF, some reverse changes to revert the change and
92       * the authorized principal triggering the revertable change event.
93       *
94       * @param principal the authorized LDAP principal triggering the change
95       * @param forward LDIF of the change going to the next state
96       * @param reverses LDIF (anti-operation): the changes required to revert this change
97       * @return the new revision reached after having applied the forward LDIF
98       * @throws LdapException if there are problems logging the change
99       */
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 }