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 {@link ConditionResult#UNDEFINED} if this attribute does not have
065   *         an approximate matching rule, {@link ConditionResult#TRUE} if at
066   *         least one value is approximately equal to the provided
067   *         value, or {@link ConditionResult#FALSE} 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} if this attribute has the specified
077   *         value, or {@code false} 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} if this attribute contains all the
088   *         values in the provided collection, or {@code false}
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} if this attribute matches the specified assertion
099   *         value, or {@code false} 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} if the provided object is an
111   *         attribute that is equal to this attribute, or
112   *         {@code false} 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 {@link ConditionResult#UNDEFINED} if this attribute does not have
156   *         an ordering matching rule, {@link ConditionResult#TRUE} if at
157   *         least one value is greater than or equal to the provided
158   *         assertion value, or {@link ConditionResult#FALSE} otherwise.
159   */
160  ConditionResult greaterThanOrEqualTo(ByteString assertionValue);
161
162  /**
163   * Indicates whether this attribute has all of the options in the provided collection.
164   *
165   * @param options
166   *          The collection of options for which to make the determination (may be {@code null}).
167   * @return {@code true} if this attribute has all of the specified options,
168   *         or {@code false} if it does not have at least one of them.
169   */
170  boolean hasAllOptions(Collection<String> options);
171
172  /**
173   * Retrieves the hash code for this attribute. It will be calculated
174   * as the sum of the hash code for the attribute type and all values.
175   *
176   * @return The hash code for this attribute.
177   */
178  @Override
179  int hashCode();
180
181  /**
182   * Indicates whether this attribute has the specified option.
183   *
184   * @param option
185   *          The option for which to make the determination.
186   * @return {@code true} if this attribute has the specified option,
187   *         or {@code false} if not.
188   */
189  boolean hasOption(String option);
190
191  /**
192   * Indicates whether this attribute has any options at all.
193   *
194   * @return {@code true} if this attribute has at least one
195   *         option, or {@code false} if not.
196   */
197  boolean hasOptions();
198
199  /**
200   * Returns {@code true} if this attribute contains no
201   * attribute values.
202   *
203   * @return {@code true} if this attribute contains no
204   *         attribute values.
205   */
206  boolean isEmpty();
207
208  /**
209   * Indicates whether this is a real attribute (persisted) rather than a virtual attribute
210   * (dynamically computed).
211   *
212   * @return {@code true} if this is a real attribute.
213   */
214  boolean isReal();
215
216  /**
217   * Indicates whether this is a virtual attribute (dynamically computed) rather than a real
218   * attribute (persisted).
219   *
220   * @return {@code true} if this is a virtual attribute.
221   */
222  boolean isVirtual();
223
224  /**
225   * Returns an iterator over the attribute values in this attribute.
226   * The attribute values are returned in the order in which they were
227   * added this attribute. The returned iterator does not support
228   * attribute value removals via {@link Iterator#remove()}.
229   *
230   * @return An iterator over the attribute values in this attribute.
231   */
232  @Override
233  Iterator<ByteString> iterator();
234
235  /**
236   * Indicates whether this attribute has any value(s) that are less
237   * than or equal to the provided value.
238   *
239   * @param assertionValue
240   *          The assertion value for which to make the determination.
241   * @return {@link ConditionResult#UNDEFINED} if this attribute does not have
242   *         an ordering matching rule, {@link ConditionResult#TRUE} if at
243   *         least one value is less than or equal to the provided
244   *         assertion value, or {@link ConditionResult#FALSE} otherwise.
245   */
246  ConditionResult lessThanOrEqualTo(ByteString assertionValue);
247
248  /**
249   * Indicates whether this attribute has any value(s) that match the
250   * provided substring.
251   *
252   * @param subInitial
253   *          The subInitial component to use in the determination.
254   * @param subAny
255   *          The subAny components to use in the determination.
256   * @param subFinal
257   *          The subFinal component to use in the determination.
258   * @return {@link ConditionResult#UNDEFINED} if this attribute does not have
259   *         a substring matching rule, {@link ConditionResult#TRUE} if at
260   *         least one value matches the provided substring, or
261   *         {@link ConditionResult#FALSE} otherwise.
262   */
263  ConditionResult matchesSubstring(ByteString subInitial,
264      List<ByteString> subAny, ByteString subFinal);
265
266  /**
267   * Indicates whether this attribute has exactly the specified set of
268   * options.
269   *
270   * @param options
271   *          The set of options for which to make the determination
272   *          (may be {@code null}).
273   * @return {@code true} if this attribute has exactly the
274   *         specified set of options.
275   */
276  boolean optionsEqual(Set<String> options);
277
278  /**
279   * Returns the number of attribute values in this attribute.
280   *
281   * @return The number of attribute values in this attribute.
282   */
283  int size();
284
285  /**
286   * Retrieves a one-line string representation of this attribute.
287   *
288   * @return A one-line string representation of this attribute.
289   */
290  @Override
291  String toString();
292
293  /**
294   * Appends a one-line string representation of this attribute to the
295   * provided buffer.
296   *
297   * @param buffer
298   *          The buffer to which the information should be appended.
299   */
300  void toString(StringBuilder buffer);
301}