Package org.forgerock.opendj.ldap.schema

Class Schema

  • @Immutable
public final class Schema
extends Object
    This class defines a data structure that holds information about the components of the LDAP schema. It includes the following kinds of elements:
    • Attribute type definitions
    • Object class definitions
    • Attribute syntax definitions
    • Matching rule definitions
    • Matching rule use definitions
    • DIT content rule definitions
    • DIT structure rule definitions
    • Name form definitions

    • Method Detail

      • getDefaultSchema

        public static Schema getDefaultSchema()
        Returns the default schema which should be used by this application. The default schema is initially set to the core schema.
        Returns:
        The default schema which should be used by this application.

      • getEmptySchema

        public static Schema getEmptySchema()
        Returns the empty schema. The empty schema is non-strict and does not contain any schema elements.
        Returns:
        The empty schema.

      • getReadSchemaSearchRequest

        public static SearchRequest getReadSchemaSearchRequest​(Dn name)
        Constructs a search request for retrieving the named subschema sub-entry.
        Parameters:
        name - The distinguished name of the subschema sub-entry.
        Returns:
        A SearchRequest to fetch the schema from the given dn.

      • readSchema

        public static Schema readSchema​(Connection connection,
                                Dn name)
                         throws LdapException
        Reads the schema contained in the named subschema sub-entry.

        If the requested schema is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null.

        Parameters:
        connection - A connection to the Directory Server whose schema is to be read.
        name - The distinguished name of the subschema sub-entry.
        Returns:
        The schema from the Directory Server.
        Throws:
        LdapException - If the result code indicates that the request failed for some reason.
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if connection.isClosed() == true.
        NullPointerException - If the connection or name was null.

      • readSchemaAsync

        public static LdapPromise<Schema> readSchemaAsync​(Connection connection,
                                                  Dn name)
        Asynchronously reads the schema contained in the named subschema sub-entry.

        If the requested schema is not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, the returned promise will never return null.

        Parameters:
        connection - A connection to the Directory Server whose schema is to be read.
        name - The distinguished name of the subschema sub-entry. the operation result when it is received, may be null.
        Returns:
        A promise representing the retrieved schema.
        Throws:
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if connection.isClosed() == true.
        NullPointerException - If the connection or name was null.

      • readSchema

        public static Single<Schema> readSchema​(LdapClientSocket socket,
                                        Dn name)
        Reads the schema contained in the named subschema sub-entry.

        If the requested schema is not returned by the Directory Server then the request will fail with an EntryNotFoundException.

        Note that the schema will only be read when the returned Single has been subscribed.

        Parameters:
        socket - A socket to the Directory Server whose schema is to be read.
        name - The distinguished name of the subschema sub-entry.
        Returns:
        A Single wrapping the schema from the Directory Server.
        Throws:
        UnsupportedOperationException - If the socket does not support search operations.
        IllegalStateException - If the socket has already been closed, i.e. if socket.isClosed() == true.
        NullPointerException - If the socket or name was null.

      • readSchemaForEntry

        public static Schema readSchemaForEntry​(Connection connection,
                                        Dn name)
                                 throws LdapException
        Reads the schema contained in the subschema sub-entry which applies to the named entry.

        If the requested entry or its associated schema are not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, this method will never return null.

        This implementation first reads the subschemaSubentry attribute of the entry in order to identify the schema and then invokes readSchema(Connection, Dn) to read the schema.

        Parameters:
        connection - A connection to the Directory Server whose schema is to be read.
        name - The distinguished name of the entry whose schema is to be located.
        Returns:
        The schema from the Directory Server which applies to the named entry.
        Throws:
        LdapException - If the result code indicates that the request failed for some reason.
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if connection.isClosed() == true.
        NullPointerException - If the connection or name was null.

      • readSchemaForEntryAsync

        public static LdapPromise<Schema> readSchemaForEntryAsync​(Connection connection,
                                                          Dn name)
        Asynchronously reads the schema contained in the subschema sub-entry which applies to the named entry.

        If the requested entry or its associated schema are not returned by the Directory Server then the request will fail with an EntryNotFoundException. More specifically, the returned promise will never return null.

        This implementation first reads the subschemaSubentry attribute of the entry in order to identify the schema and then invokes readSchemaAsync(Connection, Dn) to read the schema.

        Parameters:
        connection - A connection to the Directory Server whose schema is to be read.
        name - The distinguished name of the entry whose schema is to be located.
        Returns:
        A promise representing the retrieved schema.
        Throws:
        UnsupportedOperationException - If the connection does not support search operations.
        IllegalStateException - If the connection has already been closed, i.e. if connection.isClosed() == true.
        NullPointerException - If the connection or name was null.

      • readSchemaForEntry

        public static Single<Schema> readSchemaForEntry​(LdapClientSocket socket,
                                                Dn name)
        Reads the schema contained in the subschema sub-entry which applies to the named entry.

        If the requested entry or its associated schema are not returned by the Directory Server then the request will fail with an EntryNotFoundException.

        This implementation first reads the subschemaSubentry attribute of the entry in order to identify the schema and then invokes readSchema(LdapClientSocket, Dn) to read the schema.

        Note that the schema will only be read when the returned Single has been subscribed.

        Parameters:
        socket - A socket to the Directory Server whose schema is to be read.
        name - The distinguished name of the entry whose schema is to be located.
        Returns:
        A Single wrapping the retrieved schema.
        Throws:
        UnsupportedOperationException - If the socket does not support search operations.
        IllegalStateException - If the socket has already been closed, i.e. if socket.isClosed() == true.
        NullPointerException - If the socket or name was null.

      • setDefaultSchema

        public static void setDefaultSchema​(Schema schema)
        Sets the default schema which should be used by this application. The default schema is initially set to the core schema.
        Parameters:
        schema - The default schema which should be used by this application.

      • valueOf

        public static Schema valueOf​(Entry entry)
        Parses the provided entry as a subschema subentry. Any problems encountered while parsing the entry can be retrieved using the returned schema's getWarnings() method.
        Parameters:
        entry - The subschema subentry to be parsed.
        Returns:
        The parsed schema.

      • asNonStrictSchema

        public Schema asNonStrictSchema()
        Returns a non-strict view of this schema.

        See the description of isStrict() for more details.

        Returns:
        A non-strict view of this schema.
        See Also:
        isStrict()

      • asStrictSchema

        public Schema asStrictSchema()
        Returns a strict view of this schema.

        See the description of isStrict() for more details.

        Returns:
        A strict view of this schema.
        See Also:
        isStrict()

      • getAttributeType

        public AttributeType getAttributeType​(String nameOrOid)
        Returns the attribute type for the specified name or numeric OID.

        If the requested attribute type is not registered in this schema and this schema is non-strict then a temporary "place-holder" attribute type will be created and returned. Place holder attribute types have an OID which is the normalized attribute name with the string -oid appended. In addition, they will use the directory string syntax and case ignore matching rule.

        Parameters:
        nameOrOid - The name or OID of the attribute type to retrieve.
        Returns:
        The requested attribute type.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested attribute type was not found.
        See Also:
        AttributeType.isPlaceHolder()

      • getAttributeType

        public AttributeType getAttributeType​(String nameOrOid,
                                      Syntax syntax)
        Returns the attribute type for the specified name or numeric OID.

        If the requested attribute type is not registered in this schema and this schema is non-strict then a temporary "place-holder" attribute type will be created and returned. Place holder attribute types have an OID which is the normalized attribute name with the string -oid appended. In addition, they will use the provided syntax and the default matching rule associated with the syntax.

        Parameters:
        nameOrOid - The name or OID of the attribute type to retrieve.
        syntax - The syntax to use when creating the temporary "place-holder" attribute type.
        Returns:
        The requested attribute type.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested attribute type was not found.
        See Also:
        AttributeType.isPlaceHolder()

      • getAttributeTypes

        public Collection<AttributeType> getAttributeTypes()
        Returns an unmodifiable collection containing all of the attribute types contained in this schema.
        Returns:
        An unmodifiable collection containing all of the attribute types contained in this schema.

      • getDitContentRule

        public DitContentRule getDitContentRule​(ObjectClass structuralClass)
        Returns the DIT content rule associated with the provided structural object class, or null if no rule is defined.
        Parameters:
        structuralClass - The structural object class .
        Returns:
        The DIT content rule associated with the provided structural object class, or null if no rule is defined.

      • getDitContentRule

        public DitContentRule getDitContentRule​(String nameOrOid)
        Returns the DIT content rule with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the DIT content rule to retrieve.
        Returns:
        The requested DIT content rule.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested DIT content rule was not found.

      • getDitContentRules

        public Collection<DitContentRule> getDitContentRules()
        Returns an unmodifiable collection containing all of the DIT content rules contained in this schema.
        Returns:
        An unmodifiable collection containing all of the DIT content rules contained in this schema.

      • getDitStructureRule

        public DitStructureRule getDitStructureRule​(int ruleId)
        Returns the DIT structure rule with the specified name or numeric OID.
        Parameters:
        ruleId - The ID of the DIT structure rule to retrieve.
        Returns:
        The requested DIT structure rule.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested DIT structure rule was not found.

      • getDitStructureRule

        public DitStructureRule getDitStructureRule​(String nameOrOid)
        Returns the DIT structure rule with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the DIT structure rule to retrieve.
        Returns:
        The requested DIT structure rule.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested DIT structure rule was not found.

      • getDitStructureRules

        public Collection<DitStructureRule> getDitStructureRules​(NameForm nameForm)
        Returns an unmodifiable collection containing all of the DIT structure rules associated with the provided name form.
        Parameters:
        nameForm - The name form.
        Returns:
        An unmodifiable collection containing all of the DIT structure rules associated with the provided name form.

      • getDitStuctureRules

        public Collection<DitStructureRule> getDitStuctureRules()
        Returns an unmodifiable collection containing all of the DIT structure rules contained in this schema.
        Returns:
        An unmodifiable collection containing all of the DIT structure rules contained in this schema.

      • getMatchingRule

        public MatchingRule getMatchingRule​(String nameOrOid)
        Returns the matching rule with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the matching rule to retrieve.
        Returns:
        The requested matching rule.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested matching rule was not found.

      • getMatchingRules

        public Collection<MatchingRule> getMatchingRules()
        Returns an unmodifiable collection containing all of the matching rules contained in this schema.
        Returns:
        An unmodifiable collection containing all of the matching rules contained in this schema.

      • getMatchingRuleUse

        public MatchingRuleUse getMatchingRuleUse​(MatchingRule matchingRule)
        Returns the matching rule use associated with the provided matching rule, or null if no use is defined.
        Parameters:
        matchingRule - The matching rule whose matching rule use is to be retrieved.
        Returns:
        The matching rule use associated with the provided matching rule, or null if no use is defined.

      • getMatchingRuleUse

        public MatchingRuleUse getMatchingRuleUse​(String nameOrOid)
        Returns the matching rule use with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the matching rule use to retrieve.
        Returns:
        The requested matching rule use.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested matching rule use was not found.

      • getMatchingRuleUses

        public Collection<MatchingRuleUse> getMatchingRuleUses()
        Returns an unmodifiable collection containing all of the matching rule uses contained in this schema.
        Returns:
        An unmodifiable collection containing all of the matching rule uses contained in this schema.

      • getNameForm

        public NameForm getNameForm​(String nameOrOid)
        Returns the name form with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the name form to retrieve.
        Returns:
        The requested name form.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested name form was not found.

      • getNameForms

        public Collection<NameForm> getNameForms()
        Returns an unmodifiable collection containing all of the name forms contained in this schema.
        Returns:
        An unmodifiable collection containing all of the name forms contained in this schema.

      • getNameForms

        public Collection<NameForm> getNameForms​(ObjectClass structuralClass)
        Returns an unmodifiable collection containing all of the name forms associated with the provided structural object class.
        Parameters:
        structuralClass - The structural object class whose name forms are to be retrieved.
        Returns:
        An unmodifiable collection containing all of the name forms associated with the provided structural object class.

      • getObjectClass

        public ObjectClass getObjectClass​(String nameOrOid)
        Returns the object class with the specified name or numeric OID.

        If the requested object class is not registered in this schema and this schema is non-strict then a temporary "place-holder" object class will be created and returned. Place holder object classes have an OID which is the normalized name with the string -oid appended.

        Parameters:
        nameOrOid - The name or OID of the object class to retrieve.
        Returns:
        The requested object class.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested object class was not found.
        See Also:
        ObjectClass.isPlaceHolder()

      • getObjectClasses

        public Collection<ObjectClass> getObjectClasses()
        Returns an unmodifiable collection containing all of the object classes contained in this schema.
        Returns:
        An unmodifiable collection containing all of the object classes contained in this schema.

      • getOption

        public <T> T getOption​(Option<T> option)
        Returns the value associated to the provided Option or the option default value, if there is no such option in this schema.
        Type Parameters:
        T - The option type.
        Parameters:
        option - The option whose associated value should to be retrieve.
        Returns:
        The value associated to the provided Option or the option default value, if there is no such option in this schema.

      • getSchemaName

        public String getSchemaName()
        Returns the user-friendly name of this schema which may be used for debugging purposes. The format of the schema name is not defined but should contain the distinguished name of the subschema sub-entry for those schemas retrieved from a Directory Server.
        Returns:
        The user-friendly name of this schema which may be used for debugging purposes.

      • getSyntax

        public Syntax getSyntax​(String numericOid)
        Returns the syntax with the specified numeric OID.
        Parameters:
        numericOid - The OID of the syntax to retrieve.
        Returns:
        The requested syntax.
        Throws:
        UnknownSchemaElementException - If this is a strict schema and the requested syntax was not found or if the provided name is ambiguous.

      • getSyntaxes

        public Collection<Syntax> getSyntaxes()
        Returns an unmodifiable collection containing all of the syntaxes contained in this schema.
        Returns:
        An unmodifiable collection containing all of the syntaxes contained in this schema.

      • getWarnings

        public Collection<LocalizableMessage> getWarnings()
        Returns an unmodifiable collection containing all of the warnings that were detected when this schema was constructed.
        Returns:
        An unmodifiable collection containing all of the warnings that were detected when this schema was constructed.

      • hasAttributeType

        public boolean hasAttributeType​(String nameOrOid)
        Indicates whether this schema contains an attribute type with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the attribute type.
        Returns:
        true if this schema contains an attribute type with the specified name or numeric OID, otherwise false.

      • hasDitContentRule

        public boolean hasDitContentRule​(String nameOrOid)
        Indicates whether this schema contains a DIT content rule with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the DIT content rule.
        Returns:
        true if this schema contains a DIT content rule with the specified name or numeric OID, otherwise false.

      • hasDitStructureRule

        public boolean hasDitStructureRule​(int ruleId)
        Indicates whether this schema contains a DIT structure rule with the specified rule ID.
        Parameters:
        ruleId - The ID of the DIT structure rule.
        Returns:
        true if this schema contains a DIT structure rule with the specified rule ID, otherwise false.

      • hasMatchingRule

        public boolean hasMatchingRule​(String nameOrOid)
        Indicates whether this schema contains a matching rule with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the matching rule.
        Returns:
        true if this schema contains a matching rule with the specified name or numeric OID, otherwise false.

      • hasMatchingRuleUse

        public boolean hasMatchingRuleUse​(String nameOrOid)
        Indicates whether this schema contains a matching rule use with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the matching rule use.
        Returns:
        true if this schema contains a matching rule use with the specified name or numeric OID, otherwise false.

      • hasNameForm

        public boolean hasNameForm​(String nameOrOid)
        Indicates whether this schema contains a name form with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the name form.
        Returns:
        true if this schema contains a name form with the specified name or numeric OID, otherwise false.

      • hasObjectClass

        public boolean hasObjectClass​(String nameOrOid)
        Indicates whether this schema contains an object class with the specified name or numeric OID.
        Parameters:
        nameOrOid - The name or OID of the object class.
        Returns:
        true if this schema contains an object class with the specified name or numeric OID, otherwise false.

      • hasSyntax

        public boolean hasSyntax​(String numericOid)
        Indicates whether this schema contains a syntax with the specified numeric OID.
        Parameters:
        numericOid - The OID of the syntax.
        Returns:
        true if this schema contains a syntax with the specified numeric OID, otherwise false.

      • isStrict

        public boolean isStrict()
        Indicates whether this schema is strict.

        Attribute type queries against non-strict schema always succeed: if the requested attribute type is not found then a temporary attribute type is created automatically having the Octet String syntax and associated matching rules.

        Strict schema, on the other hand, throw an UnknownSchemaElementException whenever an attempt is made to retrieve a non-existent attribute type.

        Returns:
        true if this schema is strict.

      • toEntry

        public Entry toEntry​(Entry entry)
        Adds the definitions of all the schema elements contained in this schema to the provided subschema subentry. Any existing attributes (including schema definitions) contained in the provided entry will be preserved.
        Parameters:
        entry - The subschema subentry to which all schema definitions should be added.
        Returns:
        The updated subschema subentry.
        Throws:
        NullPointerException - If entry was null.

      • validateEntry

        public boolean validateEntry​(Entry entry,
                             SchemaValidationPolicy policy,
                             Collection<LocalizableMessage> errorMessages)
        Returns true if the provided entry is valid according to this schema and the specified schema validation policy.

        If attribute value validation is enabled then following checks will be performed:

        • checking that there is at least one value
        • checking that single-valued attributes contain only a single value
        In particular, attribute values will not be checked for conformance to their syntax since this is expected to have already been performed while adding the values to the entry.
        Parameters:
        entry - The entry to be validated.
        policy - The schema validation policy.
        errorMessages - A collection into which any schema validation warnings or error messages can be placed, or null if they should not be saved.
        Returns:
        true if an entry conforms to this schema based on the provided schema validation policy.