Package com.unboundid.ldap.matchingrules
Class MatchingRule
- java.lang.Object
-
- com.unboundid.ldap.matchingrules.MatchingRule
-
- All Implemented Interfaces:
java.io.Serializable
- Direct Known Subclasses:
BooleanMatchingRule
,CaseIgnoreListMatchingRule
,DistinguishedNameMatchingRule
,GeneralizedTimeMatchingRule
,IntegerMatchingRule
,JSONObjectExactMatchingRule
,SimpleMatchingRule
@Extensible @ThreadSafety(level=INTERFACE_THREADSAFE) public abstract class MatchingRule extends java.lang.Object implements java.io.Serializable
This class defines the API for an LDAP matching rule, which may be used to determine whether two values are equal to each other, and to normalize values so that they may be more easily compared.- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static byte
SUBSTRING_TYPE_SUBANY
The substring element type used for subAny substring assertion components.static byte
SUBSTRING_TYPE_SUBFINAL
The substring element type used for subFinal substring assertion components.static byte
SUBSTRING_TYPE_SUBINITIAL
The substring element type used for subInitial substring assertion components.
-
Constructor Summary
Constructors Modifier Constructor Description protected
MatchingRule()
Creates a new instance of this matching rule.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract int
compareValues(ASN1OctetString value1, ASN1OctetString value2)
Compares the provided values to determine their relative order in a sorted list.static MatchingRule
getDefaultEqualityMatchingRule()
Retrieves the default matching rule that will be used for equality matching if no other matching rule is specified or available.static MatchingRule
getDefaultOrderingMatchingRule()
Retrieves the default matching rule that will be used for ordering matching if no other matching rule is specified or available.static MatchingRule
getDefaultSubstringMatchingRule()
Retrieves the default matching rule that will be used for substring matching if no other matching rule is specified or available.abstract java.lang.String
getEqualityMatchingRuleName()
Retrieves the name for this matching rule when used to perform equality matching, if appropriate.java.lang.String
getEqualityMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform equality matching if defined, or the OID if no name is available.abstract java.lang.String
getEqualityMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform equality matching, if appropriate.abstract java.lang.String
getOrderingMatchingRuleName()
Retrieves the name for this matching rule when used to perform ordering matching, if appropriate.java.lang.String
getOrderingMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform ordering matching if defined, or the OID if no name is available.abstract java.lang.String
getOrderingMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform ordering matching, if appropriate.abstract java.lang.String
getSubstringMatchingRuleName()
Retrieves the name for this matching rule when used to perform substring matching, if appropriate.java.lang.String
getSubstringMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform substring matching if defined, or the OID if no name is available.abstract java.lang.String
getSubstringMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform substring matching, if appropriate.boolean
matchesAnyValue(ASN1OctetString assertionValue, ASN1OctetString[] attributeValues)
Indicates whether the provided assertion value matches any of the provided attribute values.abstract boolean
matchesSubstring(ASN1OctetString value, ASN1OctetString subInitial, ASN1OctetString[] subAny, ASN1OctetString subFinal)
Indicates whether the provided value matches the given substring assertion, according to the constraints of this matching rule.abstract ASN1OctetString
normalize(ASN1OctetString value)
Normalizes the provided value for easier matching.abstract ASN1OctetString
normalizeSubstring(ASN1OctetString value, byte substringType)
Normalizes the provided value for use as part of a substring assertion.static MatchingRule
selectEqualityMatchingRule(java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for equality matching using the specified matching rule.static MatchingRule
selectEqualityMatchingRule(java.lang.String attrName, Schema schema)
Attempts to select the appropriate matching rule to use for equality matching against the specified attribute.static MatchingRule
selectEqualityMatchingRule(java.lang.String attrName, java.lang.String ruleID, Schema schema)
Attempts to select the appropriate matching rule to use for equality matching against the specified attribute.static MatchingRule
selectMatchingRuleForSyntax(java.lang.String syntaxOID)
Attempts to select the appropriate matching rule for use with the syntax with the specified OID.static MatchingRule
selectOrderingMatchingRule(java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for ordering matching using the specified matching rule.static MatchingRule
selectOrderingMatchingRule(java.lang.String attrName, Schema schema)
Attempts to select the appropriate matching rule to use for ordering matching against the specified attribute.static MatchingRule
selectOrderingMatchingRule(java.lang.String attrName, java.lang.String ruleID, Schema schema)
Attempts to select the appropriate matching rule to use for ordering matching against the specified attribute.static MatchingRule
selectSubstringMatchingRule(java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for substring matching using the specified matching rule.static MatchingRule
selectSubstringMatchingRule(java.lang.String attrName, Schema schema)
Attempts to select the appropriate matching rule to use for substring matching against the specified attribute.static MatchingRule
selectSubstringMatchingRule(java.lang.String attrName, java.lang.String ruleID, Schema schema)
Attempts to select the appropriate matching rule to use for substring matching against the specified attribute.abstract boolean
valuesMatch(ASN1OctetString value1, ASN1OctetString value2)
Indicates whether the provided values are equal to each other, according to the constraints of this matching rule.
-
-
-
Field Detail
-
SUBSTRING_TYPE_SUBINITIAL
public static final byte SUBSTRING_TYPE_SUBINITIAL
The substring element type used for subInitial substring assertion components.- See Also:
- Constant Field Values
-
SUBSTRING_TYPE_SUBANY
public static final byte SUBSTRING_TYPE_SUBANY
The substring element type used for subAny substring assertion components.- See Also:
- Constant Field Values
-
SUBSTRING_TYPE_SUBFINAL
public static final byte SUBSTRING_TYPE_SUBFINAL
The substring element type used for subFinal substring assertion components.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
MatchingRule
protected MatchingRule()
Creates a new instance of this matching rule.
-
-
Method Detail
-
getEqualityMatchingRuleName
@Nullable public abstract java.lang.String getEqualityMatchingRuleName()
Retrieves the name for this matching rule when used to perform equality matching, if appropriate.- Returns:
- The name for this matching rule when used to perform equality
matching, or
null
if this matching rule is not intended to be used for equality matching.
-
getEqualityMatchingRuleOID
@Nullable public abstract java.lang.String getEqualityMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform equality matching, if appropriate.- Returns:
- The OID for this matching rule when used to perform equality
matching, or
null
if this matching rule is not intended to be used for equality matching.
-
getEqualityMatchingRuleNameOrOID
@Nullable public java.lang.String getEqualityMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform equality matching if defined, or the OID if no name is available.- Returns:
- The name or OID for this matching rule when used to perform
equality matching, or
null
if this matching rule cannot be used to perform equality matching.
-
getOrderingMatchingRuleName
@Nullable public abstract java.lang.String getOrderingMatchingRuleName()
Retrieves the name for this matching rule when used to perform ordering matching, if appropriate.- Returns:
- The name for this matching rule when used to perform ordering
matching, or
null
if this matching rule is not intended to be used for ordering matching.
-
getOrderingMatchingRuleOID
@Nullable public abstract java.lang.String getOrderingMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform ordering matching, if appropriate.- Returns:
- The OID for this matching rule when used to perform ordering
matching, or
null
if this matching rule is not intended to be used for ordering matching.
-
getOrderingMatchingRuleNameOrOID
@Nullable public java.lang.String getOrderingMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform ordering matching if defined, or the OID if no name is available.- Returns:
- The name or OID for this matching rule when used to perform
ordering matching, or
null
if this matching rule cannot be used to perform equality matching.
-
getSubstringMatchingRuleName
@Nullable public abstract java.lang.String getSubstringMatchingRuleName()
Retrieves the name for this matching rule when used to perform substring matching, if appropriate.- Returns:
- The name for this matching rule when used to perform substring
matching, or
null
if this matching rule is not intended to be used for substring matching.
-
getSubstringMatchingRuleOID
@Nullable public abstract java.lang.String getSubstringMatchingRuleOID()
Retrieves the OID for this matching rule when used to perform substring matching, if appropriate.- Returns:
- The OID for this matching rule when used to perform substring
matching, or
null
if this matching rule is not intended to be used for substring matching.
-
getSubstringMatchingRuleNameOrOID
@Nullable public java.lang.String getSubstringMatchingRuleNameOrOID()
Retrieves the name for this matching rule when used to perform substring matching if defined, or the OID if no name is available.- Returns:
- The name or OID for this matching rule when used to perform
substring matching, or
null
if this matching rule cannot be used to perform equality matching.
-
valuesMatch
public abstract boolean valuesMatch(@NotNull ASN1OctetString value1, @NotNull ASN1OctetString value2) throws LDAPException
Indicates whether the provided values are equal to each other, according to the constraints of this matching rule.- Parameters:
value1
- The first value for which to make the determination.value2
- The second value for which to make the determination.- Returns:
true
if the provided values are considered equal, orfalse
if not.- Throws:
LDAPException
- If a problem occurs while making the determination, or if this matching rule does not support equality matching.
-
matchesAnyValue
public boolean matchesAnyValue(@NotNull ASN1OctetString assertionValue, @NotNull ASN1OctetString[] attributeValues) throws LDAPException
Indicates whether the provided assertion value matches any of the provided attribute values.- Parameters:
assertionValue
- The assertion value for which to make the determination.attributeValues
- The set of attribute values to compare against the provided assertion value.- Returns:
true
if the provided assertion value matches any of the given attribute values, orfalse
if not.- Throws:
LDAPException
- If a problem occurs while making the determination, or if this matching rule does not support equality matching.
-
matchesSubstring
public abstract boolean matchesSubstring(@NotNull ASN1OctetString value, @Nullable ASN1OctetString subInitial, @Nullable ASN1OctetString[] subAny, @Nullable ASN1OctetString subFinal) throws LDAPException
Indicates whether the provided value matches the given substring assertion, according to the constraints of this matching rule.- Parameters:
value
- The value for which to make the determination.subInitial
- The subInitial portion of the substring assertion, ornull
if there is no subInitial element.subAny
- The subAny elements of the substring assertion, ornull
if there are no subAny elements.subFinal
- The subFinal portion of the substring assertion, ornull
if there is no subFinal element.- Returns:
true
if the provided value matches the substring assertion, orfalse
if not.- Throws:
LDAPException
- If a problem occurs while making the determination, or if this matching rule does not support substring matching.
-
compareValues
public abstract int compareValues(@NotNull ASN1OctetString value1, @NotNull ASN1OctetString value2) throws LDAPException
Compares the provided values to determine their relative order in a sorted list.- Parameters:
value1
- The first value to compare.value2
- The second value to compare.- Returns:
- A negative value if
value1
should come beforevalue2
in a sorted list, a positive value ifvalue1
should come aftervalue2
in a sorted list, or zero if the values are equal or there is no distinction between their orders in a sorted list. - Throws:
LDAPException
- If a problem occurs while making the determination, or if this matching rule does not support ordering matching.
-
normalize
@NotNull public abstract ASN1OctetString normalize(@NotNull ASN1OctetString value) throws LDAPException
Normalizes the provided value for easier matching.- Parameters:
value
- The value to be normalized.- Returns:
- The normalized form of the provided value.
- Throws:
LDAPException
- If a problem occurs while normalizing the provided value.
-
normalizeSubstring
@NotNull public abstract ASN1OctetString normalizeSubstring(@NotNull ASN1OctetString value, byte substringType) throws LDAPException
Normalizes the provided value for use as part of a substring assertion.- Parameters:
value
- The value to be normalized for use as part of a substring assertion.substringType
- The substring assertion component type for the provided value. It should be one ofSUBSTRING_TYPE_SUBINITIAL
,SUBSTRING_TYPE_SUBANY
, orSUBSTRING_TYPE_SUBFINAL
.- Returns:
- The normalized form of the provided value.
- Throws:
LDAPException
- If a problem occurs while normalizing the provided value.
-
selectEqualityMatchingRule
@NotNull public static MatchingRule selectEqualityMatchingRule(@NotNull java.lang.String attrName, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for equality matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default equality matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema.schema
- The schema to examine to make the appropriate determination. If this isnull
, then the default equality matching rule will be selected.- Returns:
- The selected matching rule.
-
selectEqualityMatchingRule
@NotNull public static MatchingRule selectEqualityMatchingRule(@Nullable java.lang.String attrName, @Nullable java.lang.String ruleID, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for equality matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default equality matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema. It may benull
if the matching rule should be selected using the matching rule ID.ruleID
- The OID of the desired matching rule. It may benull
if the matching rule should be selected only using the attribute name. If a rule ID is provided, then it will be the only criteria used to select the matching rule.schema
- The schema to examine to make the appropriate determination. If this isnull
and no rule ID was provided, then the default equality matching rule will be selected.- Returns:
- The selected matching rule.
-
selectEqualityMatchingRule
@NotNull public static MatchingRule selectEqualityMatchingRule(@NotNull java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for equality matching using the specified matching rule. If an appropriate matching rule cannot be determined, then the default equality matching rule will be selected.- Parameters:
ruleID
- The name or OID of the desired matching rule.- Returns:
- The selected matching rule.
-
getDefaultEqualityMatchingRule
@NotNull public static MatchingRule getDefaultEqualityMatchingRule()
Retrieves the default matching rule that will be used for equality matching if no other matching rule is specified or available. The rule returned will perform case-ignore string matching.- Returns:
- The default matching rule that will be used for equality matching if no other matching rule is specified or available.
-
selectOrderingMatchingRule
@NotNull public static MatchingRule selectOrderingMatchingRule(@NotNull java.lang.String attrName, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for ordering matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default ordering matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema.schema
- The schema to examine to make the appropriate determination. If this isnull
, then the default ordering matching rule will be selected.- Returns:
- The selected matching rule.
-
selectOrderingMatchingRule
@NotNull public static MatchingRule selectOrderingMatchingRule(@Nullable java.lang.String attrName, @Nullable java.lang.String ruleID, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for ordering matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default ordering matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema. It may benull
if the matching rule should be selected using the matching rule ID.ruleID
- The OID of the desired matching rule. It may benull
if the matching rule should be selected only using the attribute name. If a rule ID is provided, then it will be the only criteria used to select the matching rule.schema
- The schema to examine to make the appropriate determination. If this isnull
and no rule ID was provided, then the default ordering matching rule will be selected.- Returns:
- The selected matching rule.
-
selectOrderingMatchingRule
@NotNull public static MatchingRule selectOrderingMatchingRule(@NotNull java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for ordering matching using the specified matching rule. If an appropriate matching rule cannot be determined, then the default ordering matching rule will be selected.- Parameters:
ruleID
- The name or OID of the desired matching rule.- Returns:
- The selected matching rule.
-
getDefaultOrderingMatchingRule
@NotNull public static MatchingRule getDefaultOrderingMatchingRule()
Retrieves the default matching rule that will be used for ordering matching if no other matching rule is specified or available. The rule returned will perform case-ignore string matching.- Returns:
- The default matching rule that will be used for ordering matching if no other matching rule is specified or available.
-
selectSubstringMatchingRule
@NotNull public static MatchingRule selectSubstringMatchingRule(@NotNull java.lang.String attrName, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for substring matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default substring matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema.schema
- The schema to examine to make the appropriate determination. If this isnull
, then the default substring matching rule will be selected.- Returns:
- The selected matching rule.
-
selectSubstringMatchingRule
@NotNull public static MatchingRule selectSubstringMatchingRule(@Nullable java.lang.String attrName, @Nullable java.lang.String ruleID, @Nullable Schema schema)
Attempts to select the appropriate matching rule to use for substring matching against the specified attribute. If an appropriate matching rule cannot be determined, then the default substring matching rule will be selected.- Parameters:
attrName
- The name of the attribute to examine in the provided schema. It may benull
if the matching rule should be selected using the matching rule ID.ruleID
- The OID of the desired matching rule. It may benull
if the matching rule should be selected only using the attribute name. If a rule ID is provided, then it will be the only criteria used to select the matching rule.schema
- The schema to examine to make the appropriate determination. If this isnull
and no rule ID was provided, then the default substring matching rule will be selected.- Returns:
- The selected matching rule.
-
selectSubstringMatchingRule
@NotNull public static MatchingRule selectSubstringMatchingRule(@NotNull java.lang.String ruleID)
Attempts to select the appropriate matching rule to use for substring matching using the specified matching rule. If an appropriate matching rule cannot be determined, then the default substring matching rule will be selected.- Parameters:
ruleID
- The name or OID of the desired matching rule.- Returns:
- The selected matching rule.
-
getDefaultSubstringMatchingRule
@NotNull public static MatchingRule getDefaultSubstringMatchingRule()
Retrieves the default matching rule that will be used for substring matching if no other matching rule is specified or available. The rule returned will perform case-ignore string matching.- Returns:
- The default matching rule that will be used for substring matching if no other matching rule is specified or available.
-
selectMatchingRuleForSyntax
@NotNull public static MatchingRule selectMatchingRuleForSyntax(@NotNull java.lang.String syntaxOID)
Attempts to select the appropriate matching rule for use with the syntax with the specified OID. If an appropriate matching rule cannot be determined, then the case-ignore string matching rule will be selected.- Parameters:
syntaxOID
- The OID of the attribute syntax for which to make the determination.- Returns:
- The selected matching rule.
-
-