Package com.orchestranetworks.schema.info

# Interface SchemaFacetTableRef

All Superinterfaces:
  `SchemaFacet`, `SchemaFacetEnumeration`, `SchemaNodeExplicitRelationship`

public interface SchemaFacetTableRef extends SchemaFacetEnumeration, SchemaNodeExplicitRelationship
This interface represents the foreign key constraint associated with a node (`osd:tableRef`).

### Dependencies and validation

To optimize the validation process of this foreign key constraint, dependencies are automatically determined from its definition.

The following explicit dependencies are automatically defined:

1. Dependencies on insertions and deletions in the table referenced by this foreign key constraint. These dependencies can be added by:
   - `DependenciesDefinitionContext.addDependencyToInsertAndDelete(SchemaNode)` in the default case;
   - `DependenciesDefinitionContext.addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference)`, if this foreign key constraint defines a dataset container;
   - `DependenciesDefinitionContext.addDependencyToInsertAndDeleteInOtherInstance(Path, AdaptationReference, HomeKey)`, if this foreign key constraint defines a dataset container in another dataspace.
2. Dependencies on insertions, deletions and modifications on criterion nodes, if this foreign key constraint defines an XPath filter.

   For example, if this constraint defines the XPath filter `oid = ${../author_id}`, then a dependency on the node on the left side, `oid`, is defined. These dependencies can be added by:

   - `DependenciesDefinitionContext.addDependencyToInsertDeleteAndModify(SchemaNode)`, in the default case;
   - `DependenciesDefinitionContext.addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode, AdaptationReference)`, if this foreign key constraint defines an dataset container;
   - `DependenciesDefinitionContext.addDependencyToInsertDeleteAndModifyInOtherInstance(SchemaNode, AdaptationReference, HomeKey)`, if this foreign key constraint defines a dataset container in another dataspace.

   In all of the above methods, the `SchemaNode` argument is `oid`.

   Dependencies on modifications to the right side, `${../author_id}`, are also defined. In this case, the dependency is the same as: `DependenciesDefinitionContext.addDependencyToModify(SchemaNode)`, where the argument `SchemaNode` is `${../author_id}`.

Thus, the validation result of this foreign key constraint only depends upon the updates to the target table that are relevant to these explicit dependencies. The validation result will not be affected by any external events other than changes to the local values concerned.

The dependencies of this foreign key constraint are set to Unknown if this foreign key constraint defines:

- a programmatic filter with no explicit dependencies.
- an XPath filter specifying criterion nodes that are not in the target table.

Attention:

- The dependencies automatically defined in this constraint are used in addition to any that may be defined by a `filter`.
- In the user interface, this foreign key constraint is always called when user input is submitted.

See Also:
  - foreign keys
  - validation
  - `SchemaNode.getFacetOnTableReference()`
  - `TableRefFilterContext`
  - `ExplicitRelationship`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HomeKey`
  `getContainerHome()`
  Returns the container dataspace of this foreign key constraint, if an external container in a dataspace or snapshot is defined (property `branch`), otherwise returns `null`.
  `AdaptationReference`
  `getContainerReference()`
  Returns the reference of the container dataset of this foreign key constraint, if an external container is defined (property `container`), otherwise returns `null`.
  `Adaptation`
  `getLinkedRecord(Adaptation aRecord)`
  Returns the linked record for the specified record.
  `Adaptation`
  `getLinkedRecord(ValueContext aContext)`
  Returns the linked record for the specified context.
  `List<Adaptation>`
  `getLinkedRecords(Adaptation aRecord)`
  Returns the linked records for the specified record.
  `List<Adaptation>`
  `getLinkedRecords(ValueContext aContext)`
  Returns the linked records for the specified context.
  `AdaptationTable`
  `getTable(ValueContext aValueContext)`
  Returns the table referred to by this foreign key constraint.
  `SchemaNode`
  `getTableNode()`
  Returns the table node referred to by this foreign key constraint.
  `Path`
  `getTablePath()`
  Returns the table path referred to by this foreign key constraint.
  `SchemaNode[]`
  `getTablePrimaryKeyNodes()`
  Returns the fields that compose the primary key of the table referred to by this foreign key constraint.
  `Object[]`
  `getTablePrimaryKeyValues(String aTableRefValue)`
  Decomposes the specified `osd:tableRef` value into the values it would have in the target table.
  `Request`
  `getTableRefRequest(Adaptation aRecord)`
  Returns the request of the foreign key constraint, in the context of the specified record.
  `String`
  `getXPathFilter()`
  Returns the XPath filter defined on this foreign key constraint.

  ### Methods inherited from interface com.orchestranetworks.schema.info.SchemaFacet

  `getDocumentation, getFacetValidationMessage, getSchemaNode, getValidationPolicy, isEnumerationList, isEnumerationNomenclature, isEnumerationTableRef, isFacetBoundaryMaxExclusive, isFacetBoundaryMaxInclusive, isFacetBoundaryMinExclusive, isFacetBoundaryMinInclusive, isFacetEnumeration, isFacetExcludeSegment, isFacetExcludeValue, isFacetFractionDigits, isFacetLength, isFacetMaxLength, isFacetMinLength, isFacetOnMandatoryField, isFacetOResource, isFacetPattern, isFacetTotalDigits`

  ### Methods inherited from interface com.orchestranetworks.schema.info.SchemaFacetEnumeration

  `containsValue, getEnumerationNode, getNomenclature, getPathToNomenclature, getPathToValues, getValues, isConstraintEnumeration, isEnumerationStatic`

  ### Methods inherited from interface com.orchestranetworks.schema.relationships.SchemaNodeExplicitRelationship

  `getBreadcrumbProperties, getExplicitRelationship, getExplicitRelationship, getOwnerNode, getResult, getTableNode, isAssociationLink, isDynamic, isSelectionLink, isTableRefLink`

- ## Method Details

  - ### getTablePath

    Path getTablePath()
    Returns the table path referred to by this foreign key constraint.
    See Also:
      - `getTableNode()`

  - ### getContainerReference

    AdaptationReference getContainerReference()
    Returns the reference of the container dataset of this foreign key constraint, if an external container is defined (property `container`), otherwise returns `null`.
    Specified by:
      `getContainerReference` in interface `SchemaNodeExplicitRelationship`

  - ### getContainerHome

    HomeKey getContainerHome()
    Returns the container dataspace of this foreign key constraint, if an external container in a dataspace or snapshot is defined (property `branch`), otherwise returns `null`.
    Specified by:
      `getContainerHome` in interface `SchemaNodeExplicitRelationship`

  - ### getTableNode

    SchemaNode getTableNode()
    Returns the table node referred to by this foreign key constraint.
    Specified by:
      `getTableNode` in interface `SchemaNodeExplicitRelationship`
    See Also:
      - `SchemaNode.isTableNode()`

  - ### getXPathFilter

    String getXPathFilter()
    Returns the XPath filter defined on this foreign key constraint. Returns `null` if no XPath filter is defined.
    Since:
      6.0.0

  - ### getTable

    AdaptationTable getTable(ValueContext aValueContext)
    Returns the table referred to by this foreign key constraint.
    Throws:
      `IllegalArgumentException` - if the specified context is `null`.
      `IllegalArgumentException` - if the specified context is not in the same table as the current node (it is recommended to get this constraint from the specified context, for example using `ValueContext.getNode(Path)`).
      `InvalidSchemaException` - if the container dataset or dataspace of this foreign key constraint does not exist in the current repository.
      `UnsupportedOperationException` - if the current table is a history table.
    See Also:
      - `SchemaNode.isTableNode()`

  - ### getTablePrimaryKeyNodes

    SchemaNode[] getTablePrimaryKeyNodes()
    Returns the fields that compose the primary key of the table referred to by this foreign key constraint.

    This method is equivalent to:

    > `SchemaFacetTableRef.getTableNode().getTablePrimaryKeyNodes();`

    Since:
      5.2.3
    See Also:
      - `SchemaNode.getTablePrimaryKeyNodes()`

  - ### getTablePrimaryKeyValues

    Object[] getTablePrimaryKeyValues(String aTableRefValue) throws InvalidPrimaryKeyException, IllegalArgumentException
    Decomposes the specified `osd:tableRef` value into the values it would have in the target table.

    This method is equivalent to:

    > `SchemaFacetTableRef.getTableNode().getTablePrimaryKeyValues(aTableRefValue);`

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

  - ### getTableRefRequest

    Request getTableRefRequest(Adaptation aRecord)
    Returns the request of the foreign key constraint, in the context of the specified record.
    Throws:
      `UnsupportedOperationException` - if the current table is a history table.

  - ### getLinkedRecord

    Adaptation getLinkedRecord(ValueContext aContext)
    Returns the linked record for the specified context.
    Returns:
      the record referred to by the current node in the specified context, `null` if the node's value is undefined or refers to a non-existent record.
    Throws:
      `IllegalArgumentException` - if the current node is an aggregated list or is under an aggregated list.
      `IllegalArgumentException` - if the specified context is not in the same data model as the current node (it is recommended to get this constraint from the specified context, for example by using `ValueContext.getNode(Path)`).
      `UnsupportedOperationException` - if the current table is a history table.
    Since:
      5.2.3
    See Also:
      - `SchemaNodeExplicitRelationship.getResult(Adaptation, com.orchestranetworks.service.Session)`

  - ### getLinkedRecord

    Adaptation getLinkedRecord(Adaptation aRecord)
    Returns the linked record for the specified record.
    Throws:
      `UnsupportedOperationException` - if the current table is a history table.
    Since:
      5.2.3
    See Also:
      - `getLinkedRecord(ValueContext)`
      - `SchemaNodeExplicitRelationship.getResult(Adaptation, com.orchestranetworks.service.Session)`

  - ### getLinkedRecords

    List<Adaptation> getLinkedRecords(Adaptation aRecord)
    Returns the linked records for the specified record.
    Returns:
      the records referred to by the current node in the specified context; any values that refer to non-existent records are ignored; never returns `null`, if void returns `Collections.EMPTY_LIST`. Returns a flat list with no duplicates if this foreign key constraint is held by a node that is a list or under a list. That is, the returned list does not contain other lists of records if this foreign key constraint is defined by a node embedded in multiple lists.
    Throws:
      `UnsupportedOperationException` - if the current table is a history table.
    Since:
      5.2.3
    See Also:
      - `getLinkedRecords(ValueContext)`
      - `SchemaNodeExplicitRelationship.getResult(Adaptation, com.orchestranetworks.service.Session)`

  - ### getLinkedRecords

    List<Adaptation> getLinkedRecords(ValueContext aContext)
    Returns the linked records for the specified context.
    Returns:
      the records referred to by the current node in the specified context; any values that refer to non-existent records are ignored; never returns `null`, if void returns `Collections.EMPTY_LIST`. Returns a flat list with no duplicates if this foreign key constraint is held by a node that is a list or under a list. That is, the returned list does not contain other lists of records if this foreign key constraint is defined by a node embedded in multiple lists.
    Throws:
      `IllegalArgumentException` - if the current node is not an aggregated list, nor under an aggregated list.
      `UnsupportedOperationException` - if the current table is a history table.
    Since:
      5.2.3
    See Also:
      - `getLinkedRecords(Adaptation)`
      - `SchemaNodeExplicitRelationship.getResult(Adaptation, com.orchestranetworks.service.Session)`