org.apache.directory.server.core.api.changelog

Interface ChangeLogSearchEngine

public interface ChangeLogSearchEngine

A custom search engine designed for optimized searching across ChangeLogEvents within the ChangeLogStore. The following lookup and search operations are provided:

• lookup change by revision
• lookup change by date
• find all changes
• find all changes before or after a revision
• find all changes in a revision range
• find changes by LDAP namespace scope on Dn
• find changes by Dn
• find changes by principal
• find changes by change type
• find changes by attribute
• find changes using a restricted LDAP filter on all of the above factors

Note change lookups by date can be conducted by first looking up a revision using a generalizedTime descriptor to find a revision. Then these revisions can be plugged into the revision based find and lookup methods.

Author:

Apache Directory Project

Method Summary

Modifier and Type	Method and Description
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.schema.AttributeType attributeType, RevisionOrder order) Finds all the ChangeLogEvents altering a particular attributeType.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.ldif.ChangeType changeType, RevisionOrder order) Finds all the ChangeLogEvents of a particular change type.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.name.Dn dn, RevisionOrder order) Finds all the ChangeLogEvents on an entry.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.name.Dn base, org.apache.directory.api.ldap.model.message.SearchScope scope, RevisionOrder order) Finds all the ChangeLogEvents on an entry base and/or it's children/descendants.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.filter.ExprNode filter, RevisionOrder order) Finds all the ChangeLogEvents matched by the filter expression tree parameter.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(LdapPrincipal principal, RevisionOrder order) Finds all the ChangeLogEvents triggered by a principal in the system.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(long startRevision, long endRevision, RevisionOrder order) Finds the ChangeLogEvents that occurred between a revision range inclusive.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(org.apache.directory.api.ldap.model.schema.ObjectClass objectClass, RevisionOrder order) Finds all the ChangeLogEvents altering a particular objectClass.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	find(RevisionOrder order) Finds all the ChangeLogEvents within the system since revision 0.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	findAfter(long revision, RevisionOrder order) Finds the ChangeLogEvents that occurred after a revision inclusive.
org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent>	findBefore(long revision, RevisionOrder order) Finds the ChangeLogEvents that occurred before a revision inclusive.
ChangeLogEvent	lookup(long revision) Looks up the ChangeLogEvent for a revision.
long	lookup(String generalizedTime) Looks up the revision in effect at some time specified by a generalized time descriptor.

Method Detail

lookup

long lookup(String generalizedTime)
     throws Exception

Looks up the revision in effect at some time specified by a generalized time descriptor.

Parameters:

generalizedTime - the generalized time descriptor to find the effective revision for

Returns:

the revision that was in effect at a certain time

Throws:

Exception - if there are failures accessing the store

lookup

ChangeLogEvent lookup(long revision)
               throws Exception

Looks up the ChangeLogEvent for a revision.

Parameters:

revision - to get a ChangeLogEvent for

Returns:

the ChangeLogEvent associated with the revision

Throws:

Exception - if there are failures accessing the store

IllegalArgumentException - if the revision is out of range (less than 0 and greater than the current revision)

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents within the system since revision 0. This method should exhibit isolation characteristics: meaning if the request is initiated at revision 100 then any subsequent log entries increasing the revision should not be seen.

Parameters:

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

an enumeration of all the ChangeLogEvents

Throws:

Exception - if there are failures accessing the store

findBefore

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> findBefore(long revision,
                                                                             RevisionOrder order)
                                                                      throws Exception

Finds the ChangeLogEvents that occurred before a revision inclusive.

Parameters:

revision - the revision number to get the ChangeLogEvents before

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

an enumeration of all the ChangeLogEvents before and including some revision

Throws:

Exception - if there are failures accessing the store

IllegalArgumentException - if the revision is out of range (less than 0 and greater than the current revision)

findAfter

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> findAfter(long revision,
                                                                            RevisionOrder order)
                                                                     throws Exception

Finds the ChangeLogEvents that occurred after a revision inclusive. This method should exhibit isolation characteristics: meaning if the request is initiated at revision 100 then any subsequent log entries increasing the revision should not be seen.

Parameters:

revision - the revision number to get the ChangeLogEvents after

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

an enumeration of all the ChangeLogEvents after and including the revision

Throws:

Exception - if there are failures accessing the store

IllegalArgumentException - if the revision is out of range (less than 0 and greater than the current revision)

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(long startRevision,
                                                                       long endRevision,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds the ChangeLogEvents that occurred between a revision range inclusive.

Parameters:

startRevision - the revision number to start getting the ChangeLogEvents above

endRevision - the revision number to start getting the ChangeLogEvents below

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

an enumeration of all the ChangeLogEvents within some revision range inclusive

Throws:

Exception - if there are failures accessing the store

IllegalArgumentException - if the start and end revisions are out of range (less than 0 and greater than the current revision), or if startRevision > endRevision

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.name.Dn dn,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents on an entry.

Parameters:

dn - the normalized Dn of the entry to get ChangeLogEvents for

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of changes that occurred on an entry

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.name.Dn base,
                                                                       org.apache.directory.api.ldap.model.message.SearchScope scope,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents on an entry base and/or it's children/descendants.

Parameters:

base - the normalized Dn of the entry base to get ChangeLogEvents for

scope - the scope of the search under the base similar to LDAP search scope

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of changes that occurred on an entry and/or it's descendants depending on the scope

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(LdapPrincipal principal,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents triggered by a principal in the system.

Parameters:

principal - the LDAP principal who triggered the events

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of changes that were triggered by a specific LDAP user

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.ldif.ChangeType changeType,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents of a particular change type.

Parameters:

changeType - the change type of the ChangeLogEvents to search for

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of ChangeLogEvents of a particular ChangeType

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.schema.AttributeType attributeType,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents altering a particular attributeType.

Parameters:

attributeType - the attributeType definition for the changed attribute to search changes for

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of ChangeLogEvents on a particular attributeType

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.schema.ObjectClass objectClass,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents altering a particular objectClass.

Parameters:

objectClass - the objectClass definition for the entries to search changes for

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of ChangeLogEvents on a particular attributeType

Throws:

Exception - if there are failures accessing the store

find

org.apache.directory.api.ldap.model.cursor.Cursor<ChangeLogEvent> find(org.apache.directory.api.ldap.model.filter.ExprNode filter,
                                                                       RevisionOrder order)
                                                                throws Exception

Finds all the ChangeLogEvents matched by the filter expression tree parameter. The following attributes can be used in the constrained LDAP filter expression tree. The expression must be normalized and can contain only ATA pairs with the following set of attributes:

• ndn: normalized distinguishedName syntax (defaults to matching a string)
• date: generalizedTime syntax
• revision: integer syntax
• attributeType: numeric OID
• objectClass: numeric OID
• changeType: new changeType syntax
• principal: normalized distinguishedName syntax (defaults to matching a string)

The following are the only kinds of Ava node types allowed:

• equality (=)
• greaterThanEq (>=)
• lessThanEq (<=)
• scope (specialized)

Parameters:

filter - the filter to use for finding the change

order - the order in which to return ChangeLogEvents (ordered by revision number)

Returns:

the set of ChangeLogEvents on entries of a particular objectClass

Throws:

Exception - if there are failures accessing the store