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 org.apache.directory.server.core.LdapPrincipal;
024 import org.apache.directory.shared.ldap.cursor.Cursor;
025 import org.apache.directory.shared.ldap.filter.ExprNode;
026 import org.apache.directory.shared.ldap.ldif.ChangeType;
027 import org.apache.directory.shared.ldap.name.DN;
028 import org.apache.directory.shared.ldap.schema.AttributeType;
029 import org.apache.directory.shared.ldap.schema.ObjectClass;
030
031
032 /**
033 * A custom search engine designed for optimized searching across ChangeLogEvents
034 * within the ChangeLogStore. The following lookup and search operations are
035 * provided:
036 *
037 * <ul>
038 * <li>lookup change by revision</li>
039 * <li>lookup change by date</li>
040 * <li>find all changes</li>
041 * <li>find all changes before or after a revision</li>
042 * <li>find all changes in a revision range</li>
043 * <li>find changes by LDAP namespace scope on DN</li>
044 * <li>find changes by DN</li>
045 * <li>find changes by principal</li>
046 * <li>find changes by change type</li>
047 * <li>find changes by attribute</li>
048 * <li>find changes using a restricted LDAP filter on all of the above factors</li>
049 * </ul>
050 *
051 * Note change lookups by date can be conducted by first looking up a revision
052 * using a generalizedTime descriptor to find a revision. Then these revisions
053 * can be plugged into the revision based find and lookup methods.
054 *
055 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
056 * @version $Rev$, $Date$
057 */
058 public interface ChangeLogSearchEngine
059 {
060 /**
061 * Looks up the revision in effect at some time specified by a generalized
062 * time descriptor.
063 *
064 * @param generalizedTime the generalized time descriptor to find the effective revision for
065 * @return the revision that was in effect at a certain time
066 * @throws Exception if there are failures accessing the store
067 */
068 long lookup( String generalizedTime ) throws Exception;
069
070
071 /**
072 * Looks up the ChangeLogEvent for a revision.
073 *
074 * @param revision to get a ChangeLogEvent for
075 * @return the ChangeLogEvent associated with the revision
076 * @throws Exception if there are failures accessing the store
077 * @throws IllegalArgumentException if the revision is out of range (less than 0
078 * and greater than the current revision)
079 */
080 ChangeLogEvent lookup( long revision ) throws Exception;
081
082
083 /**
084 * Finds all the ChangeLogEvents within the system since revision 0.
085 *
086 * This method should exhibit isolation characteristics: meaning if the request is
087 * initiated at revision 100 then any subsequent log entries increasing the revision
088 * should not be seen.
089 *
090 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
091 * @return an enumeration of all the ChangeLogEvents
092 * @throws Exception if there are failures accessing the store
093 */
094 Cursor<ChangeLogEvent> find( RevisionOrder order ) throws Exception;
095
096
097 /**
098 * Finds the ChangeLogEvents that occurred before a revision inclusive.
099 *
100 * @param revision the revision number to get the ChangeLogEvents before
101 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
102 * @return an enumeration of all the ChangeLogEvents before and including some revision
103 * @throws Exception if there are failures accessing the store
104 * @throws IllegalArgumentException if the revision is out of range (less than 0
105 * and greater than the current revision)
106 */
107 Cursor<ChangeLogEvent> findBefore( long revision, RevisionOrder order ) throws Exception;
108
109
110 /**
111 * Finds the ChangeLogEvents that occurred after a revision inclusive.
112 *
113 * This method should exhibit isolation characteristics: meaning if the request is
114 * initiated at revision 100 then any subsequent log entries increasing the revision
115 * should not be seen.
116 *
117 * @param revision the revision number to get the ChangeLogEvents after
118 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
119 * @return an enumeration of all the ChangeLogEvents after and including the revision
120 * @throws Exception if there are failures accessing the store
121 * @throws IllegalArgumentException if the revision is out of range (less than 0
122 * and greater than the current revision)
123 */
124 Cursor<ChangeLogEvent> findAfter( long revision, RevisionOrder order ) throws Exception;
125
126
127 /**
128 * Finds the ChangeLogEvents that occurred between a revision range inclusive.
129 *
130 * @param startRevision the revision number to start getting the ChangeLogEvents above
131 * @param endRevision the revision number to start getting the ChangeLogEvents below
132 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
133 * @return an enumeration of all the ChangeLogEvents within some revision range inclusive
134 * @throws Exception if there are failures accessing the store
135 * @throws IllegalArgumentException if the start and end revisions are out of range
136 * (less than 0 and greater than the current revision), or if startRevision > endRevision
137 */
138 Cursor<ChangeLogEvent> find( long startRevision, long endRevision, RevisionOrder order )
139 throws Exception;
140
141
142 /**
143 * Finds all the ChangeLogEvents on an entry.
144 *
145 * @param dn the normalized DN of the entry to get ChangeLogEvents for
146 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
147 * @return the set of changes that occurred on an entry
148 * @throws Exception if there are failures accessing the store
149 */
150 Cursor<ChangeLogEvent> find( DN dn, RevisionOrder order ) throws Exception;
151
152
153 /**
154 * Finds all the ChangeLogEvents on an entry base and/or it's children/descendants.
155 *
156 * @param base the normalized DN of the entry base to get ChangeLogEvents for
157 * @param scope the scope of the search under the base similar to LDAP search scope
158 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
159 * @return the set of changes that occurred on an entry and/or it's descendants depending on the scope
160 * @throws Exception if there are failures accessing the store
161 */
162 Cursor<ChangeLogEvent> find( DN base, Scope scope, RevisionOrder order ) throws Exception;
163
164
165 /**
166 * Finds all the ChangeLogEvents triggered by a principal in the system.
167 *
168 * @param principal the LDAP principal who triggered the events
169 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
170 * @return the set of changes that were triggered by a specific LDAP user
171 * @throws Exception if there are failures accessing the store
172 */
173 Cursor<ChangeLogEvent> find( LdapPrincipal principal, RevisionOrder order ) throws Exception;
174
175
176 /**
177 * Finds all the ChangeLogEvents of a particular change type.
178 *
179 * @param changeType the change type of the ChangeLogEvents to search for
180 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
181 * @return the set of ChangeLogEvents of a particular ChangeType
182 * @throws Exception if there are failures accessing the store
183 */
184 Cursor<ChangeLogEvent> find( ChangeType changeType, RevisionOrder order ) throws Exception;
185
186
187 /**
188 * Finds all the ChangeLogEvents altering a particular attributeType.
189 *
190 * @param attributeType the attributeType definition for the changed attribute to search changes for
191 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
192 * @return the set of ChangeLogEvents on a particular attributeType
193 * @throws Exception if there are failures accessing the store
194 */
195 Cursor<ChangeLogEvent> find( AttributeType attributeType, RevisionOrder order ) throws Exception;
196
197
198 /**
199 * Finds all the ChangeLogEvents altering a particular objectClass.
200 *
201 * @param objectClass the objectClass definition for the entries to search changes for
202 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
203 * @return the set of ChangeLogEvents on a particular attributeType
204 * @throws Exception if there are failures accessing the store
205 */
206 Cursor<ChangeLogEvent> find( ObjectClass objectClass, RevisionOrder order ) throws Exception;
207
208
209 /**
210 * Finds all the ChangeLogEvents matched by the filter expression tree parameter.
211 *
212 * The following attributes can be used in the constrained LDAP filter expression
213 * tree. The expression must be normalized and can contain only ATA pairs with the
214 * following set of attributes:
215 *
216 * <ul>
217 * <li>ndn: normalized distinguishedName syntax (defaults to matching a string)</li>
218 * <li>date: generalizedTime syntax</li>
219 * <li>revision: integer syntax</li>
220 * <li>attributeType: numeric OID</li>
221 * <li>objectClass: numeric OID</li>
222 * <li>changeType: new changeType syntax</li>
223 * <li>principal: normalized distinguishedName syntax (defaults to matching a string)</li>
224 * </ul>
225 *
226 * The following are the only kinds of AVA node types allowed:
227 *
228 * <ul>
229 * <li>equality (=) </li>
230 * <li>greaterThanEq (>=) </li>
231 * <li>lessThanEq (<=) </li>
232 * <li>scope (specialized) </li>
233 * </ul>
234 *
235 * @param filter the filter to use for finding the change
236 * @param order the order in which to return ChangeLogEvents (ordered by revision number)
237 * @return the set of ChangeLogEvents on entries of a particular objectClass
238 * @throws Exception if there are failures accessing the store
239 */
240 Cursor<ChangeLogEvent> find( ExprNode filter, RevisionOrder order ) throws Exception;
241 }