AttributeIndex.java revision f4fc21a222c514860b5232cce2d9f890639f5b5a
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at legal-notices/CDDLv1_0.txt.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Copyright 2006-2010 Sun Microsystems, Inc.
* Portions Copyright 2011-2015 ForgeRock AS
* Portions Copyright 2014 Manuel Gaupp
*/
/**
* Class representing an attribute index.
* We have a separate tree for each type of indexing, which makes it easy
* to tell which attribute indexes are configured. The different types of
* indexing are equality, presence, substrings and ordering. The keys in the
* ordering index are ordered by setting the btree comparator to the ordering
* matching rule comparator.
* Note that the values in the equality index are normalized by the equality
* matching rule, whereas the values in the ordering index are normalized
* by the ordering matching rule. If these could be guaranteed to be identical
* then we would not need a separate ordering index.
*/
@SuppressWarnings("javadoc")
class AttributeIndex
{
/** Type of the index filter. */
static enum IndexFilterType
{
/** Equality. */
/** Presence. */
/** Ordering. */
/** Ordering. */
/** Substring. */
/** Approximate. */
{
}
/** {@inheritDoc} */
{
}
}
/** This class implements an attribute indexer for matching rules in a Backend. */
static final class MatchingRuleIndex extends DefaultIndex
{
private final AttributeType attributeType;
private MatchingRuleIndex(EntryContainer entryContainer, AttributeType attributeType, State state, Indexer indexer,
int indexEntryLimit)
{
super(getIndexName(entryContainer, attributeType, indexer.getIndexID()), state, indexEntryLimit, entryContainer);
this.attributeType = attributeType;
}
{
}
{
return keys;
}
{
{
}
{
if (needsAdding == null)
{
// This value has been added.
}
else if (!needsAdding)
{
// This value has not been added or removed.
}
}
}
{
if (attributes == null)
{
return;
}
{
{
{
try
{
/*
* Optimization for presence: return immediately after first value since all values
* have the same key.
*/
if (indexer == PRESENCE_INDEXER)
{
return;
}
}
catch (DecodeException e)
{
logger.traceException(e);
}
}
}
}
}
}
/** The key bytes used for the presence index as a {@link ByteString}. */
/** A special indexer for generating presence indexes. */
{
public void createKeys(Schema schema, ByteSequence value, Collection<ByteString> keys) throws DecodeException
{
}
public String getIndexID()
{
}
};
/*
* FIXME Matthew Swift: Once the matching rules have been migrated we should
* revisit this class. All of the evaluateXXX methods should go (the Matcher
* class in the SDK could implement the logic, I hope).
*/
/** The entryContainer in which this attribute index resides. */
private final EntryContainer entryContainer;
/** The attribute index configuration. */
private BackendIndexCfg config;
/** The mapping from names to indexes. */
private IndexingOptions indexingOptions;
AttributeIndex(BackendIndexCfg config, State state, EntryContainer entryContainer) throws ConfigException
{
this.entryContainer = entryContainer;
}
private static Map<String, MatchingRuleIndex> buildIndexes(EntryContainer entryContainer, State state,
{
switch (indexType)
{
case PRESENCE:
break;
case EXTENSIBLE:
getExtensibleIndexers(config.getAttribute(), config.getIndexExtensibleMatchingRule(), indexingOptions));
break;
case APPROXIMATE:
break;
case EQUALITY:
break;
case ORDERING:
break;
case SUBSTRING:
break;
default:
throw new ConfigException(ERR_CONFIG_INDEX_TYPE_NEEDS_MATCHING_RULE.get(attributeType, indexType.toString()));
}
}
}
private static MatchingRule throwIfNoMatchingRule(AttributeType attributeType, IndexType type, MatchingRule rule)
throws ConfigException
{
{
throw new ConfigException(ERR_CONFIG_INDEX_TYPE_NEEDS_MATCHING_RULE.get(attributeType, type.toString()));
}
return rule;
}
private static Map<String, MatchingRuleIndex> buildIndexesForIndexers(EntryContainer entryContainer,
AttributeType attributeType, State state, int indexEntryLimit, Collection<? extends Indexer> indexers)
{
{
{
indexes.put(indexID, new MatchingRuleIndex(entryContainer, attributeType, state, indexer, indexEntryLimit));
}
}
return indexes;
}
private static Collection<Indexer> getExtensibleIndexers(AttributeType attributeType, Set<String> extensibleRules,
{
{
throw new ConfigException(
}
{
}
return indexers;
}
private static TreeName getIndexName(EntryContainer entryContainer, AttributeType attrType, String indexID)
{
}
/**
* Open the attribute index.
*
* @param txn a non null transaction
* @param createOnDemand true if the tree should be created if it does not exist
* @throws StorageRuntimeException if an error occurs while opening the index
*/
{
{
}
config.addChangeListener(this);
}
public void close()
{
config.removeChangeListener(this);
}
/**
* Get the attribute type of this attribute index.
* @return The attribute type of this attribute index.
*/
{
return config.getAttribute();
}
/**
* Return the indexing options of this AttributeIndex.
*
* @return the indexing options of this AttributeIndex.
*/
{
return indexingOptions;
}
/**
* Returns {@code true} if this attribute index supports the provided index type.
*
* @param indexType
* The index type.
* @return {@code true} if this attribute index supports the provided index type.
*/
{
switch (indexType)
{
case PRESENCE:
case EQUALITY:
case SUBSTRING:
case SUBINITIAL:
case SUBANY:
case SUBFINAL:
case GREATER_OR_EQUAL:
case LESS_OR_EQUAL:
case APPROXIMATE:
default:
return false;
}
}
/**
* Update the attribute index for a new entry.
*
* @param buffer The index buffer to use to store the added keys
* @param entryID The entry ID.
* @param entry The contents of the new entry.
* @throws StorageRuntimeException If an error occurs in the storage.
* @throws DirectoryException If a Directory Server error occurs.
*/
void addEntry(IndexBuffer buffer, EntryID entryID, Entry entry) throws StorageRuntimeException, DirectoryException
{
{
{
}
}
}
/**
* Update the attribute index for a deleted entry.
*
* @param buffer The index buffer to use to store the deleted keys
* @param entryID The entry ID
* @param entry The contents of the deleted entry.
* @throws StorageRuntimeException If an error occurs in the storage.
* @throws DirectoryException If a Directory Server error occurs.
*/
void removeEntry(IndexBuffer buffer, EntryID entryID, Entry entry) throws StorageRuntimeException, DirectoryException
{
{
{
}
}
}
/**
* Update the index to reflect a sequence of modifications in a Modify operation.
*
* @param buffer The index buffer used to buffer up the index changes.
* @param entryID The ID of the entry that was modified.
* @param oldEntry The entry before the modifications were applied.
* @param newEntry The entry after the modifications were applied.
* @throws StorageRuntimeException If an error occurs during an operation on a
* storage.
*/
void modifyEntry(IndexBuffer buffer, EntryID entryID, Entry oldEntry, Entry newEntry) throws StorageRuntimeException
{
{
{
if (modifiedKey.getValue())
{
}
else
{
}
}
}
}
/**
* Retrieve the entry IDs that might match the provided assertion.
*
* @param indexQuery
* The query used to retrieve entries.
* @param indexName
* The name of index used to retrieve entries.
* @param filter
* The filter on entries.
* @param debugBuffer
* If not null, a diagnostic string will be written which will help
* determine how the indexes contributed to this search.
* @param monitor
* The backend monitor provider that will keep index
* filter usage statistics.
* @return The candidate entry IDs that might contain the filter assertion
* value.
*/
{
LocalizableMessageBuilder debugMessage = monitor.isFilterUseEnabled() ? new LocalizableMessageBuilder() : null;
if (debugBuffer != null)
{
}
if (monitor.isFilterUseEnabled())
{
{
}
else
{
}
}
return results;
}
/**
* Appends additional traces to {@code debugsearchindex} when a filter successfully used
* an auxiliary index type during index query.
*
* @param debugBuffer the current debugsearchindex buffer
* @param indexNameOut the name of the index type
*/
{
{
}
}
{
debugBuffer.append("[INDEX:").append(config.getAttribute().getNameOrOID()).append(".").append(infos).append("]");
}
/**
* Retrieve the entry IDs that might match two filters that restrict a value
* to both a lower bound and an upper bound.
*
* @param indexQueryFactory
* The index query factory to use for the evaluation
* @param filter1
* The first filter, that is either a less-or-equal filter or a
* greater-or-equal filter.
* @param filter2
* The second filter, that is either a less-or-equal filter or a
* greater-or-equal filter. It must not be of the same type than the
* first filter.
* @param debugBuffer
* If not null, a diagnostic string will be written which will help
* determine how the indexes contributed to this search.
* @param monitor
* The backend monitor provider that will keep index
* filter usage statistics.
* @return The candidate entry IDs that might contain match both filters.
*/
{
// TODO : this implementation is not optimal
// as it implies two separate evaluations instead of a single one, thus defeating the purpose of
// the optimization done in IndexFilter#evaluateLogicalAndFilter method.
// One solution could be to implement a boundedRangeAssertion that combine the two operations in one.
// Such an optimization can only work for attributes declared as SINGLE-VALUE, though, since multiple
// values may match both filters with values outside the range. See OPENDJ-2194.
if (debugBuffer != null)
{
}
return results1;
}
{
IndexFilterType indexFilterType = isLessOrEqual ? IndexFilterType.LESS_OR_EQUAL : IndexFilterType.GREATER_OR_EQUAL;
}
/**
* Retrieve the entry IDs that might match a filter.
*
* @param indexQueryFactory the index query factory to use for the evaluation
* @param indexFilterType the index type filter
* @param filter The filter.
* @param debugBuffer If not null, a diagnostic string will be written
* which will help determine how the indexes contributed
* to this search.
* @param monitor The backend monitor provider that will keep
* index filter usage statistics.
* @return The candidate entry IDs that might contain a value
* that matches the filter type.
*/
EntryIDSet evaluateFilter(IndexQueryFactory<IndexQuery> indexQueryFactory, IndexFilterType indexFilterType,
{
try
{
}
catch (DecodeException e)
{
logger.traceException(e);
return newUndefinedSet();
}
}
private IndexQuery getIndexQuery(IndexQueryFactory<IndexQuery> indexQueryFactory, IndexFilterType indexFilterType,
{
switch (indexFilterType)
{
case EQUALITY:
case PRESENCE:
return indexQueryFactory.createMatchAllQuery();
case GREATER_OR_EQUAL:
case LESS_OR_EQUAL:
case SUBSTRING:
case APPROXIMATE:
default:
return null;
}
}
/**
* Get a string representation of this object.
* @return return A string representation of this object.
*/
{
return getName();
}
/** {@inheritDoc} */
public synchronized boolean isConfigurationChangeAcceptable(
{
{
return false;
}
{
{
return false;
}
}
return true;
}
{
{
return false;
}
return true;
}
{
switch (indexType)
{
case APPROXIMATE:
return attrType.getApproximateMatchingRule();
case EQUALITY:
return attrType.getEqualityMatchingRule();
case ORDERING:
return attrType.getOrderingMatchingRule();
case SUBSTRING:
return attrType.getSubstringMatchingRule();
default:
}
}
/** {@inheritDoc} */
public synchronized ConfigChangeResult applyConfigurationChange(final BackendIndexCfg newConfiguration)
{
final IndexingOptions newIndexingOptions = new IndexingOptionsImpl(newConfiguration.getSubstringLength());
try
{
final Map<String, MatchingRuleIndex> newIndexIdToIndexes = buildIndexes(entryContainer, state, newConfiguration);
// Replace instances of Index created by buildIndexes() with the one already opened and present in the actual
// indexIdToIndexes
// Open added indexes *before* adding them to indexIdToIndexes
{
{
{
}
}
});
// We get exclusive lock to ensure that no query is actually using the indexes that will be deleted.
try
{
{
{
{
}
}
});
}
finally
{
}
{
}
}
catch (Exception e)
{
}
return ccr;
}
private static void createIndex(WriteableTransaction txn, MatchingRuleIndex index, ConfigChangeResult ccr)
{
{
ccr.setAdminActionRequired(true);
}
}
{
{
// This index can still be used since index size limit doesn't impact validity of the results.
ccr.setAdminActionRequired(true);
}
}
private static void deleteIndex(WriteableTransaction txn, EntryContainer entryContainer, Index index)
{
try
{
}
finally
{
}
}
/**
* Return true iff this index is trusted.
* @return the trusted state of this index
*/
boolean isTrusted()
{
{
{
return false;
}
}
return true;
}
/**
* Get the tree name prefix for indexes in this attribute index.
*
* @return tree name for this container.
*/
{
return entryContainer.getTreePrefix()
+ "_"
}
{
return indexIdToIndexes;
}
/**
* Retrieve the entry IDs that might match an extensible filter.
*
* @param indexQueryFactory the index query factory to use for the evaluation
* @param filter The extensible filter.
* @param debugBuffer If not null, a diagnostic string will be written
* which will help determine how the indexes contributed
* to this search.
* @param monitor The backend monitor provider that will keep
* index filter usage statistics.
* @return The candidate entry IDs that might contain the filter
* assertion value.
*/
{
//Get the Matching Rule OID of the filter.
/*
* Use the default equality index in two conditions:
* 1. There is no matching rule provided
* 2. The matching rule specified is actually the default equality.
*/
if (matchRuleOID == null
{
//No matching rule is defined; use the default equality matching rule.
}
if (!ruleHasAtLeastOneIndex(rule))
{
if (monitor.isFilterUseEnabled())
{
INFO_INDEX_FILTER_MATCHING_RULE_NOT_INDEXED.get(matchRuleOID, config.getAttribute().getNameOrOID()));
}
}
try
{
final IndexQuery indexQuery = rule.getAssertion(filter.getAssertionValue()).createIndexQuery(indexQueryFactory);
LocalizableMessageBuilder debugMessage = monitor.isFilterUseEnabled() ? new LocalizableMessageBuilder() : null;
if (debugBuffer != null)
{
{
.append(".")
}
}
if (monitor.isFilterUseEnabled())
{
{
}
else
{
}
}
return results;
}
catch (DecodeException e)
{
logger.traceException(e);
}
}
{
{
{
return true;
}
}
return false;
}
/** Indexing options implementation. */
private static final class IndexingOptionsImpl implements IndexingOptions
{
/** The length of substring keys used in substring indexes. */
private int substringKeySize;
private IndexingOptionsImpl(int substringKeySize)
{
this.substringKeySize = substringKeySize;
}
public int substringKeySize()
{
return substringKeySize;
}
}
{
close();
{
}
}
}