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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE 011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE. 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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. 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 2006-2008 Sun Microsystems, Inc. 026 */ 027 package org.opends.server.api; 028 import org.opends.messages.Message; 029 030 031 032 import java.util.List; 033 034 import org.opends.server.admin.std.server.AttributeSyntaxCfg; 035 import org.opends.server.config.ConfigException; 036 import org.opends.server.types.ByteString; 037 import org.opends.server.types.InitializationException; 038 039 import org.opends.messages.MessageBuilder; 040 041 042 /** 043 * This class defines the set of methods and structures that must be 044 * implemented by a Directory Server module that implements an 045 * attribute syntax. 046 * 047 * @param <T> The type of configuration handled by this attribute 048 * syntax. 049 */ 050 @org.opends.server.types.PublicAPI( 051 stability=org.opends.server.types.StabilityLevel.VOLATILE, 052 mayInstantiate=false, 053 mayExtend=true, 054 mayInvoke=false) 055 public abstract class AttributeSyntax<T extends AttributeSyntaxCfg> 056 { 057 /** 058 * Initializes this attribute syntax based on the information in the 059 * provided configuration entry. 060 * 061 * @param configuration The configuration to use to initialize 062 * this attribute syntax. 063 * 064 * @throws ConfigException If an unrecoverable problem arises in 065 * the process of performing the 066 * initialization. 067 * 068 * @throws InitializationException If a problem occurs during 069 * initialization that is not 070 * related to the server 071 * configuration. 072 */ 073 public abstract void initializeSyntax(T configuration) 074 throws ConfigException, InitializationException; 075 076 077 078 /** 079 * Indicates whether the provided configuration is acceptable for 080 * this attribute syntax. It should be possible to call this method 081 * on an uninitialized attribute syntax instance in order to 082 * determine whether the syntax would be able to use the provided 083 * configuration. 084 * <BR><BR> 085 * Note that implementations which use a subclass of the provided 086 * configuration class will likely need to cast the configuration 087 * to the appropriate subclass type. 088 * 089 * @param configuration The attribute syntax configuration 090 * for which to make the determination. 091 * @param unacceptableReasons A list that may be used to hold the 092 * reasons that the provided 093 * configuration is not acceptable. 094 * 095 * @return {@code true} if the provided configuration is acceptable 096 * for this attribute syntax, or {@code false} if not. 097 */ 098 public boolean isConfigurationAcceptable( 099 AttributeSyntaxCfg configuration, 100 List<Message> unacceptableReasons) 101 { 102 // This default implementation does not perform any special 103 // validation. It should be overridden by attribute syntax 104 // implementations that wish to perform more detailed validation. 105 return true; 106 } 107 108 109 110 /** 111 * Performs any finalization that may be necessary for this 112 * attribute syntax. By default, no finalization is performed. 113 */ 114 public void finalizeSyntax() 115 { 116 // No implementation required. 117 } 118 119 120 121 /** 122 * Retrieves the common name for this attribute syntax. 123 * 124 * @return The common name for this attribute syntax. 125 */ 126 public abstract String getSyntaxName(); 127 128 129 130 /** 131 * Retrieves the OID for this attribute syntax. 132 * 133 * @return The OID for this attribute syntax. 134 */ 135 public abstract String getOID(); 136 137 138 139 /** 140 * Retrieves a description for this attribute syntax. 141 * 142 * @return A description for this attribute syntax. 143 */ 144 public abstract String getDescription(); 145 146 147 148 /** 149 * Retrieves the default equality matching rule that will be used 150 * for attributes with this syntax. 151 * 152 * @return The default equality matching rule that will be used for 153 * attributes with this syntax, or {@code null} if equality 154 * matches will not be allowed for this type by default. 155 */ 156 public abstract EqualityMatchingRule getEqualityMatchingRule(); 157 158 159 160 /** 161 * Retrieves the default ordering matching rule that will be used 162 * for attributes with this syntax. 163 * 164 * @return The default ordering matching rule that will be used for 165 * attributes with this syntax, or {@code null} if ordering 166 * matches will not be allowed for this type by default. 167 */ 168 public abstract OrderingMatchingRule getOrderingMatchingRule(); 169 170 171 172 /** 173 * Retrieves the default substring matching rule that will be used 174 * for attributes with this syntax. 175 * 176 * @return The default substring matching rule that will be used 177 * for attributes with this syntax, or {@code null} if 178 * substring matches will not be allowed for this type by 179 * default. 180 */ 181 public abstract SubstringMatchingRule getSubstringMatchingRule(); 182 183 184 185 /** 186 * Retrieves the default approximate matching rule that will be used 187 * for attributes with this syntax. 188 * 189 * @return The default approximate matching rule that will be used 190 * for attributes with this syntax, or {@code null} if 191 * approximate matches will not be allowed for this type by 192 * default. 193 */ 194 public abstract ApproximateMatchingRule 195 getApproximateMatchingRule(); 196 197 198 199 /** 200 * Indicates whether the provided value is acceptable for use in an 201 * attribute with this syntax. If it is not, then the reason may be 202 * appended to the provided buffer. 203 * 204 * @param value The value for which to make the 205 * determination. 206 * @param invalidReason The buffer to which the invalid reason 207 * should be appended. 208 * 209 * @return {@code true} if the provided value is acceptable for use 210 * with this syntax, or {@code false} if not. 211 */ 212 public abstract boolean valueIsAcceptable(ByteString value, 213 MessageBuilder invalidReason); 214 215 216 217 /** 218 * Retrieves the hash code for this attribute syntax. It will be 219 * calculated as the sum of the characters in the OID. 220 * 221 * @return The hash code for this attribute syntax. 222 */ 223 public final int hashCode() 224 { 225 int hashCode = 0; 226 227 String oidString = getOID(); 228 int oidLength = oidString.length(); 229 for (int i=0; i < oidLength; i++) 230 { 231 hashCode += oidString.charAt(i); 232 } 233 234 return hashCode; 235 } 236 237 238 239 /** 240 * Indicates whether the provided object is equal to this attribute 241 * syntax. The provided object will be considered equal to this 242 * attribute syntax only if it is an attribute syntax with the same 243 * OID. 244 * 245 * @param o The object for which to make the determination. 246 * 247 * @return {@code true} if the provided object is equal to this 248 * attribute syntax, or {@code false} if it is not. 249 */ 250 public final boolean equals(Object o) 251 { 252 if (o == null) 253 { 254 return false; 255 } 256 257 if (this == o) 258 { 259 return true; 260 } 261 262 if (! (o instanceof AttributeSyntax)) 263 { 264 return false; 265 } 266 267 return getOID().equals(((AttributeSyntax) o).getOID()); 268 } 269 270 271 272 /** 273 * Retrieves a string representation of this attribute syntax in the 274 * format defined in RFC 2252. 275 * 276 * @return A string representation of this attribute syntax in the 277 * format defined in RFC 2252. 278 */ 279 public final String toString() 280 { 281 StringBuilder buffer = new StringBuilder(); 282 toString(buffer); 283 return buffer.toString(); 284 } 285 286 287 288 /** 289 * Appends a string representation of this attribute syntax in the 290 * format defined in RFC 2252 to the provided buffer. 291 * 292 * @param buffer The buffer to which the information should be 293 * appended. 294 */ 295 public final void toString(StringBuilder buffer) 296 { 297 buffer.append("( "); 298 buffer.append(getOID()); 299 300 String description = getDescription(); 301 if ((description == null) || (description.length() == 0)) 302 { 303 buffer.append(" )"); 304 } 305 else 306 { 307 buffer.append(" DESC '"); 308 buffer.append(description); 309 buffer.append("' )"); 310 } 311 } 312 } 313