Package com.orchestranetworks.schema

# Interface SchemaNode

public interface SchemaNode
Represents an element declaration in the resolved data model.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Object`
  `createNewOccurrence()`
  Creates a new Java object that complies to this node definition.
  `String`
  `displayOccurrence(Object aValue, boolean useLabels, ValueContext aValueContext, Locale aLocale)`
  Returns a user-friendly representation of the specified value.
  `Object`
  `executeRead(Object aContainerOccurrence)`
  Reads the specified occurrence of the parent node and returns the value corresponding to this node.
  `void`
  `executeWrite(Object aValue, Object aContainerOccurrence)`
  Modifies the specified occurrence of the parent node by setting the specified value.
  `String`
  `formatToXsString(Object aValue)`
  Returns the string that corresponds to the specified value.
  `AccessPermission`
  `getAccessMode()`
  Returns the static access mode of the current node.
  `AssociationLink`
  `getAssociationLink()`
  Returns the information for an association.
  `BusinessObjectModel`
  `getBusinessObjectModel()`
  Returns the business object model associated to this table node.
  `BusinessObjectModel`
  `getBusinessObjectModel(Adaptation aDataset, Session aSession)`
  Returns the business object model associated to this node if it is a table node.
  `String`
  `getCategory()`
  Returns the category that is defined in data model (attribute `osd:category`); returns `null` if no category is specified on the current node, nor on its ancestors.
  `Object`
  `getDefaultValue()`
  Returns the default value for the node that is defined in data model (attribute `xs:default`), or `null` if no value is specified.
  `SchemaNodeDefaultView`
  `getDefaultViewProperties()`
  Returns the default view properties for this node, as defined in the data model (element `osd:defaultView` under the element `xs:annotation/xs:appinfo`).
  `String`
  `getDescription(Session aSession)`
  Returns the localized description of this node in the context of a user session.
  `String`
  `getDescription(Locale aLocale)`
  Returns the localized description of this node.
  `<T> List<T>`
  `getEnumerationList(ValueContext aValueContext)`
  If the data model specifies an enumeration, returns the values that this node may take on.
  `<T> Nomenclature<T>`
  `getEnumerationNomenclature(ValueContext aValueContext)`
  Returns the underlying `Nomenclature`, if found by searching through facets.
  `SchemaFacetEnumeration`
  `getFacetEnumeration()`
  Returns the first `enumeration` facet declared on this node.
  `SchemaFacetExcludeSegment`
  `getFacetExcludeSegment()`
  Returns the first `excludeSegment` facet declared on this node.
  `SchemaFacetExcludeValue`
  `getFacetExcludeValue()`
  Returns the first `excludeValue` facet declared on this node.
  `SchemaFacetFractionDigits`
  `getFacetFractionDigits()`
  Returns the first `fractionDigits` facet declared on this node.
  `SchemaFacetLength`
  `getFacetLength()`
  Returns the first `length` facet declared on this node.
  `SchemaFacetBoundaryMaxExclusive`
  `getFacetMaxBoundaryExclusive()`
  Returns the first `maxExclusive` facet declared on this node.
  `SchemaFacetBoundaryMaxInclusive`
  `getFacetMaxBoundaryInclusive()`
  Returns the first `maxInclusive` facet declared on this node.
  `SchemaFacetMaxLength`
  `getFacetMaxLength()`
  Returns the first `maxlength` facet declared on this node.
  `SchemaFacetBoundaryMinExclusive`
  `getFacetMinBoundaryExclusive()`
  Returns the first `minExclusive` facet declared on this node.
  `SchemaFacetBoundaryMinInclusive`
  `getFacetMinBoundaryInclusive()`
  Returns the first `minInclusive` facet declared on this node.
  `SchemaFacetMinLength`
  `getFacetMinLength()`
  Returns the first `minLength` facet declared on this node.
  `SchemaFacetOnMandatoryField`
  `getFacetOnMandatoryField()`
  Returns the facet corresponding to the cardinality constraint related to a mandatory field (declares both `minOccurs=1` and `maxOccurs=1`).
  `SchemaFacetTableRef`
  `getFacetOnTableReference()`
  Returns the `osd:tableRef` facet (foreign key constraint) declared on this node.
  `SchemaFacetOResource`
  `getFacetOResource()`
  Returns the `OResource` facet held by this node.
  `SchemaFacetPattern`
  `getFacetPattern()`
  Returns the first `pattern` facet declared on this node.
  `Iterator<SchemaFacet>`
  `getFacets()`
  Returns an iterator over the `facets` defined by this data model node.
  `SchemaFacetTotalDigits`
  `getFacetTotalDigits()`
  Returns the first `totalDigits` facet declared on this node.
  `SchemaNodeInformation`
  `getInformation()`
  Returns the additional information (element `osd:information`) for this node, as defined in the data model.
  `SchemaInheritanceProperties`
  `getInheritanceProperties()`
  Returns the inheritance properties (element `osd:inheritance`) for this node, as defined in the data model.
  `Class<?>`
  `getJavaBeanClass()`
  Returns the specific Java Bean `class` defined on this data model node (attribute `osd:class`) or `null` if no Java Bean has been defined and/or this node is not terminal.
  `String`
  `getLabel(Session aSession)`
  Returns the label of this node for the specified session.
  `String`
  `getLabel(Locale aLocale)`
  Returns the localized label of this node.
  `UserMessage`
  `getMandatoryUserMessage()`
  Returns the mandatory error message (defined by the data model element `osd:mandatoryErrorMessage`).
  `int`
  `getMaxOccurs()`
  Returns the value of `xs:maxOccurs`.
  `int`
  `getMinOccurs()`
  Returns the value of `xs:minOccurs`.
  `SchemaNode`
  `getNode(Path aPath)`
  Returns the node at the specified path, or `null` if no node exists at the specified path.
  `SchemaNode`
  `getNode(Path aPath, boolean tolerantRead, boolean absolutePathBeginsAtRecordRoot)`
  Returns the node at the specified path, or `null` if the node does not exist and `isTolerantRead` is `true`.
  `SchemaNode[]`
  `getNodeChildren()`
  Returns the data model nodes defined directly under this node.
  `SchemaNode[]`
  `getNodeChildren(boolean includeMetadata)`
  Returns the data model nodes defined directly under this node.
  `Class<?>`
  `getOccurrencesJavaClass()`
  Returns the default `Class` of the Java records of this data model node, `null` if this node is above a terminal node.
  `SchemaNode`
  `getParent()`
  Returns the parent node of this node.
  `Path`
  `getPathInAdaptation()`
  Returns the local absolute path.
  `Path`
  `getPathInSchema()`
  Returns the absolute path of this node in the data model.
  `SchemaNodeExplicitRelationship`
  `getRelationship()`
  Returns the information for the relationship defined by this node.
  `SchemaNodeRelationships`
  `getRelationships()`
  Returns all the relationships defined by this node.
  `SchemaNodeRelationships`
  `getRelationships(Adaptation aDataset, Session aSession)`
  Returns the relationships defined by this node.
  `SchemaNodeRelationships`
  `getRelationships(Adaptation aDataset, Session aSession, boolean includeMetadata)`
  Returns the relationships defined by this node.
  `Locale`
  `getSchemaDefaultLocale()`
  Deprecated.
  Since 5.9.0 it is not possible to define locales for a module anymore.
  `SchemaDefaultTableView`
  `getSchemaDefaultTableView()`
  Returns the default table view properties for this node, as defined in the data model.
  `SchemaLinkedField`
  `getSchemaLinkedField()`
  Returns the information for a linked field.
  `List<Locale>`
  `getSchemaLocales()`
  Deprecated.
  Since 5.9.0 it is not possible to define locales for a module anymore.
  `SchemaLocation`
  `getSchemaLocation()`
  Returns the location of the data model that defines this node.
  `SelectionLink`
  `getSelectionLink()`
  Returns the information for a selection link.
  `String`
  `getTableEntityName()`
  Returns the entity name of this node if this node is a table node.
  `SchemaNode`
  `getTableNode()`
  If this node is in a table record, returns the node of the containing table, which defines `osd:table`.
  `SchemaNode`
  `getTableOccurrenceRootNode()`
  If this node is a table node (see method `isTableNode()`), returns the root node of the record structure.
  `SchemaNode[]`
  `getTablePrimaryKeyNodes()`
  Returns the primary key that is defined in the data model if this node is a table node.
  `Object[]`
  `getTablePrimaryKeyValues(PrimaryKey aPrimaryKey)`
  If this node is a table node, decomposes the specified primary key object into the primary key field values in the referenced table.
  `Object[]`
  `getTablePrimaryKeyValues(String aTableRefValue)`
  If this node is a table node, decomposes the specified `osd:tableRef` value into the primary key field values in the referenced table.
  `List<UniquenessConstraint>`
  `getUniquenessConstraints()`
  Returns the `uniqueness constraints` applied on this table using the property `xs:unique`.
  `SchemaTypeName`
  `getXsTypeName()`
  Returns the type name of this node, or `null` if this node is associated with an anonymous type definition.
  `boolean`
  `isAncestorMultiOccurrenced()`
  Returns `true` if an ancestor of this node is a list.
  `boolean`
  `isAncestorOrSelfMultiOccurrenced()`
  Returns `true` if this node or one of its ancestors is a list.
  `boolean`
  `isAssociationNode()`
  Returns `true` if this node is an association.
  `boolean`
  `isAutoIncrement()`
  Returns `true` if this node defines an auto-increment.
  `boolean`
  `isCheckNullInput()`
  Returns the value of the property`osd:checkNullInput`.
  `boolean`
  `isComplex()`
  Returns `true` if this node is a complex element declaration.
  `boolean`
  `isHistoryDisabled()`
  Specifies if the history is disabled for this node.
  `boolean`
  `isLinkedNode()`
  Returns `true` if this node is a linked node.
  `boolean`
  `isSelectNode()`
  Returns `true` if this node is a selection link.
  `boolean`
  `isTableNode()`
  Returns `true` if this node is a table node.
  `boolean`
  `isTableOccurrenceNode()`
  Returns `true` if this node is in a table record.
  `boolean`
  `isTerminalValue()`
  Returns `true` if this node is terminal.
  `boolean`
  `isTerminalValueComputed()`
  Returns `true` if this node is a terminal node whose value is not directly stored in EBX® repository.
  `boolean`
  `isTerminalValueDescendant()`
  Returns `true` if this node is the descendant of a terminal value node.
  `boolean`
  `isValidationDisabled()`
  Returns `true` if the validation is disabled on this node.
  `boolean`
  `isValueEqual(Object aFirstValue, Object aSecondValue)`
  Returns `true` if the specified values are equal, according to the underlying XML Schema type.
  `boolean`
  `isValueFunction()`
  Returns `true` if this node holds a function.
  `boolean`
  `isValueLessOrEqualTo(Object aFirstValue, Object aSecondValue)`
  Returns `true` if first value is less than or equal to the second value, according to the underlying XML Schema type.
  `boolean`
  `isValueStrictlyLessThan(Object aFirstValue, Object aSecondValue)`
  Returns `true` if the first value is strictly less than the second value, according to the underlying XML Schema type.
  `Object`
  `parseXsString(String aString)`
  Returns the value that corresponds to the specified string.

- ## Method Details

  - ### getMinOccurs

    int getMinOccurs()
    Returns the value of `xs:minOccurs`.

  - ### getMaxOccurs

    int getMaxOccurs()
    Returns the value of `xs:maxOccurs`.

  - ### isCheckNullInput

    boolean isCheckNullInput()
    Returns the value of the property`osd:checkNullInput`.

  - ### getPathInAdaptation

    Path getPathInAdaptation()
    Returns the local absolute path.

    In a table record, the local absolute path is the path that begins at the table root node (non-inclusive); otherwise, it is the path that starts at the dataset root node (inclusive). In the latter case, the path is the same as the one returned by `getPathInSchema()`.

    See Also:
      - `getPathInSchema()`

  - ### getPathInSchema

    Path getPathInSchema()
    Returns the absolute path of this node in the data model.
    See Also:
      - `getPathInAdaptation()`

  - ### isComplex

    boolean isComplex()
    Returns `true` if this node is a complex element declaration.

  - ### isValueEqual

    boolean isValueEqual(Object aFirstValue, Object aSecondValue)
    Returns `true` if the specified values are equal, according to the underlying XML Schema type.

    For example, if the data model type is `xs:date`, both specified values must instances of `Date`. Also, equality checking for `xs:date` does not take time into account, due to the Java equality checking for `Date`. In contrast, equality checking for the type `xs:dateTime` in the data model would compare time.

    Throws:
      `ClassCastException` - if a specified value is not an instance of the underlying type.

  - ### isValueLessOrEqualTo

    boolean isValueLessOrEqualTo(Object aFirstValue, Object aSecondValue)
    Returns `true` if first value is less than or equal to the second value, according to the underlying XML Schema type.
    Throws:
      `UnsupportedOperationException` - if underlying type does not support comparison.
      `ClassCastException` - if a specified value is not an instance of underlying type.

  - ### isValueStrictlyLessThan

    boolean isValueStrictlyLessThan(Object aFirstValue, Object aSecondValue)
    Returns `true` if the first value is strictly less than the second value, according to the underlying XML Schema type.
    Throws:
      `UnsupportedOperationException` - if the underlying type does not support comparison.
      `ClassCastException` - if a specified value is not an instance of the underlying type.

  - ### isTerminalValue

    boolean isTerminalValue()
    Returns `true` if this node is terminal.

    A node is terminal when:

    - it is a field (a node of a simple type) that is not the descendant of a terminal complex (see `isTerminalValueDescendant()`);
    - it is a group (a node of a complex type) that is not the descendant of a terminal complex, and the data model specifies any of the following:
      1. `maxOccurs > 1` (either an aggregated list or a `osd:table`);
      2. a value function, `osd:function` (see Computed Values);
      3. an access property, `osd:access` (see Access Properties).

    Note: if inheritance is enabled, a terminal node value can be inherited.

    See Also:
      - `isTerminalValueDescendant()`

  - ### isTerminalValueDescendant

    boolean isTerminalValueDescendant()
    Returns `true` if this node is the descendant of a terminal value node. This implies that the parent node is of a complex type and it is itself either terminal or a descendant of a terminal node.
    See Also:
      - `isTerminalValue()`

  - ### isTerminalValueComputed

    boolean isTerminalValueComputed()
    Returns `true` if this node is a terminal node whose value is not directly stored in EBX® repository.

    This is the case for a node declaring an `osd:function`, `osd:association` and `osd:table`.

  - ### isAutoIncrement

    boolean isAutoIncrement()
    Returns `true` if this node defines an auto-increment.

    An auto-incremented node is specified in the data model using the the `osd:autoIncrement` element.

  - ### isSelectNode

    boolean isSelectNode()
    Returns `true` if this node is a selection link.

    A select node is specified in the data model using the `osd:select` element.

    See Also:
      - `getSelectionLink()`

  - ### getSelectionLink

    SelectionLink getSelectionLink()
    Returns the information for a selection link. Returns `null` if the node has no selection link defined.
    See Also:
      - `isSelectNode()`

  - ### isAssociationNode

    boolean isAssociationNode()
    Returns `true` if this node is an association.

    An association node is specified in the data model using the `osd:association` element.

    Since:
      5.5.0

  - ### getAssociationLink

    AssociationLink getAssociationLink()
    Returns the information for an association. Returns `null` if the node is not an association.
    Since:
      5.5.0
    See Also:
      - `isAssociationNode()`

  - ### isLinkedNode

    boolean isLinkedNode()
    Returns `true` if this node is a linked node.

    A linked node is specified in the data model using the `osd:function linkedField="aPath"` element.

    Since:
      6.0
    See Also:
      - `getSchemaLinkedField()`

  - ### getSchemaLinkedField

    SchemaLinkedField getSchemaLinkedField()
    Returns the information for a linked field.

    Returns `null` if this node is does not define the element `osd:function linkedField="aPath"`.

    Since:
      6.0
    See Also:
      - `isLinkedNode()`

  - ### getRelationship

    SchemaNodeExplicitRelationship getRelationship()
    Returns the information for the relationship defined by this node. Returns `null` if the node has no relationship defined.
    See Also:
      - `getFacetOnTableReference()`
      - `getSelectionLink()`
      - `getAssociationLink()`

  - ### getRelationships

    SchemaNodeRelationships getRelationships(Adaptation aDataset, Session aSession)
    Returns the relationships defined by this node.

    This method is equivalent to:

    > `SchemaNode.getRelationships(Adaptation, Session, false);`

    Since:
      5.7.1
    See Also:
      - `getRelationships()`
      - `getRelationships(Adaptation, Session, boolean)`

  - ### getRelationships

    SchemaNodeRelationships getRelationships(Adaptation aDataset, Session aSession, boolean includeMetadata)
    Returns the relationships defined by this node.

    The relationships returned by this method are filtered according to the permissions defined for the end-user associated to the specified session and in the context of the given dataset that is an instance of the data model containing this node.

    * @param includeMetadata if `true` this method returns also the relationships of the metadata fields if this node is a table node.
    Throws:
      `IllegalArgumentException` - if the specified `Adaptation` is `null`.
      `IllegalStateException` - if the specified `Adaptation` is not a dataset.
      `IllegalStateException` - if the specified `Adaptation` has severe error.
      `IllegalStateException` - if the specified dataset is not an instance of the data model containing this node.
      `IllegalArgumentException` - is the specified `Session` is `null`.
    Since:
      6.1
    See Also:
      - `getRelationships()`
      - `Adaptation.hasSevereError()`

  - ### getRelationships

    SchemaNodeRelationships getRelationships()
    Returns all the relationships defined by this node.

    The method `getRelationships(Adaptation, Session)` can be used if the relationships held by this node must be filtered according to the permissions defined for a specific end-user, in the context of a dataset which is an instance of the data model containing this node.

    Since:
      5.7.1
    See Also:
      - `getRelationships(Adaptation, Session)`

  - ### getBusinessObjectModel

    BusinessObjectModel getBusinessObjectModel(Adaptation aDataset, Session aSession)
    Returns the business object model associated to this node if it is a table node.

    Permissions are resolved using this method. As a consequence, this method returns `null` if the main table of the related business object model associated cannot be viewed by the end-user associated with the given session and in the context of the specified dataset. The dimensions of the business object model are filtered as well. That is, a dimension (including its child dimensions) are not visible if the related relationship cannot be viewed by the end-user associated with the given session and in the context of the specified dataset. See `SchemaNodeRelationships.getExplicitRelationships()` for more information about the resolution of the permissions.

    Throws:
      `IllegalArgumentException` - if the specified `SchemaNode` is not a table node.
      `IllegalArgumentException` - if the specified `Adaptation` is `null`.
      `IllegalStateException` - if the specified `Adaptation` is not a dataset.
      `IllegalStateException` - if the specified `Adaptation` has a severe error.
      `IllegalStateException` - if the specified dataset is not an instance of the data model containing this node.
      `IllegalArgumentException` - if the specified `Session` is `null`.

  - ### getBusinessObjectModel

    BusinessObjectModel getBusinessObjectModel()
    Returns the business object model associated to this table node.

    The method `getBusinessObjectModel(Adaptation, Session)` can be used if the business object model associated to this node must be filtered according to the permissions defined for a specific end-user, in the context of a dataset which is an instance of the data model containing this node.

    Throws:
      `IllegalArgumentException` - if the current node is not a table node.
    See Also:
      - `getBusinessObjectModel(Adaptation, Session)`

  - ### getTableNode

    SchemaNode getTableNode()
    If this node is in a table record, returns the node of the containing table, which defines `osd:table`. Returns either the table node containing the `osd:table` declaration, or `null` if this node is not inside a table.
    See Also:
      - `isTableNode()`
      - `getTableOccurrenceRootNode()`

  - ### isTableNode

    boolean isTableNode()
    Returns `true` if this node is a table node.

    A table node is specified in the data model using the element `osd:table` (see Table definition).

    See Also:
      - `getTableOccurrenceRootNode()`

  - ### getTablePrimaryKeyNodes

    SchemaNode[] getTablePrimaryKeyNodes()
    Returns the primary key that is defined in the data model if this node is a table node. Returns the nodes of the primary key that are defined in the element `osd:table/primaryKeys` (in their declared order), or `null` if this node is not a table node.
    See Also:
      - `getTableNode()`
      - `isTableNode()`
      - `getTableOccurrenceRootNode()`
      - `AdaptationTable.computePrimaryKey(Object[])`
      - `AdaptationTable.computePrimaryKey(Adaptation)`
      - `AdaptationTable.computePrimaryKey(ValueContext)`

  - ### getTablePrimaryKeyValues

    Object[] getTablePrimaryKeyValues(String aTableRefValue) throws InvalidPrimaryKeyException, IllegalArgumentException
    If this node is a table node, decomposes the specified `osd:tableRef` value into the primary key field values in the referenced table.

    The following table gives some examples of decomposition:

    Key fields | String representation (`aTableRefValue`) | returns
    --- | --- | ---
    (xs:string) | "abc" | "abc"
    (xs:int) | "123" | [Integer(123)]
    (xs:int) | "" | throws an `InvalidPrimaryKeyException`.
    (xs:int) | "aa" | throws an `InvalidPrimaryKeyException`.
    (xs:int | xs:string) | "123|abc" | [Integer(123), "abc"]
    (xs:int | xs:string) | "123|abc|abc" | [Integer(123), "abc|abc"] (the second field is itself a foreign key, the second value can hence be itself decomposed)
    (xs:int | xs:string) | "aa|aaa" (invalid integer field) | throws an `InvalidPrimaryKeyException`.
    (xs:int | xs:string) | "|aaa" | throws an `InvalidPrimaryKeyException`.
    (xs:int | xs:string) | "" (empty string) | throws an `InvalidPrimaryKeyException`.
    (xs:int | xs:string) | "aaa" | Invalid, throws an `InvalidPrimaryKeyException`.

    Parameters:
      `aTableRefValue` - a string value that conforms to the primary key syntax.
    Returns:
      an array in which each element is extracted from the specified value and corresponds to the field at the same position in the primary key field array.
    Throws:
      `InvalidPrimaryKeyException` - if the specified value does not have the expected primary key syntax, or if a field value is `null`.
      `IllegalStateException` - if this node is not a table node.
      `IllegalArgumentException` - if the specified value is `null`.
    Since:
      5.2.3
    See Also:
      - `getTablePrimaryKeyNodes()`
      - PrimaryKey syntax
      - `SchemaFacetTableRef.getTablePrimaryKeyValues(String)`

  - ### getTablePrimaryKeyValues

    Object[] getTablePrimaryKeyValues(PrimaryKey aPrimaryKey) throws InvalidPrimaryKeyException, IllegalArgumentException
    If this node is a table node, decomposes the specified primary key object into the primary key field values in the referenced table.

    This method is equivalent to:

    > `this.getTablePrimaryKeyValues(aPrimaryKey.format());`

    Throws:
      `InvalidPrimaryKeyException`
      `IllegalArgumentException`
    See Also:
      - `getTablePrimaryKeyValues(String)`

  - ### getTableEntityName

    String getTableEntityName()
    Returns the entity name of this node if this node is a table node. Returns the entity name defined in the data model or a default one (the last step of the table's path is used as the default entity name), or `null` if this node is not a table node.
    Since:
      6.1.0

  - ### getTableOccurrenceRootNode

    SchemaNode getTableOccurrenceRootNode()
    If this node is a table node (see method `isTableNode()`), returns the root node of the record structure.

    This method is used for accessing the internal structure of a table.

    Since a table node is considered to be a terminal node, it does not provide direct access to its children. Instead, the child nodes can only be accessed through the root node of the record structure (the object that is returned by this method).

    Returns:
      the root node of the record structure, `null` if this node is not a table node
    See Also:
      - `isTableNode()`

  - ### isTableOccurrenceNode

    boolean isTableOccurrenceNode()
    Returns `true` if this node is in a table record.

  - ### isHistoryDisabled

    boolean isHistoryDisabled()
    Specifies if the history is disabled for this node. Returns `true` if:
    - this node is a table node and the property `historyProfile` is not set in the data model;
    - the history is explicitly disabled on this node, in the data model;
    - this node is a computed terminal-value;
    - the type of this node is of type `osd:password`;
    - an ancestor of this node in the data model has its history disabled.
    Since:
      5.5.1
    See Also:
      - `AdaptationTable.getHistory()`

  - ### getAccessMode

    AccessPermission getAccessMode()
    Returns the static access mode of the current node. Access can be further restricted by specifying permissions.

    For example, a `function` is `read-only`.

    Note: If the node is neither `terminal` nor a `terminal descendant`, the returned mode is `hidden`. This does not imply that the node is not visible, but rather that it does not directly hold a value.

    See Also:
      - Access Properties
      - `isTerminalValue()`

  - ### getCategory

    String getCategory()
    Returns the category that is defined in data model (attribute `osd:category`); returns `null` if no category is specified on the current node, nor on its ancestors.

  - ### getDefaultValue

    Object getDefaultValue()
    Returns the default value for the node that is defined in data model (attribute `xs:default`), or `null` if no value is specified.

    This default value is typed according to type of the current node. That is, the default value specified in the data model must comply with the type of the associated element.

    If the current node is an aggregated list (an element defining `maxOccurs > 1`) then the returned default value will be a new `List` instance containing a single occurrence of the default value defined in the data model.

  - ### getLabel

    String getLabel(Locale aLocale)
    Returns the localized label of this node.

    The label is computed as follows:

    1. If the data model defines a custom `SchemaDocumentation`, then the computed label is returned, if not, returns `null`;
    2. Otherwise, the label that is defined statically on the current node in the data model is returned;
    3. If no static label is defined, the name of this node is returned (the name is the last part of the node's path).
    See Also:
      - `SchemaDocumentation`
      - `getLabel(Session)`

  - ### getDescription

    String getDescription(Locale aLocale)
    Returns the localized description of this node.

    The description is computed as follows:

    1. If the data model defines a `SchemaDocumentation`, then the description it computes is returned, if not, returns `null`;
    2. Otherwise, the description that is defined statically on the current node in the data model is returned.
    See Also:
      - `getDescription(Session)`

  - ### getLabel

    String getLabel(Session aSession)
    Returns the label of this node for the specified session.

    The label is computed as follows:

    1. If the data model defines a `SchemaDocumentation`, then the label it computes is returned, if not, returns `null`;
    2. Otherwise, the label that is defined statically on the current node in the data model is returned;
    3. If no static label is defined, the name of this node is returned (the name is the last part of the node's path).
    See Also:
      - `getLabel(Locale)`
      - `SchemaDocumentation.getLabel(SchemaDocumentationContext)`

  - ### getDescription

    String getDescription(Session aSession)
    Returns the localized description of this node in the context of a user session.

    The description is computed as follows:

    1. If the data model defines a custom `SchemaDocumentation`, then the computed description is returned, if not, returns `null`;
    2. Otherwise, the description that is defined statically on the current node in the data model is returned.
    See Also:
      - `getDescription(Locale)`
      - `SchemaDocumentation.getDescription(SchemaDocumentationContext)`

  - ### getMandatoryUserMessage

    UserMessage getMandatoryUserMessage()
    Returns the mandatory error message (defined by the data model element `osd:mandatoryErrorMessage`).

  - ### getParent

    SchemaNode getParent()
    Returns the parent node of this node.

    This method returns the root node of the record structure if the current node is a direct child of a table node.

    Since:
      5.7.1
    See Also:
      - `getTableOccurrenceRootNode()`

  - ### getNode

    SchemaNode getNode(Path aPath)
    Returns the node at the specified path, or `null` if no node exists at the specified path.

    If the path is relative, it is interpreted based on the location of this node. This method is equivalent to `getNode(aPath, true, false)`.

    If the path begins with "`//`", this method returns the first node that matches what follows. This syntax is not as efficient as absolute or relative notations.

    See Also:
      - `getPathInSchema()`

  - ### getNode

    SchemaNode getNode(Path aPath, boolean tolerantRead, boolean absolutePathBeginsAtRecordRoot) throws PathAccessException
    Returns the node at the specified path, or `null` if the node does not exist and `isTolerantRead` is `true`.

    Parameters:
      `aPath` - if relative, it is interpreted based on the location of this node.
      `tolerantRead` - if `true`, returns `null` when no node exists at the specified location; otherwise it throws `PathAccessException`.
      `absolutePathBeginsAtRecordRoot` - if value is `true`, `aPath` is absolute, and this node is in a table, the root of the path is the table root node.
    Throws:
      `PathAccessException` - if no node exists at the specified path and `tolerantRead` is `false`.

  - ### getNodeChildren

    SchemaNode[] getNodeChildren()
    Returns the data model nodes defined directly under this node.

    This method is equivalent to:

    > `SchemaNode.getNodeChildren(false);`

  - ### getNodeChildren

    SchemaNode[] getNodeChildren(boolean includeMetadata)
    Returns the data model nodes defined directly under this node.

    This method returns an empty array if the underlying type is a simple type or if this is a table node (see `isTableNode()`). If this is a table node, the method `getTableOccurrenceRootNode()` must be used to get the structure of the table.

    Note: A node can have children and still be considered as "terminal" based on the definition given by the method `isTerminalValue()`.

    Parameters:
      `includeMetadata` - if `true` and if this node is a `table root node`, this methods includes the metadata nodes. Metadata nodes contains information related to a table record (e.g. its creator).
    See Also:
      - `SchemaMetadataConstants`

  - ### isAncestorMultiOccurrenced

    boolean isAncestorMultiOccurrenced()
    Returns `true` if an ancestor of this node is a list.
    Since:
      5.7.1
    See Also:
      - `isAncestorOrSelfMultiOccurrenced()`

  - ### isAncestorOrSelfMultiOccurrenced

    boolean isAncestorOrSelfMultiOccurrenced()
    Returns `true` if this node or one of its ancestors is a list. Returns `false` if this node is a table node.
    Since:
      5.7.1
    See Also:
      - `getMaxOccurs()`
      - `isAncestorMultiOccurrenced()`
      - `isTableNode()`

  - ### getSchemaLocation

    SchemaLocation getSchemaLocation()
    Returns the location of the data model that defines this node.

  - ### getSchemaDefaultLocale

    @Deprecated Locale getSchemaDefaultLocale()
    Deprecated.
    Since 5.9.0 it is not possible to define locales for a module anymore. `Repository.getDefaultLocale()` should be used instead.
    Returns the default locale of EBX®.

  - ### getSchemaLocales

    @Deprecated List<Locale> getSchemaLocales()
    Deprecated.
    Since 5.9.0 it is not possible to define locales for a module anymore. `Repository.getLocales()` should be used instead.
    Returns the locales that are supported by EBX®.

  - ### getXsTypeName

    SchemaTypeName getXsTypeName()
    Returns the type name of this node, or `null` if this node is associated with an anonymous type definition.

  - ### displayOccurrence

    String displayOccurrence(Object aValue, boolean useLabels, ValueContext aValueContext, Locale aLocale)
    Returns a user-friendly representation of the specified value.

    ##### Displaying values

    A value can be displayed differently than its standard XML formatted value (see method `formatToXsString`) in order to be more relevant to the user:
    1. Number and date formats: If the element is a number (`xs:int`, `xs:decimal`, etc.), or a date (`xs:date`, `xs:dateTime`, `xs:time`), it is formatted according to the formatting policy associated with the specified locale.
    2. Value labeling: If `useLabels` is `true` and the element has a declaration that enables value labeling, as described in the table below.

    Data model definition | Value label (if `useLabels = true`)
    `xs:enumeration` | Label is either the value of the attribute `osd:label` or the content of the localized element `xs:documentation`, as specified in the data model.
    `osd:tableRef` | For a foreign key constraint, the label is computed from the referenced record, if it exists, and its data model declaration. In order of preference: The elements `osd:tableRef/display` or `osd:table/defaultLabel`; If there is no such declaration, the label is the concatenation of the label of each primary key fields of the referenced record.
    `osd:enumeration` | For a dynamic enumeration, the label comes from the target node, if it defines such labels.
    `osd:constraintEnumeration` | For a programmatic enumeration constraint, the label is the string returned by the method `ConstraintEnumeration.displayOccurrence`. As a consequence, it may be localized.
    `osd:constraintNomenclature` (deprecated) | For a programmatic nomenclature constraint, the label is the string returned by the method `NomenclatureItem.getLabel`, if the nomenclature item exists for the specified value.
    other cases | No value labeling is performed, the method returns the formatted value.

    ##### Context limitations

    If the specified `ValueContext` is a `ProcedureContext`, this method will throw an `IllegalArgumentException` when dynamic or programmatic labeling calls `ValueContext.getValue(Path)` using a relative path.
    Parameters:
      `aValue` - The value must be compatible with the type of the current node. If the current node specifies `maxOccurs > 1`, then the value must be an element of the `List` instance, not the `List` itself.
      `useLabels` - If `true` and labeling is enabled, specifies to return the label associated with the value. See the table above.
      `aValueContext` - Context that contains the value. It is used when the label to be returned depends on a contextual and dynamic resolution based on a relative path (see above).
      `aLocale` - Locale for formatting numbers, dates or localized labels.
    See Also:
      - `getEnumerationList(ValueContext)`
      - `getEnumerationNomenclature(ValueContext)`

  - ### formatToXsString

    String formatToXsString(Object aValue)
    Returns the string that corresponds to the specified value. This method uses the underlying XML Schema type for performing the `Object`-to-`String` conversion.

    For example, if the underlying type is `xs:date`, the specified record must be a `Date` instance and this method will return the XML Schema representation of this date.

    Throws:
      `IllegalArgumentException` - If the resulting string is not a valid XML string (this happens if a specified `xs:string` contains invalid XML characters).
      `ClassCastException` - if the value is not of the expected Java type.
    See Also:
      - `parseXsString(String)`

  - ### parseXsString

    Object parseXsString(String aString) throws ConversionException
    Returns the value that corresponds to the specified string. This method uses the underlying XML Schema type for performing the `String`-to-`Object` conversion.

    For example, if the underlying type is `xs:date`, the string must conform to the XML Schema representation of dates (for example, "1999-05-31"). This method then returns a `Date` instance.

    Throws:
      `ConversionException` - if specified string is invalid with respect to the underlying XML Schema type.
    See Also:
      - `formatToXsString(Object)`

  - ### getOccurrencesJavaClass

    Class<?> getOccurrencesJavaClass()
    Returns the default `Class` of the Java records of this data model node, `null` if this node is above a terminal node.
    See Also:
      - `isTerminalValue()`
      - Mapping to Java

  - ### getJavaBeanClass

    Class<?> getJavaBeanClass()
    Returns the specific Java Bean `class` defined on this data model node (attribute `osd:class`) or `null` if no Java Bean has been defined and/or this node is not terminal. The difference with `getOccurrencesJavaClass()` is the fact that it returns `null` if no specific Java Bean has been defined in the data model. Therefore for simple types, it returns always `null`.
    See Also:
      - `isTerminalValue()`
      - `isComplex()`
      - Mapping to Java

  - ### createNewOccurrence

    Object createNewOccurrence()
    Creates a new Java object that complies to this node definition.

    The returned value conforms to the following rules:

    - If the element declaration includes `maxOccurs > 1`, the method does not take this fact into account (that is, it returns an element of the `List`, not a `List` instance).
    - If the element is of a simple type and no default value is defined, it returns `null`.
    - If the element is of a simple type and a default value is defined, it returns this default value (a clone of it, if this is a mutable object).
    - If the element is of a complex type, it returns a new instance, either of the class specified in the `osd:class=""` attribute, or of a default internal class (such an instance may be accessed by `executeRead(Object)`).
    See Also:
      - `executeRead(Object)`
      - `getOccurrencesJavaClass()`
      - Mapping to Java

  - ### executeRead

    Object executeRead(Object aContainerOccurrence)
    Reads the specified occurrence of the parent node and returns the value corresponding to this node.

    Precondition: This node must be a `descendant of a terminal node`.

    ##### Example

    A parent node declares `maxOccurs > 1` and it refers to a complex. Hence, the parent value will be a Java `List`. For each object (occurrence) in the list, this method gets the value associated with this child node.

    Parameters:
      `aContainerOccurrence` - must be an occurrence complying with the data model definition of the parent node.
    See Also:
      - `executeWrite(Object, Object)`
      - `getOccurrencesJavaClass()`
      - Mapping to Java

  - ### executeWrite

    void executeWrite(Object aValue, Object aContainerOccurrence)
    Modifies the specified occurrence of the parent node by setting the specified value. As explained in the section Modification of mutable objects, to be persisted, the locally modified object must be set to the context.

    Precondition: This node must be a `descendant of a terminal node`.

    Parameters:
      `aValue` - value to be set on the parent object, it must comply with the data model definition of this node; if it specifies `maxOccurs > 1`, the specified value must be a `List`.
      `aContainerOccurrence` - parent object to be modified, it must be an occurrence complying with the data model definition of the parent node; the parent node must be a complex type; if it specifies `maxOccurs > 1`, the specified object must be an element of `List`, not the `List` itself.
    Since:
      5.5.1
    See Also:
      - `executeRead(Object)`
      - `createNewOccurrence()`
      - `getOccurrencesJavaClass()`
      - Mapping to Java

  - ### getFacets

    Iterator<SchemaFacet> getFacets()
    Returns an iterator over the `facets` defined by this data model node.

    This method can be useful for retrieving all facets of a certain type. For example, using this method to get both the static and dynamic `length` facets on this node.

    See Also:
      - `SchemaFacet`

  - ### getFacetOnMandatoryField

    SchemaFacetOnMandatoryField getFacetOnMandatoryField()
    Returns the facet corresponding to the cardinality constraint related to a mandatory field (declares both `minOccurs=1` and `maxOccurs=1`).
    Since:
      6.0.0
    See Also:
      - `SchemaFacetOnMandatoryField`

  - ### getFacetLength

    SchemaFacetLength getFacetLength()
    Returns the first `length` facet declared on this node. Returns `null` if the node has no `length` facets defined.

    If multiple `length` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetLength`

  - ### getFacetMaxLength

    SchemaFacetMaxLength getFacetMaxLength()
    Returns the first `maxlength` facet declared on this node. Returns `null` if the node has no `maxlength` facets defined.

    If multiple `maxlength` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetMaxLength`

  - ### getFacetMinLength

    SchemaFacetMinLength getFacetMinLength()
    Returns the first `minLength` facet declared on this node. Returns `null` if the node has no `minLength` facets defined.

    If multiple `minLength` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetMinLength`

  - ### getFacetMaxBoundaryExclusive

    SchemaFacetBoundaryMaxExclusive getFacetMaxBoundaryExclusive()
    Returns the first `maxExclusive` facet declared on this node. Returns `null` if the node has no `maxExclusive` facets defined.

    If multiple `maxExclusive` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetBoundaryMaxExclusive`

  - ### getFacetMaxBoundaryInclusive

    SchemaFacetBoundaryMaxInclusive getFacetMaxBoundaryInclusive()
    Returns the first `maxInclusive` facet declared on this node. Returns `null` if the node has no `maxInclusive` facets defined.

    If multiple `maxInclusive` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetBoundaryMaxInclusive`

  - ### getFacetMinBoundaryExclusive

    SchemaFacetBoundaryMinExclusive getFacetMinBoundaryExclusive()
    Returns the first `minExclusive` facet declared on this node. Returns `null` if the node has no `minExclusive` facets defined.

    If multiple `minExclusive` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetBoundaryMinExclusive`

  - ### getFacetMinBoundaryInclusive

    SchemaFacetBoundaryMinInclusive getFacetMinBoundaryInclusive()
    Returns the first `minInclusive` facet declared on this node. Returns `null` if the node has no `minInclusive` facets defined.

    If multiple `minInclusive` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetBoundaryMinInclusive`

  - ### getFacetPattern

    SchemaFacetPattern getFacetPattern()
    Returns the first `pattern` facet declared on this node. Returns `null` if the node has no `pattern` facets defined.

    If multiple `pattern` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetPattern`

  - ### getFacetTotalDigits

    SchemaFacetTotalDigits getFacetTotalDigits()
    Returns the first `totalDigits` facet declared on this node. Returns `null` if the node has no `totalDigits` facets defined.

    If multiple `totalDigits` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetTotalDigits`

  - ### getFacetExcludeValue

    SchemaFacetExcludeValue getFacetExcludeValue()
    Returns the first `excludeValue` facet declared on this node. Returns `null` if the node has no `excludeValue` facets defined.

    If multiple `excludeValue` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetExcludeValue`

  - ### getFacetExcludeSegment

    SchemaFacetExcludeSegment getFacetExcludeSegment()
    Returns the first `excludeSegment` facet declared on this node. Returns `null` if the node has no `excludeSegment` facets defined.

    If multiple `excludeSegment` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetExcludeSegment`

  - ### getFacetFractionDigits

    SchemaFacetFractionDigits getFacetFractionDigits()
    Returns the first `fractionDigits` facet declared on this node. Returns `null` if the node has no `fractionDigits` facets defined.

    If multiple `fractionDigits` facets are defined, the method `getFacets()` can be called instead to retrieve all facets declared on this node.

    See Also:
      - `SchemaFacetFractionDigits`

  - ### getFacetOnTableReference

    SchemaFacetTableRef getFacetOnTableReference()
    Returns the `osd:tableRef` facet (foreign key constraint) declared on this node. Returns `null` if the node does not have a foreign key constraint or if it has errors due to a non-existent container dataset or dataspace.

  - ### getFacetOResource

    SchemaFacetOResource getFacetOResource()
    Returns the `OResource` facet held by this node. Returns `null` if the node does not have an `OResource` facet.
    See Also:
      - `SchemaFacetOResource`

  - ### getFacetEnumeration

    SchemaFacetEnumeration getFacetEnumeration()
    Returns the first `enumeration` facet declared on this node. That is, one the following facets: `xs:enumeration`, `osd:tableRef`, `osd:enumeration`, `osd:constraintEnumeration`, or `osd:constraintNomenclature` (deprecated). Returns `null` if the node does not define an enumeration.
    See Also:
      - `getEnumerationList(ValueContext)`
      - `getEnumerationNomenclature(ValueContext)`

  - ### getEnumerationList

    <T> List<T> getEnumerationList(ValueContext aValueContext)
    If the data model specifies an enumeration, returns the values that this node may take on. If no enumeration is specified, this method returns `null`.

    When a label is associated with a value, this label may be displayed by invoking `displayOccurrence`.

    The supported cases are as follows:

    Data model definition | Result
    `xs:enumeration` | For a static enumeration, this method returns the list of static objects defined in the data model.
    `osd:tableRef` | For a foreign key constraint, this method returns the list of primary keys defined by the target table, in their `String` representation (see `PrimaryKey.format()`).
    `osd:enumeration` | For a dynamic enumeration, this method returns the list of objects defined by the target node.
    `osd:constraintEnumeration` | For a programmatic enumeration constraint, this method returns the list of objects as returned by `ConstraintEnumeration.getValues(ValueContext)`.
    `osd:constraintNomenclature` (deprecated) | For a programmatic nomenclature constraint, this method returns the list of the values of the nomenclature returned by `ConstraintNomenclature.getNomenclature(ValueContext)`.
    other cases | This method returns `null`.

    Parameters:
      `aValueContext` - Context containing the enumeration, used when the enumeration to be returned depends on a contextual and dynamic resolution.
    See Also:
      - `displayOccurrence(Object, boolean, ValueContext, Locale)`
      - `getFacetEnumeration()`

  - ### getUniquenessConstraints

    List<UniquenessConstraint> getUniquenessConstraints()
    Returns the `uniqueness constraints` applied on this table using the property `xs:unique`. Returns `null` if this node is not a table or does not contain `uniqueness constraints`.
    Since:
      5.8.1
    See Also:
      - `isTableNode()`
      - `UniquenessConstraint`

  - ### getEnumerationNomenclature

    <T> Nomenclature<T> getEnumerationNomenclature(ValueContext aValueContext)
    Returns the underlying `Nomenclature`, if found by searching through facets. If no nomenclature is found, returns `null`.

    The supported cases are as follows:

    Data model definition | Result
    `osd:enumeration` | For a dynamic enumeration whose target node itself has a nomenclature, this method returns the nomenclature that corresponds to the values of the target node.
    `osd:constraintNomenclature` (deprecated) | For a programmatic nomenclature constraint, this method returns the nomenclature, as returned by `ConstraintNomenclature.getNomenclature(ValueContext)`.
    other cases | Returns `null`.

    Parameters:
      `aValueContext` - Context containing the nomenclature, used when the nomenclature to be returned depends on a contextual and dynamic resolution.
    Returns:
      see table above.
    See Also:
      - `getFacetEnumeration()`

  - ### isValueFunction

    boolean isValueFunction()
    Returns `true` if this node holds a function.

    A function is specified in the data model using an `osd:function` extension.

    See Also:
      - `ValueFunction`

  - ### isValidationDisabled

    boolean isValidationDisabled()
    Returns `true` if the validation is disabled on this node.

    Validation is disabled if this node is computed and defines in the data model the attribute `osd:disableValidation = true`.

    Since:
      5.8.1
    See Also:
      - `isValueFunction()`

  - ### getInformation

    SchemaNodeInformation getInformation()
    Returns the additional information (element `osd:information`) for this node, as defined in the data model.

  - ### getDefaultViewProperties

    SchemaNodeDefaultView getDefaultViewProperties()
    Returns the default view properties for this node, as defined in the data model (element `osd:defaultView` under the element `xs:annotation/xs:appinfo`).

    If no default view is specified, this method returns a default `SchemaNodeDefaultView` with the following values:

    Method | Returned value
    `SchemaNodeDefaultView.getDisplayMode()` | `null`
    `SchemaNodeDefaultView.getHiddenInSearch()` | `"false"`
    `SchemaNodeDefaultView.getTabOrder()` | `null`
    `SchemaNodeDefaultView.getViewForAdvancedSelection()` | `null`
    `SchemaNodeDefaultView.getWidgetFactory()` | `null`
    `SchemaNodeDefaultView.isHidden()` | `false`
    `SchemaNodeDefaultView.isHiddenInDataServices()` | `false`
    `SchemaNodeDefaultView.isHiddenInAllViews()` | `false`

    Since:
      5.7.1

  - ### getInheritanceProperties

    SchemaInheritanceProperties getInheritanceProperties()
    Returns the inheritance properties (element `osd:inheritance`) for this node, as defined in the data model. If no inheritance is specified, this method returns `null`.

  - ### getSchemaDefaultTableView

    SchemaDefaultTableView getSchemaDefaultTableView()
    Returns the default table view properties for this node, as defined in the data model.

    Returns null if the current node is not a table node.

    Since:
      6.2.1