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.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 }