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 2009 Sun Microsystems, Inc.
015 */
016
017package org.forgerock.opendj.ldap.schema;
018
019import org.forgerock.i18n.LocalizableMessageBuilder;
020import org.forgerock.opendj.ldap.ByteSequence;
021
022/**
023 * This interface defines the set of methods and structures that must be
024 * implemented to define a new attribute syntax.
025 */
026public interface SyntaxImpl {
027    /**
028     * Retrieves the default approximate matching rule that will be used for
029     * attributes with this syntax.
030     *
031     * @return The default approximate matching rule that will be used for
032     *         attributes with this syntax, or {@code null} if approximate
033     *         matches will not be allowed for this type by default.
034     */
035    String getApproximateMatchingRule();
036
037    /**
038     * Retrieves the default equality matching rule that will be used for
039     * attributes with this syntax.
040     *
041     * @return The default equality matching rule that will be used for
042     *         attributes with this syntax, or {@code null} if equality matches
043     *         will not be allowed for this type by default.
044     */
045    String getEqualityMatchingRule();
046
047    /**
048     * Retrieves the common name for this attribute syntax.
049     *
050     * @return The common name for this attribute syntax.
051     */
052    String getName();
053
054    /**
055     * Retrieves the default ordering matching rule that will be used for
056     * attributes with this syntax.
057     *
058     * @return The default ordering matching rule that will be used for
059     *         attributes with this syntax, or {@code null} if ordering matches
060     *         will not be allowed for this type by default.
061     */
062    String getOrderingMatchingRule();
063
064    /**
065     * Retrieves the default substring matching rule that will be used for
066     * attributes with this syntax.
067     *
068     * @return The default substring matching rule that will be used for
069     *         attributes with this syntax, or {@code null} if substring matches
070     *         will not be allowed for this type by default.
071     */
072    String getSubstringMatchingRule();
073
074    /**
075     * Indicates whether this attribute syntax requires that values must be
076     * encoded using the Basic Encoding Rules (BER) used by X.500 directories
077     * and always include the {@code binary} attribute description option.
078     *
079     * @return {@code true} this attribute syntax requires that values must be
080     *         BER encoded and always include the {@code binary} attribute
081     *         description option, or {@code false} if not.
082     * @see <a href="http://tools.ietf.org/html/rfc4522">RFC 4522 - Lightweight
083     *      Directory Access Protocol (LDAP): The Binary Encoding Option </a>
084     */
085    boolean isBEREncodingRequired();
086
087    /**
088     * Indicates whether this attribute syntax would likely be a human readable
089     * string.
090     *
091     * @return {@code true} if this attribute syntax would likely be a human
092     *         readable string or {@code false} if not.
093     */
094    boolean isHumanReadable();
095
096    /**
097     * Indicates whether the provided value is acceptable for use in an
098     * attribute with this syntax. If it is not, then the reason may be appended
099     * to the provided buffer.
100     *
101     * @param schema
102     *            The schema in which this syntax is defined.
103     * @param value
104     *            The value for which to make the determination.
105     * @param invalidReason
106     *            The buffer to which the invalid reason should be appended.
107     * @return {@code true} if the provided value is acceptable for use with
108     *         this syntax, or {@code false} if not.
109     */
110    boolean valueIsAcceptable(Schema schema, ByteSequence value,
111            LocalizableMessageBuilder invalidReason);
112}