001 /* 002 * CDDL HEADER START 003 * 004 * The contents of this file are subject to the terms of the 005 * Common Development and Distribution License, Version 1.0 only 006 * (the "License"). You may not use this file except in compliance 007 * with the License. 008 * 009 * You can obtain a copy of the license at 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2010-2014 UnboundID Corp. 026 */ 027 package com.unboundid.directory.sdk.common.schema; 028 029 030 031 import com.unboundid.directory.sdk.common.types.ConditionResult; 032 import com.unboundid.ldap.sdk.LDAPException; 033 import com.unboundid.util.ByteString; 034 import com.unboundid.util.NotExtensible; 035 import com.unboundid.util.ThreadSafety; 036 import com.unboundid.util.ThreadSafetyLevel; 037 038 039 040 /** 041 * This interface provides an API for interacting with matching rules, which 042 * can be used to perform matching-related operations against data. 043 */ 044 @NotExtensible() 045 @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE) 046 public interface MatchingRule 047 { 048 /** 049 * Retrieves the numeric OID for this matching rule. 050 * 051 * @return The numeric OID for this matching rule. 052 */ 053 String getOID(); 054 055 056 057 /** 058 * Retrieves the name for this matching rule, if any. 059 * 060 * @return The name for this matching rule, or {@code null} if it does not 061 * have a name. 062 */ 063 String getName(); 064 065 066 067 /** 068 * Retrieves the name for this matching rule, or the numeric OID if it does 069 * not have a name. 070 * 071 * @return The name for this matching rule, or the numeric OID if it does not 072 * have a name. 073 */ 074 String getNameOrOID(); 075 076 077 078 /** 079 * Indicates whether the provided string matches the name or numeric OID for 080 * this matching rule. 081 * 082 * @param name The name for which to make the determination. 083 * 084 * @return {@code true} if the provided string matches the name or numeric 085 * OID for this matching rule, or {@code false} if not. 086 */ 087 boolean hasNameOrOID(final String name); 088 089 090 091 /** 092 * Retrieves the description for this matching rule, if any. 093 * 094 * @return The description for this matching rule, or {@code null} if it does 095 * not have a description. 096 */ 097 String getDescription(); 098 099 100 101 /** 102 * Retrieves the OID of the attribute syntax with which this matching rule is 103 * most closely associated. 104 * 105 * @return The OID of the attribute syntax with which this matching rule is 106 * most closely associated. 107 */ 108 String getSyntaxOID(); 109 110 111 112 /** 113 * Indicates whether this matching rule is declared obsolete in the server 114 * schema. 115 * 116 * @return {@code true} if this matching rule is declared obsolete, or 117 * {@code false} if not. 118 */ 119 boolean isObsolete(); 120 121 122 123 /** 124 * Retrieves the normalized form of the provided value. 125 * 126 * @param value The value to be normalized. 127 * 128 * @return The normalized form of the provided value. 129 * 130 * @throws LDAPException If an error occurs while attempting to normalize 131 * the provided value (e.g., it does not conform to 132 * the appropriate syntax). 133 */ 134 ByteString normalizeValue(final ByteString value) 135 throws LDAPException; 136 137 138 139 /** 140 * Indicates whether the provided attribute value may be considered logically 141 * equivalent to the provided assertion value according to the constraints of 142 * this matching rule.. 143 * 144 * @param normAttributeValue The normalized form of the attribute value to 145 * be compared. 146 * @param normAssertionValue The normalized form of the assertion value to 147 * be compared. 148 * 149 * @return {@code TRUE} if the values are considered equal, 150 * {@code FALSE} if the values are considered different, or 151 * {@code UNDEFINED} if the result is not defined for this matching 152 * rule. 153 */ 154 ConditionResult valuesMatch(final ByteString normAttributeValue, 155 final ByteString normAssertionValue); 156 157 158 159 /** 160 * Retrieves the hash code for this matching rule. 161 * 162 * @return The hash code for this matching rule. 163 */ 164 int hashCode(); 165 166 167 168 /** 169 * Indicates whether the provided object is equal to this matching rule. 170 * 171 * @param o The object for which to make the determination. 172 * 173 * @return {@code true} if the provided object is equal to this matching 174 * rule, or {@code false} if not. 175 */ 176 boolean equals(final Object o); 177 178 179 180 /** 181 * Retrieves a string representation of this matching rule. 182 * 183 * @return A string representation of this matching rule. 184 */ 185 String toString(); 186 }