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}