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    }