Package com.onwbp.adaptation

# Interface AdaptationTable

public interface AdaptationTable
An instance of this class holds the records of a table node, declared as `osd:table` in the data model. See Tables, filters and selection nodes for more information on declaring tables.

The dataset that contains the table is called the container dataset. A table is accessed from its container dataset by calling method `ReadContext.getTable(Path)`.

All the records of a table are represented by the class `Adaptation`. As such, they benefit from inheritance features, if dataset inheritance is enabled.

See Also:
  - `Request`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PrimaryKey`
  `computePrimaryKey(Adaptation anOccurrence)`
  Returns the same result as `Adaptation.getOccurrencePrimaryKey()`.
  `PrimaryKey`
  `computePrimaryKey(ValueContext aContext)`
  `PrimaryKey`
  `computePrimaryKey(Object[] primaryKeyValues)`
  Returns the `PrimaryKey` object that corresponds to the specified raw values.
  `Request`
  `createRequest()`
  Creates a new request for this table.
  `RequestResult`
  `createRequestResult(String aPredicate)`
  Returns the `RequestResult` for the specified predicate.
  `RequestResult`
  `createRequestResult(String aPredicate, RequestSortCriteria sortCriteria)`
  Returns the `RequestResult` for the specified predicate and sort criteria.
  `Adaptation`
  `getContainerAdaptation()`
  Returns the dataset that contains this table.
  `AdaptationTable`
  `getHistory()`
  Returns the corresponding history table; returns `null` if history is not activated.
  `Date`
  `getLastModificationDate()`
  Retrieves the date of the most recent modification operation performed on the table.
  `Path[]`
  `getPrimaryKeySpec()`
  Returns the paths of the data model nodes that compose the primary key of this table.
  `AdaptationName`
  `getRootKey()`
  Deprecated.
  Does not work for mapped tables.
  `SchemaNode`
  `getTableNode()`
  Returns the node of the table, which is a terminal node, in the dataset.
  `SchemaNode`
  `getTableOccurrenceRootNode()`
  Returns the root node that defines the record structure.
  `Path`
  `getTablePath()`
  Returns the path of the container node.
  `ValidationReport`
  `getValidationReport()`
  Returns an up-to-date validation report associated with this table.
  `ValidationReport`
  `getValidationReport(boolean ensureActivation)`
  Returns an up-to-date validation report associated with this table.
  `ValidationReport`
  `getValidationReport(boolean ensureActivation, boolean updateValidationReport)`
  Returns the validation report associated with this table.
  `ValidationReport`
  `getValidationReport(ValidationSpec aSpec)`
  Returns the validation report associated with this table according to the specified properties.
  `boolean`
  `isPrimaryKeyComplete(ValueContext aContext)`
  Returns `false` if at least one field in the primary key in the specified context is not set.
  `Adaptation`
  `lookupAdaptationByName(AdaptationName aName)`
  Returns the record based on the name specified; returns `null` if no record by that name exists.
  `Adaptation`
  `lookupAdaptationByPrimaryKey(PrimaryKey aKey)`
  Returns the record specified by its primary key.
  `Adaptation`
  `lookupAdaptationByPrimaryKey(PrimaryKey aKey, boolean includeOcculting)`
  Returns the record specified by its primary key.
  `Adaptation`
  `lookupAdaptationByPrimaryKey(ValueContext aContext)`
  Returns the record that has its primary key specified by the specified context.
  `Adaptation`
  `lookupAdaptationByPrimaryKey(ValueContext aContext, boolean includeOcculting)`
  Returns the record specified by its primary key.
  `Adaptation`
  `lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey, String aPredicateExpression)`
  Returns the first record that matches the specified XPath predicate, `null` if no such record exists.
  `Adaptation`
  `lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey, String aPredicateExpression, boolean includeOcculting)`
  Returns the first record that matches the specified XPath predicate, `null` if no such record exists.
  `Adaptation`
  `lookupFirstRecordMatchingPredicate(String aPredicateExpression)`
  Returns the first record that matches the specified XPath predicate, `null` if no such record exists.
  `void`
  `resetValidationReport()`
  Resets the validation report of this table.
  `List<Adaptation>`
  `selectOccurrences(String aPredicateExpression)`
  Returns a list of records for the specified predicate.
  `List<Adaptation>`
  `selectOccurrences(String aPredicate, RequestSortCriteria sortCriteria)`
  Returns a list of records for the specified predicate and sort criteria.
  `String`
  `toPublicReference()`
  Returns a `String` that identifies the table (composed of the dataset reference and table path).

- ## Method Details

  - ### toPublicReference

    String toPublicReference()
    Returns a `String` that identifies the table (composed of the dataset reference and table path).

  - ### lookupAdaptationByPrimaryKey

    Adaptation lookupAdaptationByPrimaryKey(ValueContext aContext)
    Returns the record that has its primary key specified by the specified context. Returns `null` if it does not exist or is in occulting mode.
    See Also:
      - `lookupAdaptationByPrimaryKey(ValueContext, boolean)`

  - ### lookupAdaptationByPrimaryKey

    Adaptation lookupAdaptationByPrimaryKey(ValueContext aContext, boolean includeOcculting)
    Returns the record specified by its primary key. Returns `null` if:
    - the record does not exist in this table or in any ancestor tables, or
    - the record with the key specified is in occulting mode and `includeOcculting` is `false`.

    Note: The record that is returned may have been inherited from an ancestor table.

    Parameters:
      `aContext` - Context that specifies the primary key of the record to look up.
      `includeOcculting` - If `true`, a record in occulting mode can be returned. If `false`, `null` will be returned if the record with the specified primary key is in occulting mode.
    See Also:
      - `Adaptation.isOccurrenceOcculting()`

  - ### lookupAdaptationByPrimaryKey

    Adaptation lookupAdaptationByPrimaryKey(PrimaryKey aKey)
    Returns the record specified by its primary key. Returns `null` if it the record does not exist or if it is in occulting mode.

    To directly retrieve the record from a foreign key value in a given context, it is recommended to invoke the method `SchemaFacetTableRef.getLinkedRecord(ValueContext)` instead.

    See Also:
      - `SchemaFacetTableRef.getLinkedRecord(ValueContext)`

  - ### lookupAdaptationByPrimaryKey

    Adaptation lookupAdaptationByPrimaryKey(PrimaryKey aKey, boolean includeOcculting)
    Returns the record specified by its primary key. Returns `null` if:
    - the record does not exist in this table or any ancestor tables, or
    - the record with the key specified is in occulting mode and `includeOcculting` is `false`.

    To directly retrieve the record from a foreign key value in a given context, it is recommended to invoke the method `SchemaFacetTableRef.getLinkedRecord(ValueContext)` instead.

    Parameters:
      `aKey` - Identity of the record to look up.
      `includeOcculting` - If `true`, a record in occulting mode can be returned. If `false`, `null` will be returned if the record with the specified primary key is in occulting mode.
    See Also:
      - `Adaptation.isOccurrenceOcculting()`
      - `SchemaFacetTableRef.getLinkedRecord(ValueContext)`

  - ### lookupFirstRecordMatchingPredicate

    Adaptation lookupFirstRecordMatchingPredicate(String aPredicateExpression)
    Returns the first record that matches the specified XPath predicate, `null` if no such record exists.

    This method is equivalent to:

    >      AdaptationTable.lookupFirstRecordMatchingPredicate(
    >             false,
    >             aPredicateExpression,
    >             false);

    Since:
      5.4.3
    See Also:
      - `lookupFirstRecordMatchingPredicate(boolean, String, boolean)`

  - ### lookupFirstRecordMatchingPredicate

    Adaptation lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey, String aPredicateExpression)
    Returns the first record that matches the specified XPath predicate, `null` if no such record exists.

    This method is equivalent to:

    >      AdaptationTable.lookupFirstRecordMatchingPredicate(
    >             checkActualPrimaryKey,
    >             aPredicateExpression,
    >             false);

    Since:
      5.4.3
    See Also:
      - `lookupFirstRecordMatchingPredicate(boolean, String, boolean)`

  - ### lookupFirstRecordMatchingPredicate

    Adaptation lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey, String aPredicateExpression, boolean includeOcculting)
    Returns the first record that matches the specified XPath predicate, `null` if no such record exists.

    For example, for the predicate `./name='Smith'`, this method would return the first record (in primary key order) with its field 'name' equal to "Smith", or `null` if none exists.

    If the argument `checkActualPrimaryKey` is `true`, the predicate must specify the value of each primary key field. Using this type of predicate allows for a much faster resolution.

    Throws:
      `IllegalArgumentException` - if one of the specified arguments is not defined.
      `IllegalArgumentException` - if the specified `Adaptation` is not a dataset.
      `IllegalArgumentException` - if `checkActualPrimaryKey` is `true` and the specified XPath expression argument is not a primary key expression.
      `MalformedXPathExpressionException` - if the specified XPath expression is not syntactically correct.
      `PathAccessException` - if the extracted table path expression does not reference an existing table node in the underlying structure.
    Since:
      5.4.3
    See Also:
      - Supported XPath syntax
      - `XPathExpressionHelper.lookupFirstRecordMatchingXPath(boolean, Adaptation, String, boolean)`

  - ### computePrimaryKey

    PrimaryKey computePrimaryKey(Adaptation anOccurrence)
    Returns the same result as `Adaptation.getOccurrencePrimaryKey()`.

  - ### computePrimaryKey

    PrimaryKey computePrimaryKey(ValueContext aContext)

  - ### computePrimaryKey

    PrimaryKey computePrimaryKey(Object[] primaryKeyValues)
    Returns the `PrimaryKey` object that corresponds to the specified raw values.
    Parameters:
      `primaryKeyValues` - values of the primary key fields. They must be in the same order as the fields declared in in the `osd:table/primaryKeys` element.
    Throws:
      `IllegalArgumentException` - if either the argument or the `osd:table/primaryKeys` element is `null`, if the specified array does not have the same length as the `osd:table/primaryKeys` element, or if a value in the argument is not of the expected type.
      `ClassCastException` - if a value in the specified array is not of the expected Java type.
    See Also:
      - `SchemaNode.getTablePrimaryKeyNodes()`
      - `SchemaNode.getTablePrimaryKeyValues(String)`
      - `SchemaFacetTableRef.getLinkedRecord(ValueContext)`

  - ### isPrimaryKeyComplete

    boolean isPrimaryKeyComplete(ValueContext aContext)
    Returns `false` if at least one field in the primary key in the specified context is not set.

  - ### getPrimaryKeySpec

    Path[] getPrimaryKeySpec()
    Returns the paths of the data model nodes that compose the primary key of this table.

  - ### getTableOccurrenceRootNode

    SchemaNode getTableOccurrenceRootNode()
    Returns the root node that defines the record structure.
    See Also:
      - `getTableNode()`

  - ### getTableNode

    SchemaNode getTableNode()
    Returns the node of the table, which is a terminal node, in the dataset.
    See Also:
      - `getTableOccurrenceRootNode()`
      - `SchemaNode.isTableNode()`

  - ### getContainerAdaptation

    Adaptation getContainerAdaptation()
    Returns the dataset that contains this table.

  - ### getLastModificationDate

    Date getLastModificationDate()
    Retrieves the date of the most recent modification operation performed on the table. A modification operation is any record creation, update, or deletion within the table. If the table is empty, and never contained any records, the method instead returns the creation date of the container dataspace.
    Since:
      6.0.6

  - ### getHistory

    AdaptationTable getHistory()
    Returns the corresponding history table; returns `null` if history is not activated.

    The returned table has the same structure as this table, except:

    1. the primary key has a first field specifying the transaction, `ebx-technical/tx_id`, then has the functional primary key fields;
    2. the nodes ignored by the history are not present (for instance, computed values and fields explicitly disabling history);
    3. some transaction-related fields are added, such as `ebx-technical/tx_id`, `ebx-technical/dataspace`, `ebx-technical/timestamp`, `ebx-technical/op`, and `ebx-technical/user`. The paths of these fields are also available in the user interface;
    4. an additional operation fields is added for each historized functional field. Operation fields are defined under the group `ebx-operationCode`. For example, a historized functional field `name` will be associated with an operation field `ebx-operationCode/name`. For more information regarding the values of these fields, see Operation field values.
    Since:
      5.2.0
    See Also:
      - History
      - `Adaptation.isHistory()`
      - `SchemaNode.isHistoryDisabled()`

  - ### getTablePath

    Path getTablePath()
    Returns the path of the container node.

  - ### getRootKey

    @Deprecated AdaptationName getRootKey()
    Deprecated.
    Does not work for mapped tables.
    Returns the key to the virtual root record of this table. This technical record is not seen by the end user, but is useful for managing a hierarchical set of all records in this table and its descendants, for example for performing a deletion.

    Each table has a unique virtual root record that exists even if the table is empty. The virtual root record itself is not persisted, and does not support modifications.

    Returns:
      the key of the virtual root record of this table.
    See Also:
      - `AdaptationHome.findAllDescendants(Adaptation)`
      - `ProcedureContext.doDelete(AdaptationName, boolean)`

  - ### lookupAdaptationByName

    Adaptation lookupAdaptationByName(AdaptationName aName)
    Returns the record based on the name specified; returns `null` if no record by that name exists.

  - ### createRequest

    Request createRequest()
    Creates a new request for this table.

  - ### createRequestResult

    RequestResult createRequestResult(String aPredicate, RequestSortCriteria sortCriteria)
    Returns the `RequestResult` for the specified predicate and sort criteria.

    This method is equivalent to the method `selectOccurrences(String)`.

    Performance considerations: If the specified predicate must be often reused by multiple `Request` objects, it is recommended to use a cached filter. Parameterized expressions also help reuse.

    Parameters:
      `aPredicate` - Simplified XPath expression of a filter to be applied to the table records. If `null`, no filter is applied.
      `sortCriteria` - Criteria for sorting the result. If `null`, no sort order is applied.
    See Also:
      - `Request.setXPathFilter(XPathFilter)`
      - `Request.setSortCriteria(RequestSortCriteria)`

  - ### createRequestResult

    RequestResult createRequestResult(String aPredicate)
    Returns the `RequestResult` for the specified predicate.

    This method is equivalent to the method `selectOccurrences(String)`.

    Performance considerations: If the specified predicate must be often reused by multiple `Request` objects, it is recommended to use a cached filter. Parameterized expressions also help reuse.

    Parameters:
      `aPredicate` - Simplified XPath expression of a filter to apply to the table records. If `null`, no filter is applied.
    See Also:
      - `Request.setXPathFilter(XPathFilter)`

  - ### selectOccurrences

    List<Adaptation> selectOccurrences(String aPredicate, RequestSortCriteria sortCriteria)
    Returns a list of records for the specified predicate and sort criteria.

    This method is equivalent to the method `createRequestResult(String)`, but is not recommended for a large number of results.

    Performance considerations: If the specified predicate must be often reused by multiple `Request` objects, it is recommended to use a cached filter. Parameterized expressions also help reuse.

    Parameters:
      `aPredicate` - Simplified XPath expression of a filter to apply on the table records. If `null`, no filter is applied.
      `sortCriteria` - Criteria for sorting the result. If `null`, no sort order is applied.
    Returns:
      a `List` of records, where each element is an `Adaptation`.
    See Also:
      - XPath supported syntax
      - `Request.setXPathFilter(XPathFilter)`

  - ### selectOccurrences

    List<Adaptation> selectOccurrences(String aPredicateExpression)
    Returns a list of records for the specified predicate.

    This method is equivalent to the method `createRequestResult(String)`, but is not recommended for a large number of results.

    Performance considerations: If the specified predicate will often be reused by multiple `Request` objects, it is recommended to use a cached filter. Parameterized expressions also help reuse.

    Parameters:
      `aPredicateExpression` - Simplified XPath expression of a filter to apply on table records. If `null`, no filter is applied.
    Returns:
      a `List` of records, where each element is an `Adaptation`.
    See Also:
      - `Request.setXPathFilter(XPathFilter)`

  - ### getValidationReport

    ValidationReport getValidationReport()
    Returns an up-to-date validation report associated with this table.

    This method is equivalent to:

    > `AdaptationTable.getValidationReport(true);`

    See Also:
      - `Adaptation.getValidationReport()`
      - `getValidationReport(boolean)`
      - `getValidationReport(boolean, boolean)`

  - ### getValidationReport

    ValidationReport getValidationReport(ValidationSpec aSpec)
    Returns the validation report associated with this table according to the specified properties. The validation takes into account all the various constraints defined by the underlying data model.

    The report returned by this method is not affected by updates performed after this method is called. The rules for ensuring that data in EBX® remains valid (regarding possible concurrent updates) are explained in the section Consistency and validation.

    Limitation: this method should not be called inside a programmatic constraint or a value function with the argument `updateValidationReport` set to `true`, since the computation of an up-to-date validation report is not supported during a validation process and may cause inconsistent results. In this case, the method `AdaptationTable.getValidationReport(..., false)` should be used instead inside a programmatic constraint or a value function.

    Limitation: a validation report is only valid as long as the dataspace remains open. If the report is accessed in any way after the dataspace has been closed or deleted, a runtime exception may be thrown.

    Throws:
      `IllegalStateException` - if the current table holds data that is not subject to validation. This is the case, for instance, for the history.
    Since:
      5.9.0
    See Also:
      - `ValidationSpec`

  - ### getValidationReport

    ValidationReport getValidationReport(boolean ensureActivation)
    Returns an up-to-date validation report associated with this table. The validation takes into account all the various constraints defined by the underlying data model.

    The report returned by this method is not affected by updates performed after this method is called. The rules for ensuring that data in EBX® remains valid (regarding possible concurrent updates) are explained in section Consistency and validation.

    This method is equivalent to:

    > `AdaptationTable.getValidationReport(ensureActivation, true);`

    Parameters:
      `ensureActivation` - if `true`, the validation also checks that the dataset is `activated` (it adds an error if this is not the case).
    See Also:
      - `Adaptation.getValidationReport(boolean)`
      - `getValidationReport()`
      - `getValidationReport(boolean, boolean)`
      - `ValidationSpec`

  - ### getValidationReport

    ValidationReport getValidationReport(boolean ensureActivation, boolean updateValidationReport)
    Returns the validation report associated with this table.

    This method is equivalent to:

         ValidationSpec spec = new ValidationSpec();
         spec.setEnsureActivation(ensureActivation);
         spec.setRefreshPolicy(updateValidationReport ? RefreshPolicy.UP_TO_DATE : RefreshPolicy.AS_IS);

         AdaptationTable.getValidationReport(spec);

    See Also:
      - `getValidationReport(ValidationSpec)`
      - `ValidationSpec`

  - ### resetValidationReport

    void resetValidationReport()
    Resets the validation report of this table.
    Since:
      5.9.0
    See Also:
      - `Adaptation.resetValidationReport(boolean)`