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}