org.opends.server.api
Class MatchingRule<T extends MatchingRuleCfg>

java.lang.Object
  extended by org.opends.server.api.MatchingRule<T>
Type Parameters:
T - The type of configuration handled by this matching rule.
Direct Known Subclasses:
ApproximateMatchingRule, EqualityMatchingRule, OrderingMatchingRule, SubstringMatchingRule

@PublicAPI(stability=VOLATILE,
           mayInstantiate=false,
           mayExtend=true,
           mayInvoke=false)
public abstract class MatchingRule<T extends MatchingRuleCfg>
extends java.lang.Object

This class defines the set of methods and structures that must be implemented by a Directory Server module that implements a matching rule.


Constructor Summary
MatchingRule()
           
 
Method Summary
 boolean equals(java.lang.Object o)
          Indicates whether the provided object is equal to this matching rule.
 void finalizeMatchingRule()
          Performs any finalization that may be needed whenever this matching rule is taken out of service.
abstract  java.lang.String getDescription()
          Retrieves the description for this matching rule.
abstract  java.lang.String getName()
          Retrieves the common name for this matching rule.
 java.lang.String getNameOrOID()
          Retrieves the name or OID for this matching rule.
abstract  java.lang.String getOID()
          Retrieves the OID for this matching rule.
abstract  java.lang.String getSyntaxOID()
          Retrieves the OID of the syntax with which this matching rule is associated.
 int hashCode()
          Retrieves the hash code for this matching rule.
abstract  void initializeMatchingRule(T configuration)
          Initializes this matching rule based on the information in the provided configuration entry.
 boolean isConfigurationAcceptable(MatchingRuleCfg configuration, java.util.List<Message> unacceptableReasons)
          Indicates whether the provided configuration is acceptable for this matching rule.
 boolean isObsolete()
          Indicates whether this matching rule is declared "OBSOLETE".
abstract  ByteString normalizeValue(ByteString value)
          Retrieves the normalized form of the provided value, which is best suite for efficiently performing matching operations on that value.
 java.lang.String toString()
          Retrieves a string representation of this matching rule in the format defined in RFC 2252.
 void toString(java.lang.StringBuilder buffer)
          Appends a string representation of this matching rule in the format defined in RFC 2252 to the provided buffer.
abstract  ConditionResult valuesMatch(ByteString attributeValue, ByteString assertionValue)
          Indicates whether the provided attribute value should be considered a match for the given assertion value.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MatchingRule

public MatchingRule()
Method Detail

initializeMatchingRule

public abstract void initializeMatchingRule(T configuration)
                                     throws ConfigException,
                                            InitializationException
Initializes this matching rule based on the information in the provided configuration entry.

Parameters:
configuration - The configuration to use to intialize this matching rule.
Throws:
ConfigException - If an unrecoverable problem arises in the process of performing the initialization.
InitializationException - If a problem that is not configuration-related occurs during initialization.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(MatchingRuleCfg configuration,
                                         java.util.List<Message> unacceptableReasons)
Indicates whether the provided configuration is acceptable for this matching rule. It should be possible to call this method on an uninitialized matching rule instance in order to determine whether the matching rule would be able to use the provided configuration.

Note that implementations which use a subclass of the provided configuration class will likely need to cast the configuration to the appropriate subclass type.

Parameters:
configuration - The matching rule configuration for which to make the determination.
unacceptableReasons - A list that may be used to hold the reasons that the provided configuration is not acceptable.
Returns:
true if the provided configuration is acceptable for this matching rule, or false if not.

finalizeMatchingRule

public void finalizeMatchingRule()
Performs any finalization that may be needed whenever this matching rule is taken out of service.


getName

public abstract java.lang.String getName()
Retrieves the common name for this matching rule.

Returns:
The common name for this matching rule, or null if it does not have a name.

getOID

public abstract java.lang.String getOID()
Retrieves the OID for this matching rule.

Returns:
The OID for this matching rule.

getNameOrOID

public final java.lang.String getNameOrOID()
Retrieves the name or OID for this matching rule. If it has a name, then it will be returned. Otherwise, the OID will be returned.

Returns:
The name or OID for this matching rule.

getDescription

public abstract java.lang.String getDescription()
Retrieves the description for this matching rule.

Returns:
The description for this matching rule, or null if there is none.

getSyntaxOID

public abstract java.lang.String getSyntaxOID()
Retrieves the OID of the syntax with which this matching rule is associated.

Returns:
The OID of the syntax with which this matching rule is associated.

isObsolete

public boolean isObsolete()
Indicates whether this matching rule is declared "OBSOLETE". The default implementation will always return false. If that is not acceptable for a particular matching rule implementation, then it should override this method and perform the appropriate processing to return the correct value.

Returns:
true if this matching rule is declared "OBSOLETE", or false if not.

normalizeValue

public abstract ByteString normalizeValue(ByteString value)
                                   throws DirectoryException
Retrieves the normalized form of the provided value, which is best suite for efficiently performing matching operations on that value.

Parameters:
value - The value to be normalized.
Returns:
The normalized version of the provided value.
Throws:
DirectoryException - If the provided value is invalid according to the associated attribute syntax.

valuesMatch

public abstract ConditionResult valuesMatch(ByteString attributeValue,
                                            ByteString assertionValue)
Indicates whether the provided attribute value should be considered a match for the given assertion value. This will only be used for the purpose of extensible matching. Subclasses should define more specific methods that are appropriate to the matching rule type.

Parameters:
attributeValue - The attribute value in a form that has been normalized according to this matching rule.
assertionValue - The assertion value in a form that has been normalized according to this matching rule.
Returns:
TRUE if the attribute value should be considered a match for the provided assertion value, FALSE if it does not match, or UNDEFINED if the result is undefined.

hashCode

public final int hashCode()
Retrieves the hash code for this matching rule. It will be calculated as the sum of the characters in the OID.

Overrides:
hashCode in class java.lang.Object
Returns:
The hash code for this matching rule.

equals

public final boolean equals(java.lang.Object o)
Indicates whether the provided object is equal to this matching rule. The provided object will be considered equal to this matching rule only if it is a matching rule with the same OID.

Overrides:
equals in class java.lang.Object
Parameters:
o - The object for which to make the determination.
Returns:
true if the provided object is equal to this matching rule, or false if it is not.

toString

public final java.lang.String toString()
Retrieves a string representation of this matching rule in the format defined in RFC 2252.

Overrides:
toString in class java.lang.Object
Returns:
A string representation of this matching rule in the format defined in RFC 2252.

toString

public final void toString(java.lang.StringBuilder buffer)
Appends a string representation of this matching rule in the format defined in RFC 2252 to the provided buffer.

Parameters:
buffer - The buffer to which the information should be appended.