001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2006-2008 Sun Microsystems, Inc. 015 * Portions Copyright 2014-2016 ForgeRock AS. 016 */ 017package org.opends.server.types; 018 019import java.util.Collection; 020import java.util.Iterator; 021import java.util.List; 022 023import org.forgerock.opendj.ldap.AttributeDescription; 024import org.forgerock.opendj.ldap.ByteString; 025import org.forgerock.opendj.ldap.ConditionResult; 026 027/** 028 * This class defines a data structure for storing and interacting 029 * with an attribute that may be used in the Directory Server. 030 * <p> 031 * Attributes are immutable and therefore any attempts to modify them 032 * will result in an {@link UnsupportedOperationException}. 033 * <p> 034 * There are two types of attribute: real attributes and virtual attributes. 035 * Real attributes can be created using the {@link AttributeBuilder} class 036 * or by using the various static factory methods in the {@link Attributes} class, 037 * whereas virtual attributes are represented using the {@link VirtualAttribute} class. 038 * New attribute implementations can be implemented by either implementing this interface 039 * or by extending {@link AbstractAttribute}. 040 */ 041@org.opends.server.types.PublicAPI( 042 stability = org.opends.server.types.StabilityLevel.UNCOMMITTED, 043 mayInstantiate = false, 044 mayExtend = false, 045 mayInvoke = true) 046public interface Attribute extends Iterable<ByteString> 047{ 048 /** Marks code that can be removed once we are switching from server's to SDK's {@code Attribute}. */ 049 public @interface RemoveOnceSwitchingAttributes 050 { 051 /** Free-form comment. */ 052 String comment() default ""; 053 } 054 055 /** 056 * Indicates whether this attribute has any value(s) that are 057 * approximately equal to the provided value. 058 * 059 * @param assertionValue 060 * The assertion value for which to make the determination. 061 * @return {@link ConditionResult#UNDEFINED} if this attribute does not have 062 * an approximate matching rule, {@link ConditionResult#TRUE} if at 063 * least one value is approximately equal to the provided 064 * value, or {@link ConditionResult#FALSE} otherwise. 065 */ 066 ConditionResult approximatelyEqualTo(ByteString assertionValue); 067 068 /** 069 * Indicates whether this attribute contains the specified value. 070 * 071 * @param value 072 * The value for which to make the determination. 073 * @return {@code true} if this attribute has the specified 074 * value, or {@code false} if not. 075 */ 076 boolean contains(ByteString value); 077 078 /** 079 * Indicates whether this attribute contains all the values in the 080 * collection. 081 * 082 * @param values 083 * The set of values for which to make the determination. 084 * @return {@code true} if this attribute contains all the 085 * values in the provided collection, or {@code false} 086 * if it does not contain at least one of them. 087 */ 088 boolean containsAll(Collection<?> values); 089 090 /** 091 * Indicates whether this attribute matches the specified assertion value. 092 * 093 * @param assertionValue 094 * The assertion value for which to make the determination. 095 * @return {@code true} if this attribute matches the specified assertion 096 * value, or {@code false} if not. 097 */ 098 ConditionResult matchesEqualityAssertion(ByteString assertionValue); 099 100 /** 101 * Indicates whether the provided object is an attribute that is 102 * equal to this attribute. It will be considered equal if the 103 * attribute type, set of values, and set of options are equal. 104 * 105 * @param o 106 * The object for which to make the determination. 107 * @return {@code true} if the provided object is an 108 * attribute that is equal to this attribute, or 109 * {@code false} if not. 110 */ 111 @Override 112 boolean equals(Object o); 113 114 /** 115 * Retrieves the attribute description for this attribute. 116 * 117 * @return The attribute description for this attribute. 118 */ 119 AttributeDescription getAttributeDescription(); 120 121 /** 122 * Indicates whether this attribute has any value(s) that are 123 * greater than or equal to the provided value. 124 * 125 * @param assertionValue 126 * The assertion value for which to make the determination. 127 * @return {@link ConditionResult#UNDEFINED} if this attribute does not have 128 * an ordering matching rule, {@link ConditionResult#TRUE} if at 129 * least one value is greater than or equal to the provided 130 * assertion value, or {@link ConditionResult#FALSE} otherwise. 131 */ 132 ConditionResult greaterThanOrEqualTo(ByteString assertionValue); 133 134 /** 135 * Retrieves the hash code for this attribute. It will be calculated as the sum of the hash code 136 * for the attribute type and all values. 137 * 138 * @return The hash code for this attribute. 139 */ 140 @Override 141 int hashCode(); 142 143 /** 144 * Returns {@code true} if this attribute contains no 145 * attribute values. 146 * 147 * @return {@code true} if this attribute contains no 148 * attribute values. 149 */ 150 boolean isEmpty(); 151 152 /** 153 * Indicates whether this is a real attribute (persisted) rather than a virtual attribute 154 * (dynamically computed). 155 * 156 * @return {@code true} if this is a real attribute. 157 */ 158 boolean isReal(); 159 160 /** 161 * Indicates whether this is a virtual attribute (dynamically computed) rather than a real 162 * attribute (persisted). 163 * 164 * @return {@code true} if this is a virtual attribute. 165 */ 166 boolean isVirtual(); 167 168 /** 169 * Returns an iterator over the attribute values in this attribute. 170 * The attribute values are returned in the order in which they were 171 * added this attribute. The returned iterator does not support 172 * attribute value removals via {@link Iterator#remove()}. 173 * 174 * @return An iterator over the attribute values in this attribute. 175 */ 176 @Override 177 Iterator<ByteString> iterator(); 178 179 /** 180 * Indicates whether this attribute has any value(s) that are less 181 * than or equal to the provided value. 182 * 183 * @param assertionValue 184 * The assertion value for which to make the determination. 185 * @return {@link ConditionResult#UNDEFINED} if this attribute does not have 186 * an ordering matching rule, {@link ConditionResult#TRUE} if at 187 * least one value is less than or equal to the provided 188 * assertion value, or {@link ConditionResult#FALSE} otherwise. 189 */ 190 ConditionResult lessThanOrEqualTo(ByteString assertionValue); 191 192 /** 193 * Indicates whether this attribute has any value(s) that match the 194 * provided substring. 195 * 196 * @param subInitial 197 * The subInitial component to use in the determination. 198 * @param subAny 199 * The subAny components to use in the determination. 200 * @param subFinal 201 * The subFinal component to use in the determination. 202 * @return {@link ConditionResult#UNDEFINED} if this attribute does not have 203 * a substring matching rule, {@link ConditionResult#TRUE} if at 204 * least one value matches the provided substring, or 205 * {@link ConditionResult#FALSE} otherwise. 206 */ 207 ConditionResult matchesSubstring(ByteString subInitial, 208 List<ByteString> subAny, ByteString subFinal); 209 210 /** 211 * Returns the number of attribute values in this attribute. 212 * 213 * @return The number of attribute values in this attribute. 214 */ 215 int size(); 216 217 /** 218 * Retrieves a one-line string representation of this attribute. 219 * 220 * @return A one-line string representation of this attribute. 221 */ 222 @Override 223 String toString(); 224 225 /** 226 * Appends a one-line string representation of this attribute to the 227 * provided buffer. 228 * 229 * @param buffer 230 * The buffer to which the information should be appended. 231 */ 232 void toString(StringBuilder buffer); 233}