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   * Retrieves the user-provided name for this attribute.
123   *
124   * @return The user-provided name for this attribute.
125   */
126  String getName();
127
128  /**
129   * Retrieves the user-provided name of this attribute, along with
130   * any options that might have been provided.
131   *
132   * @return The user-provided name of this attribute, along with any
133   *         options that might have been provided.
134   */
135  String getNameWithOptions();
136
137  /**
138   * Indicates whether this attribute has any value(s) that are
139   * greater than or equal to the provided value.
140   *
141   * @param assertionValue
142   *          The assertion value for which to make the determination.
143   * @return {@link ConditionResult#UNDEFINED} if this attribute does not have
144   *         an ordering matching rule, {@link ConditionResult#TRUE} if at
145   *         least one value is greater than or equal to the provided
146   *         assertion value, or {@link ConditionResult#FALSE} otherwise.
147   */
148  ConditionResult greaterThanOrEqualTo(ByteString assertionValue);
149
150  /**
151   * Retrieves the hash code for this attribute. It will be calculated as the sum of the hash code
152   * for the attribute type and all values.
153   *
154   * @return The hash code for this attribute.
155   */
156  @Override
157  int hashCode();
158
159  /**
160   * Indicates whether this attribute has the specified option.
161   *
162   * @param option
163   *          The option for which to make the determination.
164   * @return {@code true} if this attribute has the specified option,
165   *         or {@code false} if not.
166   */
167  boolean hasOption(String option);
168
169  /**
170   * Indicates whether this attribute has any options at all.
171   *
172   * @return {@code true} if this attribute has at least one
173   *         option, or {@code false} if not.
174   */
175  boolean hasOptions();
176
177  /**
178   * Returns {@code true} if this attribute contains no
179   * attribute values.
180   *
181   * @return {@code true} if this attribute contains no
182   *         attribute values.
183   */
184  boolean isEmpty();
185
186  /**
187   * Indicates whether this is a real attribute (persisted) rather than a virtual attribute
188   * (dynamically computed).
189   *
190   * @return {@code true} if this is a real attribute.
191   */
192  boolean isReal();
193
194  /**
195   * Indicates whether this is a virtual attribute (dynamically computed) rather than a real
196   * attribute (persisted).
197   *
198   * @return {@code true} if this is a virtual attribute.
199   */
200  boolean isVirtual();
201
202  /**
203   * Returns an iterator over the attribute values in this attribute.
204   * The attribute values are returned in the order in which they were
205   * added this attribute. The returned iterator does not support
206   * attribute value removals via {@link Iterator#remove()}.
207   *
208   * @return An iterator over the attribute values in this attribute.
209   */
210  @Override
211  Iterator<ByteString> iterator();
212
213  /**
214   * Indicates whether this attribute has any value(s) that are less
215   * than or equal to the provided value.
216   *
217   * @param assertionValue
218   *          The assertion value for which to make the determination.
219   * @return {@link ConditionResult#UNDEFINED} if this attribute does not have
220   *         an ordering matching rule, {@link ConditionResult#TRUE} if at
221   *         least one value is less than or equal to the provided
222   *         assertion value, or {@link ConditionResult#FALSE} otherwise.
223   */
224  ConditionResult lessThanOrEqualTo(ByteString assertionValue);
225
226  /**
227   * Indicates whether this attribute has any value(s) that match the
228   * provided substring.
229   *
230   * @param subInitial
231   *          The subInitial component to use in the determination.
232   * @param subAny
233   *          The subAny components to use in the determination.
234   * @param subFinal
235   *          The subFinal component to use in the determination.
236   * @return {@link ConditionResult#UNDEFINED} if this attribute does not have
237   *         a substring matching rule, {@link ConditionResult#TRUE} if at
238   *         least one value matches the provided substring, or
239   *         {@link ConditionResult#FALSE} otherwise.
240   */
241  ConditionResult matchesSubstring(ByteString subInitial,
242      List<ByteString> subAny, ByteString subFinal);
243
244  /**
245   * Returns the number of attribute values in this attribute.
246   *
247   * @return The number of attribute values in this attribute.
248   */
249  int size();
250
251  /**
252   * Retrieves a one-line string representation of this attribute.
253   *
254   * @return A one-line string representation of this attribute.
255   */
256  @Override
257  String toString();
258
259  /**
260   * Appends a one-line string representation of this attribute to the
261   * provided buffer.
262   *
263   * @param buffer
264   *          The buffer to which the information should be appended.
265   */
266  void toString(StringBuilder buffer);
267}