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
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Portions Copyright 2010-2024 Ping Identity Corporation
026 */
027package com.unboundid.directory.sdk.common.schema;
028
029
030
031import com.unboundid.util.ByteString;
032import com.unboundid.util.NotExtensible;
033import com.unboundid.util.ThreadSafety;
034import com.unboundid.util.ThreadSafetyLevel;
035
036
037
038/**
039 * This interface provides an API for interacting with attribute syntaxes, which
040 * can be used to constrain the kinds of data that may be stored in associated
041 * attributes.
042 */
043@NotExtensible()
044@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
045public interface AttributeSyntax
046{
047  /**
048   * Retrieves the numeric OID for this attribute syntax.
049   *
050   * @return  The numeric OID for this attribute syntax.
051   */
052  String getOID();
053
054
055
056  /**
057   * Retrieves the name for this attribute syntax, if any.
058   *
059   * @return  The name for this attribute syntax, or {@code null} if it does not
060   *          have a name.
061   */
062  String getName();
063
064
065
066  /**
067   * Retrieves the name for this attribute syntax, or the numeric OID if it does
068   * not have a name.
069   *
070   * @return  The name for this attribute syntax, or the numeric OID if it does
071   *          not have a name.
072   */
073  String getNameOrOID();
074
075
076
077  /**
078   * Indicates whether the provided string matches the name or numeric OID for
079   * this attribute syntax.
080   *
081   * @param  name  The name for which to make the determination.
082   *
083   * @return  {@code true} if the provided string matches the name or numeric
084   *          OID for this attribute syntax, or {@code false} if not.
085   */
086  boolean hasNameOrOID(final String name);
087
088
089
090  /**
091   * Retrieves the description for this attribute syntax, if any.
092   *
093   * @return  The description for this attribute syntax, or {@code null} if it
094   *          does not have a description.
095   */
096  String getDescription();
097
098
099
100  /**
101   * Retrieves the default equality matching rule that will be used for
102   * attribute types with this syntax which do not explicitly specify their own
103   * equality matching rule.
104   *
105   * @return  The default equality matching rule that will be used for attribute
106   *          types with this syntax, or {@code null} if there is no default
107   *          equality matching rule.
108   */
109  EqualityMatchingRule getDefaultEqualityMatchingRule();
110
111
112
113  /**
114   * Retrieves the default ordering matching rule that will be used for
115   * attribute types with this syntax which do not explicitly specify their own
116   * ordering matching rule.
117   *
118   * @return  The default ordering matching rule that will be used for attribute
119   *          types with this syntax, or {@code null} if there is no default
120   *          ordering matching rule.
121   */
122  OrderingMatchingRule getDefaultOrderingMatchingRule();
123
124
125
126  /**
127   * Retrieves the default substring matching rule that will be used for
128   * attribute types with this syntax which do not explicitly specify their own
129   * substring matching rule.
130   *
131   * @return  The default substring matching rule that will be used for
132   *          attribute types with this syntax, or {@code null} if there is no
133   *          default substring matching rule.
134   */
135  SubstringMatchingRule getDefaultSubstringMatchingRule();
136
137
138
139  /**
140   * Retrieves the default approximate matching rule that will be used for
141   * attribute types with this syntax which do not explicitly specify their own
142   * approximate matching rule.
143   *
144   * @return  The default approximate matching rule that will be used for
145   *          attribute types with this syntax, or {@code null} if there is no
146   *          default approximate matching rule.
147   */
148  ApproximateMatchingRule getDefaultApproximateMatchingRule();
149
150
151
152  /**
153   * Indicates whether the provided value is acceptable for use with this
154   * attribute syntax.  NOTE:  It is recommended that the
155   * {@link #valueIsAcceptable(AttributeType, ByteString, StringBuilder)}
156   * version of this method be used when possible.
157   *
158   * @param  value          The value for which to make the determination.
159   * @param  invalidReason  A buffer to which a message may be appended with
160   *                        information about why the given value is not
161   *                        acceptable.
162   *
163   * @return  {@code true} if the provided value is acceptable for use with this
164   *          attribute syntax, or {@code false} if not.
165   */
166  boolean valueIsAcceptable(final ByteString value,
167                            final StringBuilder invalidReason);
168
169
170
171  /**
172   * Indicates whether the provided value is acceptable for use with this
173   * attribute syntax.
174   *
175   * @param  attributeType  The attribute type with which the value is
176   *                        associated.
177   * @param  value          The value for which to make the determination.
178   * @param  invalidReason  A buffer to which a message may be appended with
179   *                        information about why the given value is not
180   *                        acceptable.
181   *
182   * @return  {@code true} if the provided value is acceptable for use with this
183   *          attribute syntax, or {@code false} if not.
184   */
185  boolean valueIsAcceptable(final AttributeType attributeType,
186                            final ByteString value,
187                            final StringBuilder invalidReason);
188
189
190
191  /**
192   * Retrieves the hash code for this attribute syntax.
193   *
194   * @return  The hash code for this attribute syntax.
195   */
196  int hashCode();
197
198
199
200  /**
201   * Indicates whether the provided object is equal to this attribute syntax.
202   *
203   * @param  o  The object for which to make the determination.
204   *
205   * @return  {@code true} if the provided object is equal to this attribute
206   *          syntax, or {@code false} if not.
207   */
208  boolean equals(final Object o);
209
210
211
212  /**
213   * Retrieves a string representation of this attribute syntax.
214   *
215   * @return  A string representation of this attribute syntax.
216   */
217  String toString();
218}