org.apache.directory.server.xdbm

Interface Index<K,E>

Type Parameters:

K - The Indexed value type, used to retrieve an element

E - The unique identifier type in the master table

All Known Implementing Classes:

AbstractIndex, AvlIndex, AvlRdnIndex, JdbmDnIndex, JdbmIndex, JdbmRdnIndex, MavibotDnIndex, MavibotIndex, MavibotRdnIndex

public interface Index<K,E>

An index used to retrieve elements into the master table. Each stored element that is indexed has a unique identifier (ID). We may have more than one element associated with a value (K). We may cache the retrieved element (O).
Cursors over indices can also be gotten to traverse the values of the index.

Author:

Apache Directory Project

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_INDEX_CACHE_SIZE The default cache size (ie, the number of elements we stored in the cache)

Method Summary

Modifier and Type	Method and Description
void	add(PartitionTxn partitionTxn, K attrVal, E entryId) Add an entry into the index, associated with the element E.
void	close(PartitionTxn partitionTxn) Close and index
long	count(PartitionTxn partitionTxn) Gets the total scan count for this index.
long	count(PartitionTxn partitionTxn, K attrVal) Gets the scan count for the occurrence of a specific attribute value within the index.
void	drop(PartitionTxn partitionTxn, E entryId) Remove all the reference to an entry from the index.
void	drop(PartitionTxn partitionTxn, K attrVal, E entryId) Remove the pair <K,ID> from the index for the given value and id.
boolean	forward(PartitionTxn partitionTxn, K attrVal) Try to move forward in the index
boolean	forward(PartitionTxn partitionTxn, K attrVal, E entryId) Try to move forward in the index
org.apache.directory.api.ldap.model.cursor.Cursor<IndexEntry<K,E>>	forwardCursor(PartitionTxn partitionTxn) Builds a Cursor on the Forward index
org.apache.directory.api.ldap.model.cursor.Cursor<IndexEntry<K,E>>	forwardCursor(PartitionTxn partitionTxn, K key) Builds a Cursor on the Forward index, starting at a specific key
E	forwardLookup(PartitionTxn partitionTxn, K attrVal) Search for a value using the Forward table
org.apache.directory.api.ldap.model.cursor.Cursor<E>	forwardValueCursor(PartitionTxn partitionTxn, K key) Builds a Cursor on the Forward index, starting at a specific key
org.apache.directory.api.ldap.model.schema.AttributeType	getAttribute() Gets the attribute this Index is built upon.
String	getAttributeId() Gets the attribute identifier set at configuration time for this index which may not be the OID but an alias name for the attributeType associated with this Index
int	getCacheSize() Gets the size of the index cache in terms of the number of index entries to be cached.
URI	getWkDirPath() Gets the working directory path to something other than the default.
long	greaterThanCount(PartitionTxn partitionTxn, K attrVal) Find the number of element in a tree above a given key
boolean	hasReverse() Tells if the index has a reverse table or not
boolean	isDupsEnabled() tells whether the Index implementation supports storing duplicate keys
long	lessThanCount(PartitionTxn partitionTxn, K attrVal) Find the number of element in a tree below a given key
boolean	reverse(PartitionTxn partitionTxn, E entryId) Try to move backward in the index
boolean	reverse(PartitionTxn partitionTxn, E entryId, K attrVal) Try to move backward in the index
K	reverseLookup(PartitionTxn partitionTxn, E element) Search for a value using the Reverse table
org.apache.directory.api.ldap.model.cursor.Cursor<K>	reverseValueCursor(PartitionTxn partitionTxn, E entryId) Builds a Cursor on the Reverse index, starting at a specific entry Id
void	setAttributeId(String attributeId) Sets the attribute identifier set at configuration time for this index which may not be the OID but an alias name for the attributeType associated with this Index
void	setCacheSize(int cacheSize) Sets the size of the index cache in terms of the number of index entries to be cached.
void	setWkDirPath(URI wkDirPath) Sets the working directory path to something other than the default.

Field Detail

DEFAULT_INDEX_CACHE_SIZE

static final int DEFAULT_INDEX_CACHE_SIZE

The default cache size (ie, the number of elements we stored in the cache)

See Also:

Constant Field Values

Method Detail

getAttributeId

String getAttributeId()

Gets the attribute identifier set at configuration time for this index which may not be the OID but an alias name for the attributeType associated with this Index

Returns:

configured attribute oid or alias name

setAttributeId

void setAttributeId(String attributeId)

Sets the attribute identifier set at configuration time for this index which may not be the OID but an alias name for the attributeType associated with this Index

Parameters:

attributeId - configured attribute oid or alias name

getCacheSize

int getCacheSize()

Gets the size of the index cache in terms of the number of index entries to be cached.

Returns:

the size of the index cache

setCacheSize

void setCacheSize(int cacheSize)

Sets the size of the index cache in terms of the number of index entries to be cached.

Parameters:

cacheSize - the size of the index cache

setWkDirPath

void setWkDirPath(URI wkDirPath)

Sets the working directory path to something other than the default. Sometimes more performance is gained by locating indices on separate disk spindles.

Parameters:

wkDirPath - optional working directory path

getWkDirPath

URI getWkDirPath()

Gets the working directory path to something other than the default. Sometimes more performance is gained by locating indices on separate disk spindles.

Returns:

optional working directory path

getAttribute

org.apache.directory.api.ldap.model.schema.AttributeType getAttribute()

Gets the attribute this Index is built upon.

Returns:

the id of the Index's attribute

count

long count(PartitionTxn partitionTxn)
    throws org.apache.directory.api.ldap.model.exception.LdapException

Gets the total scan count for this index.

Parameters:

partitionTxn - The transaction to use

Returns:

the number of key/value pairs in this index

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - on failure to access index db files

count

long count(PartitionTxn partitionTxn,
           K attrVal)
    throws org.apache.directory.api.ldap.model.exception.LdapException

Gets the scan count for the occurrence of a specific attribute value within the index.

Parameters:

partitionTxn - The transaction to use

attrVal - the value of the attribute to get a scan count for

Returns:

the number of key/value pairs in this index with the value value

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - on failure to access index db files

greaterThanCount

long greaterThanCount(PartitionTxn partitionTxn,
                      K attrVal)
               throws org.apache.directory.api.ldap.model.exception.LdapException

Find the number of element in a tree above a given key

Parameters:

partitionTxn - The transaction to use

attrVal - The key

Returns:

The number of element above the key

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the operation failed

lessThanCount

long lessThanCount(PartitionTxn partitionTxn,
                   K attrVal)
            throws org.apache.directory.api.ldap.model.exception.LdapException

Find the number of element in a tree below a given key

Parameters:

partitionTxn - The transaction to use

attrVal - The key

Returns:

The number of element below the key

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the operation failed

forwardLookup

E forwardLookup(PartitionTxn partitionTxn,
                K attrVal)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Search for a value using the Forward table

Parameters:

partitionTxn - The transaction to use

attrVal - The key to retrieve

Returns:

The found value

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the operation failed

reverseLookup

K reverseLookup(PartitionTxn partitionTxn,
                E element)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Search for a value using the Reverse table

Parameters:

partitionTxn - The transaction to use

element - The key to retrieve

Returns:

The found value

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the operation failed

add

void add(PartitionTxn partitionTxn,
         K attrVal,
         E entryId)
  throws org.apache.directory.api.ldap.model.exception.LdapException

Add an entry into the index, associated with the element E. The added value is the key to retrieve the element having the given ID.

Parameters:

partitionTxn - The transaction to use

attrVal - The added value

entryId - The entry ID pointed by the added value

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the addition can't be done

drop

void drop(PartitionTxn partitionTxn,
          E entryId)
   throws org.apache.directory.api.ldap.model.exception.LdapException

Remove all the reference to an entry from the index.
As an entry might be referenced more than once in the forward index, depending on which index we are dealing with, we need to iterate over all the values contained into the reverse index for this entryId.
For instance, considering the ObjectClass index for an entry having three ObjectClasses (top, person, inetOrgPerson), then the reverse index will contain :

 [entryId, [top, person, inetOrgPerson]]
 

and the forward index will contain many entries like :

 [top, [..., entryId, ...]]
 [person,  [..., entryId, ...]]
 [inetOrgPerson,  [..., entryId, ...]]
 

So dropping the entryId means that we must first get all the values from the reverse index (and we will get [top, person, inetOrgPerson]) then to iterate through all those values to remove entryId from the associated list of entryIds.

Parameters:

partitionTxn - The transaction to use

entryId - The master table entryId to remove

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - if we can't drop the element from the index

drop

void drop(PartitionTxn partitionTxn,
          K attrVal,
          E entryId)
   throws org.apache.directory.api.ldap.model.exception.LdapException

Remove the pair <K,ID> from the index for the given value and id.

Parameters:

partitionTxn - The transaction to use

attrVal - The value we want to remove from the index

entryId - The associated ID

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the removal can't be done

forwardCursor

org.apache.directory.api.ldap.model.cursor.Cursor<IndexEntry<K,E>> forwardCursor(PartitionTxn partitionTxn)
                                                                          throws org.apache.directory.api.ldap.model.exception.LdapException

Builds a Cursor on the Forward index

Parameters:

partitionTxn - The transaction to use

Returns:

The created Cursor

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the cursor can't be created

forwardCursor

org.apache.directory.api.ldap.model.cursor.Cursor<IndexEntry<K,E>> forwardCursor(PartitionTxn partitionTxn,
                                                                                 K key)
                                                                          throws org.apache.directory.api.ldap.model.exception.LdapException

Builds a Cursor on the Forward index, starting at a specific key

Parameters:

partitionTxn - The transaction to use

key - The key to start from

Returns:

The created Cursor

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the cursor can't be created

reverseValueCursor

org.apache.directory.api.ldap.model.cursor.Cursor<K> reverseValueCursor(PartitionTxn partitionTxn,
                                                                        E entryId)
                                                                 throws org.apache.directory.api.ldap.model.exception.LdapException

Builds a Cursor on the Reverse index, starting at a specific entry Id

Parameters:

partitionTxn - The transaction to use

entryId - The entry ID to start from

Returns:

The created Cursor

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the cursor can't be created

forwardValueCursor

org.apache.directory.api.ldap.model.cursor.Cursor<E> forwardValueCursor(PartitionTxn partitionTxn,
                                                                        K key)
                                                                 throws org.apache.directory.api.ldap.model.exception.LdapException

Builds a Cursor on the Forward index, starting at a specific key

Parameters:

partitionTxn - The transaction to use

key - The key to start from

Returns:

The created Cursor

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If the cursor can't be created

forward

boolean forward(PartitionTxn partitionTxn,
                K attrVal)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Try to move forward in the index

Parameters:

partitionTxn - The transaction to use

attrVal - The key we want to start with

Returns:

true if we can move forward

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If we had an issue moving forward

forward

boolean forward(PartitionTxn partitionTxn,
                K attrVal,
                E entryId)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Try to move forward in the index

Parameters:

partitionTxn - The transaction to use

attrVal - The key we want to start with

entryId - The entry ID to start from

Returns:

true if we can move forward

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If we had an issue moving forward

reverse

boolean reverse(PartitionTxn partitionTxn,
                E entryId)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Try to move backward in the index

Parameters:

partitionTxn - The transaction to use

entryId - The entry we want to start with

Returns:

true if we can move backward

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If we had an issue moving backward

reverse

boolean reverse(PartitionTxn partitionTxn,
                E entryId,
                K attrVal)
         throws org.apache.directory.api.ldap.model.exception.LdapException

Try to move backward in the index

Parameters:

partitionTxn - The transaction to use

entryId - The entry ID to start from

attrVal - The key we want to start with

Returns:

true if we can move backward

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If we had an issue moving backward

close

void close(PartitionTxn partitionTxn)
    throws org.apache.directory.api.ldap.model.exception.LdapException,
           IOException

Close and index

Parameters:

partitionTxn - The transaction to use

Throws:

org.apache.directory.api.ldap.model.exception.LdapException - If we weren't able to close the index

IOException - If we had an issue with the index file

isDupsEnabled

boolean isDupsEnabled()

tells whether the Index implementation supports storing duplicate keys

Returns:

true if duplicate keys are allowed false otherwise

hasReverse

boolean hasReverse()

Tells if the index has a reverse table or not

Returns:

true if the index has a reverse table