Package com.orchestranetworks.schema

# Interface DependenciesDefinitionContext

All Superinterfaces:
  `SchemaNodeContext`

All Known Subinterfaces:
  `ConstraintContext`, `ConstraintContextOnTable`, `TableRefFilterContext`

public interface DependenciesDefinitionContext extends SchemaNodeContext
Provides methods for setting dependencies in the context of a constraint and its data model.

### Dependencies and validation

This context provides methods for declaring a constraint's dependencies. Constraint dependencies are used to minimize the number of calls to these constraints during the validation process. For instance, in the context of programmatic constraints, calls to the method `Constraint.checkOccurrence(Object, ValueContextForValidation)` will be minimized if dependencies are defined. Three modes are available:

1. Local dependency: In this mode, the validation result of the current constraint depends only on the local value of the underlying node. Besides modification of this local value, the validation result will not be affected by any external events. This mode is enabled by calling the method `ConstraintContext.setDependencyToLocalNode()`.
2. Explicit dependencies: In this mode, the validation result of the current constraint depends only on updates of the source nodes that have been specified explicitly. Besides such updates and modification of the local value, the validation result will not be affected by any external events. One or more explicit dependencies can be specified using methods:
   - `addDependencyToModify(Path)`.
   - `addDependencyToModify(SchemaNode)`.
   - `addDependencyToInsertAndDelete(Path)`.
   - `addDependencyToInsertAndDelete(SchemaNode)`.
   - `addDependencyToInsertDeleteAndModify(Path)`.
   - `addDependencyToInsertDeleteAndModify(SchemaNode)`.
   - `addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference)`.
   - `addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference, HomeKey)`.
   - `addDependencyToInsertDeleteAndModifyInOtherInstance(Path, AdaptationReference)`.
   - `addDependencyToInsertDeleteAndModifyInOtherInstance(Path, AdaptationReference, HomeKey)`.
   - `addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode, AdaptationReference)`.
   - `addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode, AdaptationReference, HomeKey)`.
3. Unknown dependencies (default): In this mode, the validation result of the current constraint depends on unknown sources or events (for example, data stored in an external system). This is the default mode, enabled if neither of the above methods has been called or if the element containing this constraint is computed by a value function or is an inherited field (defines the property `osd:inheritance`).

Attention:

- Dependencies on computed values and inherited fields (define the property `osd:inheritance`) are not allowed. Constraints applied on elements defining a value function will be automatically set to Unknown dependencies mode. Consequently, if a constraint attempts to specify an explicit dependency, an `IllegalArgumentException` will be thrown.
- If local or explicit dependencies are specified, they must be in complete accordance with the constraint's actual implementation. More precisely, if a dependency is missing, the validation result could be inaccurate.
- It is not mandatory to specify dependencies. The specification of local or explicit dependencies is useful when large volumes of data must be validated and/or the validation algorithm is particularly expensive. In other cases, the default unknown dependencies mode is sufficient.
- In EBX® user interface mode, the current constraint is always checked when user input is submitted.

See Also:
  - validation
  - `ValueFunctionContext`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDependencyToInsertAndDelete(Path aPathToATableSourceNode)`
  Specifies that the validation result of the current constraint depends on the insertions and deletions of the table node with the specified path.
  `void`
  `addDependencyToInsertAndDelete(SchemaNode aTableSourceNode)`
  Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node.
  `void`
  `addDependencyToInsertAndDeleteInOtherInstance(Path tablePathInContainer, AdaptationReference containerReference)`
  Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node of a given instance.
  `void`
  `addDependencyToInsertAndDeleteInOtherInstance(Path tablePathInContainer, AdaptationReference containerReference, HomeKey homeReference)`
  Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node of a given dataset in a specific dataspace.
  `void`
  `addDependencyToInsertDeleteAndModify(Path aPathToSourceNode)`
  Specifies that the validation result of the current constraint depends on insertions, modifications and deletions on the node targeted by the specified path.
  `void`
  `addDependencyToInsertDeleteAndModify(SchemaNode aSourceNode)`
  Specifies that the validation result of the current constraint depends on insertions, modifications and deletions on the specified node.
  `void`
  `addDependencyToInsertDeleteAndModifyInOtherInstance(Path nodePath, AdaptationReference containerReference)`
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset.
  `void`
  `addDependencyToInsertDeleteAndModifyInOtherInstance(Path nodePath, AdaptationReference containerReference, HomeKey homeReference)`
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset in a specific dataspace.
  `void`
  `addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode sourceNode, AdaptationReference containerReference)`
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset.
  `void`
  `addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode sourceNode, AdaptationReference containerDataSetReference, HomeKey dataSpaceReference)`
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset in a specific dataspace.
  `void`
  `addDependencyToModify(Path aPathToLocalSource)`
  Specifies that the validation result of the current constraint depends on the value of the source node with the specified path in the same record.
  `void`
  `addDependencyToModify(SchemaNode aLocalSource)`
  Specifies that the validation result of the current constraint depends on the value of the specified source node in the same record.

  ### Methods inherited from interface com.orchestranetworks.schema.SchemaNodeContext

  `addError, addError, addInfo, addMessage, addWarning, getSchemaNode`

- ## Method Details

  - ### addDependencyToModify

    void addDependencyToModify(SchemaNode aLocalSource)
    Specifies that the validation result of the current constraint depends on the value of the specified source node in the same record.

    In the scope of incremental validation, this implies that any modification to the source node's value will trigger a revalidation of this constraint within the context of the altered record.

    In the context of a constraint on a table, this method can be used to add a modification dependency to a dataset node.

    Attention:

    - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
    - If the source or current node are computed by a computed value in unknown dependencies mode mode or are an inherited field (defines the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
    Throws:
      `IllegalStateException` - if a local dependency has been set to this constraint.
      `IllegalStateException` - if this constraint is set to Unknown dependencies mode.
      `IllegalArgumentException` - if the specified source node does not have a local value; that is:
      - it is not a terminal node or under a terminal node.
      - it is a table node.
      - it is a table record node not in the same table as the current node (if this node is also in a table record).

  - ### addDependencyToModify

    void addDependencyToModify(Path aPathToLocalSource)
    Specifies that the validation result of the current constraint depends on the value of the source node with the specified path in the same record.

    In the scope of incremental validation, this implies that any modification to the source node's value will trigger a revalidation of this constraint within the context of the altered record.

    In the context of a constraint on a table, this method can be used to add a modification dependency to a dataset node.

    Attention:

    - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
    - If the source or current node are computed by a computed value in unknown dependencies mode mode or are an inherited field (defines the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
    Throws:
      `IllegalStateException` - if a local dependency has been set to this constraint.
      `IllegalStateException` - if this constraint is set to Unknown dependencies mode.
      `IllegalArgumentException` - if no node is found at the specified path. if the source targeted by the specified path does not have a local value; that is:
      - it is not a terminal node or under a terminal node.
      - it is a table node.
      - it is a table record node not in the same table as the current node (if this node is also in a table record).
    Since:
      6.1.1

  - ### addDependencyToInsertAndDelete

    void addDependencyToInsertAndDelete(SchemaNode aTableSourceNode)
    Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node.

    In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

    - An insertion in the specified source table.
    - A deletion in the specified source table.
    Attention: A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.

    Throws:
      `IllegalStateException` - if a local dependency has been set for this constraint.
      `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
      `IllegalArgumentException` - if specified source is not a table node.

  - ### addDependencyToInsertAndDelete

    void addDependencyToInsertAndDelete(Path aPathToATableSourceNode)
    Specifies that the validation result of the current constraint depends on the insertions and deletions of the table node with the specified path.

    In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

    - An insertion in the source table with the specified path.
    - A deletion in the source table with the specified path.
    Attention: A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.

    Throws:
      `IllegalStateException` - if a local dependency has been set for this constraint.
      `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
      `IllegalArgumentException` - if no table node is found at the specified path.
    Since:
      6.1.1

  - ### addDependencyToInsertAndDeleteInOtherInstance

    void addDependencyToInsertAndDeleteInOtherInstance(Path tablePathInContainer, AdaptationReference containerReference, HomeKey homeReference)
    Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node of a given dataset in a specific dataspace.

    In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

    - An insertion in the specified source table.
    - A deletion in the specified source table.

    Attention: A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.

    Throws:
      `IllegalStateException` - if a local dependency has been set for this constraint.
      `IllegalArgumentException` - if specified source is not a table node. if specified containerReference is `null`. if specified homeReference is `null`.
    See Also:
      - `addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference)`

  - ### addDependencyToInsertAndDeleteInOtherInstance

    void addDependencyToInsertAndDeleteInOtherInstance(Path tablePathInContainer, AdaptationReference containerReference)
    Specifies that the validation result of the current constraint depends on the insertions and deletions of the specified table node of a given instance.

    In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

    - An insertion in the specified source table.
    - A deletion in the specified source table.

    Attention: A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.

    Throws:
      `IllegalStateException` - if a local dependency has been set for this constraint.
      `IllegalArgumentException` - if specified source is not a table node. if specified containerReference is `null`.
    See Also:
      - `addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference, HomeKey)`

  - ### addDependencyToInsertDeleteAndModify

    void addDependencyToInsertDeleteAndModify(SchemaNode aSourceNode)
    Specifies that the validation result of the current constraint depends on insertions, modifications and deletions on the specified node.

    In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

    - An insertion in the source table.
    - A deletion in the source table.
    - A modification of any node in any of the records in the source table if the source node is a table node.
    - A modification of the source node in any of the records in the source table if the source node is a table record node.

    Attention:

    - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
    - If the source node is a table record node and if it, or the current node are computed by a computed value, or are an inherited field (defines the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
    Parameters:
      `aSourceNode` - specifies the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all records of the table; if the source is a table record node, the revalidation is more restrictive since only modification of the specified node and any insertions or deletions will result in revalidation.
    Throws:
      `IllegalStateException` - if a local dependency has been set for this constraint.
      `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
      `IllegalArgumentException` - if the specified source node is not a table node or table record node.

- ### addDependencyToInsertDeleteAndModify

  void addDependencyToInsertDeleteAndModify(Path aPathToSourceNode)
  Specifies that the validation result of the current constraint depends on insertions, modifications and deletions on the node targeted by the specified path.

  In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

  - An insertion in the source table.
  - A deletion in the source table.
  - A modification of any node in any of the records in the source table if the source node targeted by the specified path is a table node.
  - A modification of the source node in any of the records in the source table if the source node targeted by the specified path is a table record node.

  Attention:

  - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
  - If the source node is a table record node and if it or the current node are computed by a computed value or are an inherited field (defines the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
  Parameters:
    `aPathToSourceNode` - specifies the path to the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all records of the table; if the source is a table record node, the revalidation is more restrictive since only modification of the specified node and any insertions or deletions will result in revalidation.
  Throws:
    `IllegalStateException` - if a local dependency has been set for this constraint.
    `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
    `IllegalArgumentException` - if no node is found at the specified path. if the found node is not a table node or table record node.

Since:
  6.1.1

- ### addDependencyToInsertDeleteAndModifyInOtherInstance

  void addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode sourceNode, AdaptationReference containerDataSetReference, HomeKey dataSpaceReference)
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset in a specific dataspace.

  In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

  - An insertion in the source table.
  - A deletion in the source table.
  - A modification of any node in any of the records in the source table, if the source node is a table node.
  - A modification of the source node in any of the records in the source table, if the source node is a table record node.

  Attention:

  - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
If the source node is a table record node and if it or the current node are computed by a value function in unknown dependencies mode mode or are an inherited field (define the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.

Parameters:
  `sourceNode` - specifies the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all the records of the table; if the source is a table record node, the revalidation is more restrictive since only the modification of the specified node or any insertion or deletion will result in revalidation.
Throws:
  `IllegalStateException` - if a local dependency has been set for this constraint.
  `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
  `IllegalArgumentException` - if the specified source node is not a table node or a table record node. if specified `containerReference` is `null`. if specified `homeReference` is `null`.

- ### addDependencyToInsertDeleteAndModifyInOtherInstance

  void addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode sourceNode, AdaptationReference containerReference)
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset.

  In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

  - An insertion in the source table.
  - A deletion in the source table.
  - A modification of any node is done in any of the records in the source table, if the source node is a table node.
  - A modification of the source node in any of the records in the source table, if the source node is a table record node..s

  Attention:

  - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
  - If the source node is a table record node and if it or the current node are computed by a value function in unknown dependencies mode mode or are an inherited field (define the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
  Parameters:
    `sourceNode` - specifies the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all the records of the table; if the source is a table record node, the revalidation is more restrictive since only the modification of the specified node or any insertion or deletion will result in revalidation.
  Throws:
    `IllegalStateException` - if a local dependency has been set for this constraint.
    `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
    `IllegalArgumentException` - if the specified source node is not a table node or a table record node. if specified `containerReference` is `null`.

- ### addDependencyToInsertDeleteAndModifyInOtherInstance

  void addDependencyToInsertDeleteAndModifyInOtherInstance(Path nodePath, AdaptationReference containerReference)
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset.

  In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

  - An insertion in the source table.
  - A deletion in the source table.
  - A modification of any node is done in any of the records in the source table, if the source node is a table node;
  - A modification of the source node in any of the records in the source table, if the source node is a table record node.

  Attention:

  - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
  - If the source node is a table record node and if it or the current node are computed by a value function in unknown dependencies mode mode or are an inherited field (define the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.
  Parameters:
    `nodePath` - specifies the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all the records of the table; if the source is a table record node, the revalidation is more restrictive since only the modification of the specified node or any insertion or deletion will result in revalidation.
  Throws:
    `IllegalStateException` - if a local dependency has been set for this constraint.
    `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
    `IllegalArgumentException` - if no node is found at the specified path. if the found source node is not a table node or a table record node. if specified `containerReference` is `null`.
  Since:
    6.1.1

- ### addDependencyToInsertDeleteAndModifyInOtherInstance

  void addDependencyToInsertDeleteAndModifyInOtherInstance(Path nodePath, AdaptationReference containerReference, HomeKey homeReference)
  Specifies that the validation result of the current constraint depends on the insertions, modifications and deletions on the specified node in a given dataset in a specific dataspace.

  In the scope of incremental validation, this implies that the current constraint is revalidated for all of the table's records if any of the following events occur:

  - An insertion in the source table.
  - A deletion in the source table.
  - A modification of any node in any of the records in the source table, if the source node is a table node.
  - A modification of the source node in any of records in the source table, if the source node is a table record node.

  Attention:

  - A call to this method implies that all dependencies are explicitly declared (explicit dependencies mode). For more information, see Dependencies and validation above.
If the source node is a table record node and if it or the current node are computed by a value function in unknown dependencies mode mode or are an inherited field (define the property `osd:inheritance`), then this constraint will be considered to be in unknown dependencies mode.

Parameters:
  `nodePath` - specifies the source node and table on which this constraint depends; if the source is a table node, any insertion, modification and deletion in the table will result in the revalidation of the current constraint for all the records of the table; if the source is a table record node, the revalidation is more restrictive since only the modification of the specified node or any insertion or deletion will result in revalidation.
Throws:
  `IllegalStateException` - if a local dependency has been set for this constraint.
  `IllegalStateException` - if this constraint is set in Unknown dependencies mode.
  `IllegalArgumentException` - if no node is found at the specified path. if the found source node is not a table node or a table record node. if specified `containerReference` is `null`. if specified `homeReference` is `null`.
Since:
  6.1.1