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.authn.LdapPrincipal;
26  import org.apache.directory.server.core.cursor.Cursor;
27  import org.apache.directory.server.core.DirectoryService;
28  import org.apache.directory.shared.ldap.ldif.LdifEntry;
29  
30  
31  
32  /**
33   * A store for change events on the directory which exposes methods for 
34   * managing, querying and in general performing legal operations on the log.
35   *
36   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
37   * @version $Rev$, $Date$
38   */
39  public interface ChangeLogStore 
40  {
41      void init( DirectoryService service ) throws Exception;
42  
43  
44      void sync() throws Exception;
45  
46  
47      void destroy() throws Exception;
48  
49  
50      /**
51       * Gets the current revision of the server (a.k.a. the HEAD revision).
52       *
53       * @return the current revision of the server
54       */
55      long getCurrentRevision();
56  
57  
58      /**
59       * Records a change as a forward LDIF, a reverse change to revert the change and
60       * the authorized principal triggering the revertable change event.
61       *
62       * @param principal the authorized LDAP principal triggering the change
63       * @param forward LDIF of the change going to the next state
64       * @param reverse LDIF (anti-operation): the change required to revert this change
65       * @return the new revision reached after having applied the forward LDIF
66       * @throws Exception if there are problems logging the change
67       */
68      ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, LdifEntry reverse ) throws Exception;
69  
70      
71      /**
72       * Records a change as a forward LDIF, some reverse changes to revert the change and
73       * the authorized principal triggering the revertable change event.
74       *
75       * @param principal the authorized LDAP principal triggering the change
76       * @param forward LDIF of the change going to the next state
77       * @param reverses LDIF (anti-operation): the changes required to revert this change
78       * @return the new revision reached after having applied the forward LDIF
79       * @throws Exception if there are problems logging the change
80       */
81      ChangeLogEvent log( LdapPrincipal principal, LdifEntry forward, List<LdifEntry> reverses ) throws Exception;
82  
83      
84      /**
85       * Looks up the ChangeLogEvent for a revision.
86       *
87       * @param revision to get a ChangeLogEvent for
88       * @return the ChangeLogEvent associated with the revision
89       * @throws Exception if there are failures accessing the store
90       * @throws IllegalArgumentException if the revision is out of range (less than 0
91       * and greater than the current revision)
92       */
93      ChangeLogEvent lookup( long revision ) throws Exception;
94  
95  
96      /**
97       * Gets a Cursor over all the ChangeLogEvents within the system since
98       * revision 0.
99       *
100      * This method should exhibit isolation characteristics: meaning if the
101      * request is initiated at revision 100, then any subsequent log entries
102      * increasing the revision should not be seen.
103      *
104      * @return a Cursor over all the ChangeLogEvents
105      * @throws Exception if there are failures accessing the store
106      */
107     Cursor<ChangeLogEvent> find() throws Exception;
108 
109 
110     /**
111      * Gets a Cursor over the ChangeLogEvents that occurred before a revision
112      * exclusive.
113      *
114      * @param revision the revision number to get the ChangeLogEvents before
115      * @return a Cursor over the ChangeLogEvents before a revision
116      * @throws Exception if there are failures accessing the store
117      * @throws IllegalArgumentException if the revision is out of range (less than 0
118      * and greater than the current revision)
119      */
120     Cursor<ChangeLogEvent> findBefore( long revision ) throws Exception;
121 
122 
123     /**
124      * Finds the ChangeLogEvents that occurred after a revision exclusive.
125      *
126      * This method should exhibit isolation characteristics: meaning if the request is
127      * initiated at revision 100 then any subsequent log entries increasing the revision
128      * should not be seen.
129      *
130      * @param revision the revision number to get the ChangeLogEvents after
131      * @return a Cursor of all the ChangeLogEvents after and including the revision
132      * @throws Exception if there are failures accessing the store
133      * @throws IllegalArgumentException if the revision is out of range (less than 0
134      * and greater than the current revision)
135      */
136     Cursor<ChangeLogEvent> findAfter( long revision ) throws Exception;
137 
138 
139     /**
140      * Finds the ChangeLogEvents that occurred between a revision range inclusive.
141      *
142      * @param startRevision the revision number to start getting the ChangeLogEvents above
143      * @param endRevision the revision number to start getting the ChangeLogEvents below
144      * @return an enumeration of all the ChangeLogEvents within some revision range inclusive
145      * @throws Exception if there are failures accessing the store
146      * @throws IllegalArgumentException if the start and end revisions are out of range
147      * (less than 0 and greater than the current revision), or if startRevision > endRevision
148      */
149     Cursor<ChangeLogEvent> find( long startRevision, long endRevision ) throws Exception;
150 }