Package org.forgerock.opendj.ldap.schema

Class SchemaBuilder

  • public final class SchemaBuilder
extends Object
    Schema builders should be used for incremental construction of new schemas.

    • Constructor Detail

      • SchemaBuilder

        public SchemaBuilder()
        Creates a new schema builder with no schema elements and default compatibility options.

      • SchemaBuilder

        public SchemaBuilder​(Entry entry)
        Creates a new schema builder containing all of the schema elements contained in the provided subschema subentry. Any problems encountered while parsing the entry can be retrieved using the returned schema's Schema.getWarnings() method.
        Parameters:
        entry - The subschema subentry to be parsed.
        Throws:
        NullPointerException - If entry was null.

      • SchemaBuilder

        public SchemaBuilder​(Schema schema)
        Creates a new schema builder containing all of the schema elements from the provided schema and its compatibility options.
        Parameters:
        schema - The initial contents of the schema builder.
        Throws:
        NullPointerException - If schema was null.

      • SchemaBuilder

        public SchemaBuilder​(String schemaName)
        Creates a new schema builder with no schema elements and default compatibility options.
        Parameters:
        schemaName - The user-friendly name of this schema which may be used for debugging purposes.

    • Method Detail

      • addAttributeType

        public SchemaBuilder addAttributeType​(String definition,
                                      boolean overwrite)
        Adds the provided attribute type definition to this schema builder.
        Parameters:
        definition - The attribute type definition.
        overwrite - true if any existing attribute type with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided attribute type definition could not be parsed.
        NullPointerException - If definition was null.

      • addDitContentRule

        public SchemaBuilder addDitContentRule​(String definition,
                                       boolean overwrite)
        Adds the provided DIT content rule definition to this schema builder.
        Parameters:
        definition - The DIT content rule definition.
        overwrite - true if any existing DIT content rule with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided DIT content rule definition could not be parsed.
        NullPointerException - If definition was null.

      • addDitStructureRule

        public SchemaBuilder addDitStructureRule​(String definition,
                                         boolean overwrite)
        Adds the provided DIT structure rule definition to this schema builder.
        Parameters:
        definition - The DIT structure rule definition.
        overwrite - true if any existing DIT structure rule with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided DIT structure rule definition could not be parsed.
        NullPointerException - If definition was null.

      • addEnumerationSyntax

        public SchemaBuilder addEnumerationSyntax​(String oid,
                                          String description,
                                          boolean overwrite,
                                          String... enumerations)
        Adds the provided enumeration syntax definition to this schema builder.
        Parameters:
        oid - The OID of the enumeration syntax definition.
        description - The description of the enumeration syntax definition.
        overwrite - true if any existing syntax with the same OID should be overwritten.
        enumerations - The range of values which attribute values must match in order to be valid.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.

      • addMatchingRule

        public SchemaBuilder addMatchingRule​(String definition,
                                     boolean overwrite)
        Adds the provided matching rule definition to this schema builder.
        Parameters:
        definition - The matching rule definition.
        overwrite - true if any existing matching rule with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided matching rule definition could not be parsed.
        NullPointerException - If definition was null.

      • addMatchingRuleUse

        public SchemaBuilder addMatchingRuleUse​(String definition,
                                        boolean overwrite)
        Adds the provided matching rule use definition to this schema builder.
        Parameters:
        definition - The matching rule use definition.
        overwrite - true if any existing matching rule use with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided matching rule use definition could not be parsed.
        NullPointerException - If definition was null.

      • buildAttributeType

        public AttributeType.Builder buildAttributeType​(String oid)
        Returns a builder which can be used for incrementally constructing a new attribute type before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildAttributeType("attributetype-oid").name("attribute type name").addToSchema();
        Parameters:
        oid - The OID of the attribute type definition.
        Returns:
        A builder to continue building the AttributeType.

      • buildDitStructureRule

        public DitStructureRule.Builder buildDitStructureRule​(int ruleId)
        Returns a builder which can be used for incrementally constructing a new DIT structure rule before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 final int myRuleID = ...;
 builder.buildDITStructureRule(myRuleID).name("DIT structure rule name").addToSchema();
        Parameters:
        ruleId - The ID of the DIT structure rule.
        Returns:
        A builder to continue building the DITStructureRule.

      • buildMatchingRule

        public MatchingRule.Builder buildMatchingRule​(String oid)
        Returns a builder which can be used for incrementally constructing a new matching rule before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildMatchingRule("matchingrule-oid").name("matching rule name").addToSchema();
        Parameters:
        oid - The OID of the matching rule definition.
        Returns:
        A builder to continue building the MatchingRule.

      • buildMatchingRuleUse

        public MatchingRuleUse.Builder buildMatchingRuleUse​(String oid)
        Returns a builder which can be used for incrementally constructing a new matching rule use before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildMatchingRuleUse("matchingrule-oid")
        .name("matching rule use name")
        .addToSchema();
        Parameters:
        oid - The OID of the matching rule definition.
        Returns:
        A builder to continue building the MatchingRuleUse.

      • addNameForm

        public SchemaBuilder addNameForm​(String definition,
                                 boolean overwrite)
        Adds the provided name form definition to this schema builder.
        Parameters:
        definition - The name form definition.
        overwrite - true if any existing name form with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided name form definition could not be parsed.
        NullPointerException - If definition was null.

      • buildDitContentRule

        public DitContentRule.Builder buildDitContentRule​(String structuralClassOid)
        Returns a builder which can be used for incrementally constructing a new DIT content rule before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildDITContentRule("structuralobjectclass-oid").name("DIT content rule name").addToSchema();
        Parameters:
        structuralClassOid - The OID of the structural objectclass for the DIT content rule to build.
        Returns:
        A builder to continue building the DITContentRule.

      • buildNameForm

        public NameForm.Builder buildNameForm​(String oid)
        Returns a builder which can be used for incrementally constructing a new name form before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildNameForm("1.2.3.4").name("myNameform").addToSchema();
        Parameters:
        oid - The OID of the name form definition.
        Returns:
        A builder to continue building the NameForm.

      • buildObjectClass

        public ObjectClass.Builder buildObjectClass​(String oid)
        Returns a builder which can be used for incrementally constructing a new object class before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildObjectClass("objectclass-oid").name("object class name").addToSchema();
        Parameters:
        oid - The OID of the object class definition.
        Returns:
        A builder to continue building the ObjectClass.

      • buildSyntax

        public Syntax.Builder buildSyntax​(String oid)
        Returns a builder which can be used for incrementally constructing a new syntax before adding it to the schema. Example usage: 
         SchemaBuilder builder = ...;
 builder.buildSyntax("1.2.3.4").addToSchema();
        Parameters:
        oid - The OID of the syntax definition.
        Returns:
        A builder to continue building the syntax.

      • buildAttributeType

        public AttributeType.Builder buildAttributeType​(AttributeType attributeType)
        Returns an attribute type builder whose fields are initialized to the values of the provided attribute type. This method should be used when duplicating attribute types from external schemas or when modifying existing attribute types.
        Parameters:
        attributeType - The attribute type source.
        Returns:
        A builder to continue building the AttributeType.

      • buildDitContentRule

        public DitContentRule.Builder buildDitContentRule​(DitContentRule contentRule)
        Returns a DIT content rule builder whose fields are initialized to the values of the provided DIT content rule. This method should be used when duplicating DIT content rules from external schemas or when modifying existing DIT content rules.
        Parameters:
        contentRule - The DIT content rule source.
        Returns:
        A builder to continue building the DITContentRule.

      • buildDitStructureRule

        public DitStructureRule.Builder buildDitStructureRule​(DitStructureRule structureRule)
        Returns an DIT structure rule builder whose fields are initialized to the values of the provided rule. This method should be used when duplicating structure rules from external schemas or when modifying existing structure rules.
        Parameters:
        structureRule - The DIT structure rule source.
        Returns:
        A builder to continue building the DITStructureRule.

      • buildMatchingRule

        public MatchingRule.Builder buildMatchingRule​(MatchingRule matchingRule)
        Returns a matching rule builder whose fields are initialized to the values of the provided matching rule. This method should be used when duplicating matching rules from external schemas or when modifying existing matching rules.
        Parameters:
        matchingRule - The matching rule source.
        Returns:
        A builder to continue building the MatchingRule.

      • buildMatchingRuleUse

        public MatchingRuleUse.Builder buildMatchingRuleUse​(MatchingRuleUse matchingRuleUse)
        Returns a matching rule use builder whose fields are initialized to the values of the provided matching rule use object. This method should be used when duplicating matching rule uses from external schemas or when modifying existing matching rule uses.
        Parameters:
        matchingRuleUse - The matching rule use source.
        Returns:
        A builder to continue building the MatchingRuleUse.

      • buildNameForm

        public NameForm.Builder buildNameForm​(NameForm nameForm)
        Returns a name form builder whose fields are initialized to the values of the provided name form. This method should be used when duplicating name forms from external schemas or when modifying existing names forms.
        Parameters:
        nameForm - The name form source.
        Returns:
        A builder to continue building the NameForm.

      • buildObjectClass

        public ObjectClass.Builder buildObjectClass​(ObjectClass objectClass)
        Returns an object class builder whose fields are initialized to the values of the provided object class. This method should be used when duplicating object classes from external schemas or when modifying existing object classes.
        Parameters:
        objectClass - The object class source.
        Returns:
        A builder to continue building the ObjectClass.

      • buildSyntax

        public Syntax.Builder buildSyntax​(Syntax syntax)
        Returns a syntax builder whose fields are initialized to the values of the provided syntax. This method should be used when duplicating syntaxes from external schemas or when modifying existing syntaxes.
        Parameters:
        syntax - The syntax source.
        Returns:
        A builder to continue building the Syntax.

      • addObjectClass

        public SchemaBuilder addObjectClass​(String definition,
                                    boolean overwrite)
        Adds the provided object class definition to this schema builder.
        Parameters:
        definition - The object class definition.
        overwrite - true if any existing object class with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided object class definition could not be parsed.
        NullPointerException - If definition was null.

      • addPatternSyntax

        public SchemaBuilder addPatternSyntax​(String oid,
                                      String description,
                                      Pattern pattern,
                                      boolean overwrite)
        Adds the provided pattern syntax definition to this schema builder.
        Parameters:
        oid - The OID of the pattern syntax definition.
        description - The description of the pattern syntax definition.
        pattern - The regular expression pattern which attribute values must match in order to be valid.
        overwrite - true if any existing syntax with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.

      • addSchema

        public SchemaBuilder addSchema​(Connection connection,
                               Dn name,
                               boolean overwrite)
                        throws LdapException
        Reads the schema elements contained in the named subschema sub-entry and adds them to this schema builder.

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

        Parameters:
        connection - A connection to the Directory Server whose schema is to be read.
        name - The distinguished name of the subschema sub-entry.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A reference to this schema builder.
        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 isClosed() == true.
        NullPointerException - If the connection or name was null.

      • addSchema

        public SchemaBuilder addSchema​(Entry entry,
                               boolean overwrite)
        Adds all of the schema elements contained in the provided subschema subentry to this schema builder. Any problems encountered while parsing the entry can be retrieved using the returned schema's Schema.getWarnings() method.
        Parameters:
        entry - The subschema subentry to be parsed.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        NullPointerException - If entry was null.

      • addSchema

        public SchemaBuilder addSchema​(Entry entry,
                               boolean overwrite,
                               SchemaBuilder.SchemaBuilderHook hook)
        Adds all of the schema elements contained in the provided subschema subentry to this schema builder. Any problems encountered while parsing the entry can be retrieved using the returned schema's Schema.getWarnings() method.
        Parameters:
        entry - The subschema subentry to be parsed.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        hook - Allows to perform modifications on element's builders before adding the result to this schema builder.
        Returns:
        A reference to this schema builder.
        Throws:
        NullPointerException - If entry was null.

      • addSchema

        public SchemaBuilder addSchema​(Schema schema,
                               boolean overwrite)
        Adds all of the schema elements in the provided schema to this schema builder.
        Parameters:
        schema - The schema to be copied into this schema builder.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and conflicting schema elements were found.
        NullPointerException - If schema was null.

      • addSchemaAsync

        public LdapPromise<SchemaBuilder> addSchemaAsync​(Connection connection,
                                                 Dn name,
                                                 boolean overwrite)
        Asynchronously reads the schema elements contained in the named subschema sub-entry and adds them to this schema builder.

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

        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.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A promise representing the updated schema builder.
        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.

      • addSchema

        public Single<SchemaBuilder> addSchema​(LdapClientSocket socket,
                                       Dn name,
                                       boolean overwrite)
        Reads the schema elements contained in the named subschema sub-entry and adds them to this schema builder.

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

        Note that the schema elements 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.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A Single wrapping the updated schema builder.
        Throws:
        UnsupportedOperationException - If the connection 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.

      • addSchemaForEntry

        public SchemaBuilder addSchemaForEntry​(Connection connection,
                                       Dn name,
                                       boolean overwrite)
                                throws LdapException
        Reads the schema elements contained in the subschema sub-entry which applies to the named entry and adds them to this schema builder.

        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 addSchema(Connection, Dn, boolean) 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.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A reference to this schema builder.
        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.

      • addSchemaForEntryAsync

        public LdapPromise<SchemaBuilder> addSchemaForEntryAsync​(Connection connection,
                                                         Dn name,
                                                         boolean overwrite)
        Asynchronously reads the schema elements contained in the subschema sub-entry which applies to the named entry and adds them to this schema builder.

        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 addSchemaAsync(Connection, Dn, boolean) 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.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A promise representing the updated schema builder.
        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.

      • addSchemaForEntry

        public Single<SchemaBuilder> addSchemaForEntry​(LdapClientSocket socket,
                                               Dn name,
                                               boolean overwrite)
        Reads the schema elements contained in the subschema sub-entry which applies to the named entry and adds them to this schema builder.

        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 addSchema(LdapClientSocket, Dn, boolean) to read the schema.

        Note that the request will only be sent 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.
        overwrite - true if existing schema elements with the same conflicting OIDs should be overwritten.
        Returns:
        A Single representing the updated schema builder.
        Throws:
        UnsupportedOperationException - If the connection 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.

      • addSubstitutionSyntax

        public SchemaBuilder addSubstitutionSyntax​(String oid,
                                           String description,
                                           String substituteSyntax,
                                           boolean overwrite)
        Adds the provided substitution syntax definition to this schema builder.
        Parameters:
        oid - The OID of the substitution syntax definition.
        description - The description of the substitution syntax definition.
        substituteSyntax - The OID of the syntax whose implementation should be substituted.
        overwrite - true if any existing syntax with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.

      • addSyntax

        public SchemaBuilder addSyntax​(String definition,
                               boolean overwrite)
        Adds the provided syntax definition to this schema builder.
        Parameters:
        definition - The syntax definition.
        overwrite - true if any existing syntax with the same OID should be overwritten.
        Returns:
        A reference to this schema builder.
        Throws:
        ConflictingSchemaElementException - If overwrite was false and a conflicting schema element was found.
        LocalizedIllegalArgumentException - If the provided syntax definition could not be parsed.
        NullPointerException - If definition was null.

      • removeAttributeType

        public boolean removeAttributeType​(String nameOrOid)
        Removes the named attribute type from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the attribute type to be removed.
        Returns:
        true if the attribute type was found.

      • removeDitContentRule

        public boolean removeDitContentRule​(String nameOrOid)
        Removes the named DIT content rule from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the DIT content rule to be removed.
        Returns:
        true if the DIT content rule was found.

      • removeDitStructureRule

        public boolean removeDitStructureRule​(int ruleId)
        Removes the specified DIT structure rule from this schema builder.
        Parameters:
        ruleId - The ID of the DIT structure rule to be removed.
        Returns:
        true if the DIT structure rule was found.

      • removeMatchingRule

        public boolean removeMatchingRule​(String nameOrOid)
        Removes the named matching rule from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the matching rule to be removed.
        Returns:
        true if the matching rule was found.

      • removeMatchingRuleUse

        public boolean removeMatchingRuleUse​(String nameOrOid)
        Removes the named matching rule use from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the matching rule use to be removed.
        Returns:
        true if the matching rule use was found.

      • removeNameForm

        public boolean removeNameForm​(String nameOrOid)
        Removes the named name form from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the name form to be removed.
        Returns:
        true if the name form was found.

      • removeObjectClass

        public boolean removeObjectClass​(String nameOrOid)
        Removes the named object class from this schema builder.
        Parameters:
        nameOrOid - The name or OID of the object class to be removed.
        Returns:
        true if the object class was found.

      • removeSyntax

        public boolean removeSyntax​(String numericOid)
        Removes the named syntax from this schema builder.
        Parameters:
        numericOid - The name of the syntax to be removed.
        Returns:
        true if the syntax was found.

      • setOption

        public <T> SchemaBuilder setOption​(Option<T> option,
                                   T value)
        Sets a schema option overriding any previous values for the option.
        Type Parameters:
        T - The option type.
        Parameters:
        option - Option with which the specified value is to be associated.
        value - Value to be associated with the specified option.
        Returns:
        A reference to this schema builder.
        Throws:
        UnsupportedOperationException - If the schema builder options are read only.

      • toSchema

        public Schema toSchema()
        Returns a strict Schema containing all of the schema elements contained in this schema builder as well as the same set of schema compatibility options.

        This method does not alter the contents of this schema builder.

        Returns:
        A Schema containing all of the schema elements contained in this schema builder as well as the same set of schema compatibility options