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 legal-notices/CDDLv1_0.txt 010 * or http://forgerock.org/license/CDDLv1.0.html. 011 * See the License for the specific language governing permissions 012 * and limitations under the License. 013 * 014 * When distributing Covered Code, include this CDDL HEADER in each 015 * file and include the License file at legal-notices/CDDLv1_0.txt. 016 * If applicable, add the following below this CDDL HEADER, with the 017 * fields enclosed by brackets "[]" replaced with your own identifying 018 * information: 019 * Portions Copyright [yyyy] [name of copyright owner] 020 * 021 * CDDL HEADER END 022 * 023 * 024 * Copyright 2006-2008 Sun Microsystems, Inc. 025 * Portions Copyright 2014-2015 ForgeRock AS 026 */ 027package org.opends.server.types; 028 029import java.util.Collection; 030import java.util.Iterator; 031import java.util.List; 032import java.util.Set; 033 034import org.forgerock.opendj.ldap.ByteString; 035import org.forgerock.opendj.ldap.ConditionResult; 036 037/** 038 * This class defines a data structure for storing and interacting 039 * with an attribute that may be used in the Directory Server. 040 * <p> 041 * Attributes are immutable and therefore any attempts to modify them 042 * will result in an {@link UnsupportedOperationException}. 043 * <p> 044 * There are two types of attribute: real attributes and virtual attributes. 045 * Real attributes can be created using the {@link AttributeBuilder} class 046 * or by using the various static factory methods in the {@link Attributes} class, 047 * whereas virtual attributes are represented using the {@link VirtualAttribute} class. 048 * New attribute implementations can be implemented by either implementing this interface 049 * or by extending {@link AbstractAttribute}. 050 */ 051@org.opends.server.types.PublicAPI( 052 stability = org.opends.server.types.StabilityLevel.UNCOMMITTED, 053 mayInstantiate = false, 054 mayExtend = false, 055 mayInvoke = true) 056public interface Attribute extends Iterable<ByteString> 057{ 058 /** 059 * Indicates whether this attribute has any value(s) that are 060 * approximately equal to the provided value. 061 * 062 * @param assertionValue 063 * The assertion value for which to make the determination. 064 * @return <CODE>UNDEFINED</CODE> if this attribute does not have 065 * an approximate matching rule, <CODE>TRUE</CODE> if at 066 * least one value is approximately equal to the provided 067 * value, or <CODE>false</CODE> otherwise. 068 */ 069 ConditionResult approximatelyEqualTo(ByteString assertionValue); 070 071 /** 072 * Indicates whether this attribute contains the specified value. 073 * 074 * @param value 075 * The value for which to make the determination. 076 * @return <CODE>true</CODE> if this attribute has the specified 077 * value, or <CODE>false</CODE> if not. 078 */ 079 boolean contains(ByteString value); 080 081 /** 082 * Indicates whether this attribute contains all the values in the 083 * collection. 084 * 085 * @param values 086 * The set of values for which to make the determination. 087 * @return <CODE>true</CODE> if this attribute contains all the 088 * values in the provided collection, or <CODE>false</CODE> 089 * if it does not contain at least one of them. 090 */ 091 boolean containsAll(Collection<ByteString> values); 092 093 /** 094 * Indicates whether this attribute matches the specified assertion value. 095 * 096 * @param assertionValue 097 * The assertion value for which to make the determination. 098 * @return <CODE>true</CODE> if this attribute matches the specified assertion 099 * value, or <CODE>false</CODE> if not. 100 */ 101 ConditionResult matchesEqualityAssertion(ByteString assertionValue); 102 103 /** 104 * Indicates whether the provided object is an attribute that is 105 * equal to this attribute. It will be considered equal if the 106 * attribute type, set of values, and set of options are equal. 107 * 108 * @param o 109 * The object for which to make the determination. 110 * @return <CODE>true</CODE> if the provided object is an 111 * attribute that is equal to this attribute, or 112 * <CODE>false</CODE> if not. 113 */ 114 @Override 115 boolean equals(Object o); 116 117 /** 118 * Retrieves the attribute type for this attribute. 119 * 120 * @return The attribute type for this attribute. 121 */ 122 AttributeType getAttributeType(); 123 124 /** 125 * Retrieves the user-provided name for this attribute. 126 * 127 * @return The user-provided name for this attribute. 128 */ 129 String getName(); 130 131 /** 132 * Retrieves the user-provided name of this attribute, along with 133 * any options that might have been provided. 134 * 135 * @return The user-provided name of this attribute, along with any 136 * options that might have been provided. 137 */ 138 String getNameWithOptions(); 139 140 /** 141 * Retrieves the unmodifiable set of attribute options for this 142 * attribute. The returned set of options are not normalized. 143 * 144 * @return The unmodifiable set of attribute options for this 145 * attribute. 146 */ 147 Set<String> getOptions(); 148 149 /** 150 * Indicates whether this attribute has any value(s) that are 151 * greater than or equal to the provided value. 152 * 153 * @param assertionValue 154 * The assertion value for which to make the determination. 155 * @return <CODE>UNDEFINED</CODE> if this attribute does not have 156 * an ordering matching rule, <CODE>TRUE</CODE> if at 157 * least one value is greater than or equal to the provided 158 * assertion value, or <CODE>false</CODE> otherwise. 159 */ 160 ConditionResult greaterThanOrEqualTo(ByteString assertionValue); 161 162 /** 163 * Indicates whether this attribute has all of the options in the 164 * provided collection. 165 * 166 * @param options 167 * The collection of options for which to make the 168 * determination (may be <code>null</code>). 169 * @return <CODE>true</CODE> if this attribute has all of the 170 * specified options, or <CODE>false</CODE> if it does not 171 * have at least one of them. 172 */ 173 boolean hasAllOptions(Collection<String> options); 174 175 /** 176 * Retrieves the hash code for this attribute. It will be calculated 177 * as the sum of the hash code for the attribute type and all 178 * values. 179 * 180 * @return The hash code for this attribute. 181 */ 182 @Override 183 int hashCode(); 184 185 /** 186 * Indicates whether this attribute has the specified option. 187 * 188 * @param option 189 * The option for which to make the determination. 190 * @return <CODE>true</CODE> if this attribute has the specified 191 * option, or <CODE>false</CODE> if not. 192 */ 193 boolean hasOption(String option); 194 195 /** 196 * Indicates whether this attribute has any options at all. 197 * 198 * @return <CODE>true</CODE> if this attribute has at least one 199 * option, or <CODE>false</CODE> if not. 200 */ 201 boolean hasOptions(); 202 203 /** 204 * Returns <code>true</code> if this attribute contains no 205 * attribute values. 206 * 207 * @return <CODE>true</CODE> if this attribute contains no 208 * attribute values. 209 */ 210 boolean isEmpty(); 211 212 /** 213 * Indicates whether this is a real attribute (persisted) rather than a virtual attribute 214 * (dynamically computed). 215 * 216 * @return {@code true} if this is a real attribute. 217 */ 218 boolean isReal(); 219 220 /** 221 * Indicates whether this is a virtual attribute (dynamically computed) rather than a real 222 * attribute (persisted). 223 * 224 * @return {@code true} if this is a virtual attribute. 225 */ 226 boolean isVirtual(); 227 228 /** 229 * Returns an iterator over the attribute values in this attribute. 230 * The attribute values are returned in the order in which they were 231 * added this attribute. The returned iterator does not support 232 * attribute value removals via its <code>remove</code> method. 233 * 234 * @return An iterator over the attribute values in this attribute. 235 */ 236 @Override 237 Iterator<ByteString> iterator(); 238 239 /** 240 * Indicates whether this attribute has any value(s) that are less 241 * than or equal to the provided value. 242 * 243 * @param assertionValue 244 * The assertion value for which to make the determination. 245 * @return <CODE>UNDEFINED</CODE> if this attribute does not have 246 * an ordering matching rule, <CODE>TRUE</CODE> if at 247 * least one value is less than or equal to the provided 248 * assertion value, or <CODE>false</CODE> otherwise. 249 */ 250 ConditionResult lessThanOrEqualTo(ByteString assertionValue); 251 252 /** 253 * Indicates whether this attribute has any value(s) that match the 254 * provided substring. 255 * 256 * @param subInitial 257 * The subInitial component to use in the determination. 258 * @param subAny 259 * The subAny components to use in the determination. 260 * @param subFinal 261 * The subFinal component to use in the determination. 262 * @return <CODE>UNDEFINED</CODE> if this attribute does not have 263 * a substring matching rule, <CODE>TRUE</CODE> if at 264 * least one value matches the provided substring, or 265 * <CODE>FALSE</CODE> otherwise. 266 */ 267 ConditionResult matchesSubstring(ByteString subInitial, 268 List<ByteString> subAny, ByteString subFinal); 269 270 /** 271 * Indicates whether this attribute has exactly the specified set of 272 * options. 273 * 274 * @param options 275 * The set of options for which to make the determination 276 * (may be <code>null</code>). 277 * @return <CODE>true</CODE> if this attribute has exactly the 278 * specified set of options. 279 */ 280 boolean optionsEqual(Set<String> options); 281 282 /** 283 * Returns the number of attribute values in this attribute. 284 * 285 * @return The number of attribute values in this attribute. 286 */ 287 int size(); 288 289 /** 290 * Retrieves a one-line string representation of this attribute. 291 * 292 * @return A one-line string representation of this attribute. 293 */ 294 @Override 295 String toString(); 296 297 /** 298 * Appends a one-line string representation of this attribute to the 299 * provided buffer. 300 * 301 * @param buffer 302 * The buffer to which the information should be appended. 303 */ 304 void toString(StringBuilder buffer); 305}