org.forgerock.opendj.ldap.schema

Class Schema

java.lang.Object

org.forgerock.opendj.ldap.schema.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 Summary

Modifier and Type	Method and Description
Schema	asNonStrictSchema() Returns a non-strict view of this schema.
Schema	asStrictSchema() Returns a strict view of this schema.
AttributeType	getAttributeType(String nameOrOid) Returns the attribute type for the specified name or numeric OID.
AttributeType	getAttributeType(String nameOrOid, Syntax syntax) Returns the attribute type for the specified name or numeric OID.
Collection<AttributeType>	getAttributeTypes() Returns an unmodifiable collection containing all of the attribute types contained in this schema.
static Schema	getCoreSchema() Returns the core schema.
static Schema	getDefaultSchema() Returns the default schema which should be used by this application.
DitContentRule	getDitContentRule(ObjectClass structuralClass) Returns the DIT content rule associated with the provided structural object class, or null if no rule is defined.
DitContentRule	getDitContentRule(String nameOrOid) Returns the DIT content rule with the specified name or numeric OID.
Collection<DitContentRule>	getDitContentRules() Returns an unmodifiable collection containing all of the DIT content rules contained in this schema.
DitStructureRule	getDitStructureRule(int ruleId) Returns the DIT structure rule with the specified name or numeric OID.
DitStructureRule	getDitStructureRule(String nameOrOid) Returns the DIT structure rule with the specified name or numeric OID.
Collection<DitStructureRule>	getDitStructureRules(NameForm nameForm) Returns an unmodifiable collection containing all of the DIT structure rules associated with the provided name form.
Collection<DitStructureRule>	getDitStuctureRules() Returns an unmodifiable collection containing all of the DIT structure rules contained in this schema.
static Schema	getEmptySchema() Returns the empty schema.
MatchingRule	getMatchingRule(String nameOrOid) Returns the matching rule with the specified name or numeric OID.
Collection<MatchingRule>	getMatchingRules() Returns an unmodifiable collection containing all of the matching rules contained in this schema.
MatchingRuleUse	getMatchingRuleUse(MatchingRule matchingRule) Returns the matching rule use associated with the provided matching rule, or null if no use is defined.
MatchingRuleUse	getMatchingRuleUse(String nameOrOid) Returns the matching rule use with the specified name or numeric OID.
Collection<MatchingRuleUse>	getMatchingRuleUses() Returns an unmodifiable collection containing all of the matching rule uses contained in this schema.
NameForm	getNameForm(String nameOrOid) Returns the name form with the specified name or numeric OID.
Collection<NameForm>	getNameForms() Returns an unmodifiable collection containing all of the name forms contained in this schema.
Collection<NameForm>	getNameForms(ObjectClass structuralClass) Returns an unmodifiable collection containing all of the name forms associated with the provided structural object class.
ObjectClass	getObjectClass(String nameOrOid) Returns the object class with the specified name or numeric OID.
Collection<ObjectClass>	getObjectClasses() Returns an unmodifiable collection containing all of the object classes contained in this schema.
<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.
String	getSchemaName() Returns the user-friendly name of this schema which may be used for debugging purposes.
Syntax	getSyntax(String numericOid) Returns the syntax with the specified numeric OID.
Collection<Syntax>	getSyntaxes() Returns an unmodifiable collection containing all of the syntaxes contained in this schema.
Collection<LocalizableMessage>	getWarnings() Returns an unmodifiable collection containing all of the warnings that were detected when this schema was constructed.
boolean	hasAttributeType(String nameOrOid) Indicates whether this schema contains an attribute type with the specified name or numeric OID.
boolean	hasDitContentRule(String nameOrOid) Indicates whether this schema contains a DIT content rule with the specified name or numeric OID.
boolean	hasDitStructureRule(int ruleId) Indicates whether this schema contains a DIT structure rule with the specified rule ID.
boolean	hasMatchingRule(String nameOrOid) Indicates whether this schema contains a matching rule with the specified name or numeric OID.
boolean	hasMatchingRuleUse(String nameOrOid) Indicates whether this schema contains a matching rule use with the specified name or numeric OID.
boolean	hasNameForm(String nameOrOid) Indicates whether this schema contains a name form with the specified name or numeric OID.
boolean	hasObjectClass(String nameOrOid) Indicates whether this schema contains an object class with the specified name or numeric OID.
boolean	hasSyntax(String numericOid) Indicates whether this schema contains a syntax with the specified numeric OID.
boolean	isStrict() Indicates whether this schema is strict.
static Schema	readSchema(Connection connection, Dn name) Reads the schema contained in the named subschema sub-entry.
static Single<Schema>	readSchema(LdapClientSocket socket, Dn name) Reads the schema contained in the named subschema sub-entry.
static LdapPromise<Schema>	readSchemaAsync(Connection connection, Dn name) Asynchronously reads the schema contained in the named subschema sub-entry.
static Schema	readSchemaForEntry(Connection connection, Dn name) Reads the schema contained in the subschema sub-entry which applies to the named entry.
static Single<Schema>	readSchemaForEntry(LdapClientSocket socket, Dn name) Reads the schema contained in the subschema sub-entry which applies to the named entry.
static LdapPromise<Schema>	readSchemaForEntryAsync(Connection connection, Dn name) Asynchronously reads the schema contained in the subschema sub-entry which applies to the named entry.
static void	setDefaultSchema(Schema schema) Sets the default schema which should be used by this application.
Entry	toEntry(Entry entry) Adds the definitions of all the schema elements contained in this schema to the provided subschema subentry.
String	toString()
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.
static Schema	valueOf(Entry entry) Parses the provided entry as a subschema subentry.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getCoreSchema

public static Schema getCoreSchema()

Returns the core schema. The core schema is non-strict and contains the following standard LDAP schema elements:

• RFC 4512 - Lightweight Directory Access Protocol (LDAP): Directory Information Models
• RFC 4517 - Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules
• RFC 4519 - Lightweight Directory Access Protocol (LDAP): Schema for User Applications
• RFC 4530 - Lightweight Directory Access Protocol (LDAP): entryUUID Operational Attribute
• RFC 3045 - Storing Vendor Information in the LDAP root DSE
• RFC 3112 - LDAP Authentication Password Schema

Returns:

The core schema.

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.

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.

toString

public String toString()

Overrides:

toString in class Object