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 org.apache.directory.api.ldap.model.cursor.Cursor; 24 import org.apache.directory.api.ldap.model.filter.ExprNode; 25 import org.apache.directory.api.ldap.model.ldif.ChangeType; 26 import org.apache.directory.api.ldap.model.message.SearchScope; 27 import org.apache.directory.api.ldap.model.name.Dn; 28 import org.apache.directory.api.ldap.model.schema.AttributeType; 29 import org.apache.directory.api.ldap.model.schema.ObjectClass; 30 import org.apache.directory.server.core.api.LdapPrincipal; 31 32 33 /** 34 * A custom search engine designed for optimized searching across ChangeLogEvents 35 * within the ChangeLogStore. The following lookup and search operations are 36 * provided: 37 * 38 * <ul> 39 * <li>lookup change by revision</li> 40 * <li>lookup change by date</li> 41 * <li>find all changes</li> 42 * <li>find all changes before or after a revision</li> 43 * <li>find all changes in a revision range</li> 44 * <li>find changes by LDAP namespace scope on Dn</li> 45 * <li>find changes by Dn</li> 46 * <li>find changes by principal</li> 47 * <li>find changes by change type</li> 48 * <li>find changes by attribute</li> 49 * <li>find changes using a restricted LDAP filter on all of the above factors</li> 50 * </ul> 51 * 52 * Note change lookups by date can be conducted by first looking up a revision 53 * using a generalizedTime descriptor to find a revision. Then these revisions 54 * can be plugged into the revision based find and lookup methods. 55 * 56 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> 57 */ 58 public interface ChangeLogSearchEngine 59 { 60 /** 61 * Looks up the revision in effect at some time specified by a generalized 62 * time descriptor. 63 * 64 * @param generalizedTime the generalized time descriptor to find the effective revision for 65 * @return the revision that was in effect at a certain time 66 * @throws Exception if there are failures accessing the store 67 */ 68 long lookup( String generalizedTime ) throws Exception; 69 70 71 /** 72 * Looks up the ChangeLogEvent for a revision. 73 * 74 * @param revision to get a ChangeLogEvent for 75 * @return the ChangeLogEvent associated with the revision 76 * @throws Exception if there are failures accessing the store 77 * @throws IllegalArgumentException if the revision is out of range (less than 0 78 * and greater than the current revision) 79 */ 80 ChangeLogEvent lookup( long revision ) throws Exception; 81 82 83 /** 84 * Finds all the ChangeLogEvents within the system since revision 0. 85 * 86 * This method should exhibit isolation characteristics: meaning if the request is 87 * initiated at revision 100 then any subsequent log entries increasing the revision 88 * should not be seen. 89 * 90 * @param order the order in which to return ChangeLogEvents (ordered by revision number) 91 * @return an enumeration of all the ChangeLogEvents 92 * @throws Exception if there are failures accessing the store 93 */ 94 Cursor<ChangeLogEvent> find( RevisionOrder order ) throws Exception; 95 96 97 /** 98 * Finds the ChangeLogEvents that occurred before a revision inclusive. 99 * 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, SearchScope 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 }