Package com.onwbp.adaptation

# Interface Adaptation

All Superinterfaces:
  `ReadContext`

public interface Adaptation extends ReadContext
Provides a read-only access facade to data values in EBX®.

An `Adaptation` represents either a dataset or a table record.

Datasets make up dataspaces, which serve to isolate or organize datasets, and are represented by the class `AdaptationHome` in the Java API.

Note: In versions before 5.0, a dataset was known as an adaptation instance, and a record was sometimes referred to as an occurrence.

### Accessing values

Values in a dataset or record are organized in a structure that conforms to an underlying data model (XML Schema Document). Each value is accessed using a `path`. For improved reliability and performance, it is recommended to use a path generated using Java constants (see Java bindings).

Note: Only terminal nodes hold actual values.

The interface `ValueContext` provides access functionality that is equivalent to that of `Adaptation`. However, absolute paths are not interpreted the same way by the two interfaces:

- For a `ValueContext`, the absolute path always begins at the root of the dataset, even if it is a table record.
- For an `Adaptation`, the absolute path begins at the root node of the dataset or record. That is, if it is a record, the absolute path begins at the record root and not at the root of its dataset.

### Inheritance

See Inheritance and value resolution for information.

See Also:
  - `createValueContext()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default Query<Tuple>`
  `createQuery(String aSqlString)`
  Creates a query over this dataset from the specified SQL string.
  `QueryBuilder`
  `createQueryBuilder()`
  Returns a query builder initialized with this dataset for unqualified tables.
  `ValueContext`
  `createValueContext()`
  Returns a `ValueContext` for this `Adaptation`.
  `boolean`
  `equals(Object object)`
  `boolean`
  `equalsToAdaptation(Adaptation other)`
  Indicates whether the other specified dataset or record is "equal to" this one, that is, it has the `same reference` in the same `dataspace`.
  `Object`
  `get(Path aPath)`
  Returns the value of the specified node.
  `Object`
  `get(SchemaNode aNode)`
  Returns the value of the specified node.
  `AdaptationName`
  `getAdaptationName()`
  Returns the name that uniquely identifies this dataset or record in the current dataspace.
  `Adaptation`
  `getContainer()`
  This method returns the dataset that contains this adaptation.
  `AdaptationTable`
  `getContainerTable()`
  The method returns the table that contains this adaptation.
  `UserReference`
  `getCreator()`
  Returns the creator of this dataset or record.
  `AdaptationReference`
  `getDatasetReference()`
  Returns the reference that uniquely identifies this dataset in its dataspace.
  `String`
  `getDescription(Locale aLocale)`
  Returns the description corresponding to the given locale.
  `AdaptationHome`
  `getHome()`
  Returns the dataspace which contains this dataset or record.
  `String`
  `getLabel(Session aSession)`
  Returns the label of the dataset or record corresponding to the locale in the specified session.
  `String`
  `getLabel(Locale aLocale)`
  Returns the label of the dataset or record corresponding to the specified locale.
  `String`
  `getLabelOrName(Session aSession)`
  Returns the label of the dataset or record corresponding to the locale in the specified session.
  `String`
  `getLabelOrName(Locale aLocale)`
  Returns the label of the dataset or record corresponding to the specified locale.
  `long`
  `getLastTransactionId()`
  Returns the identifier of the last transaction in which this dataset or record has been modified.
  `UserReference`
  `getLastUser()`
  Returns the last user who modified this dataset or record.
  `String`
  `getModuleName()`
  Returns the name of the module that holds the data model document.
  `DefinitionMode`
  `getOccurrenceDefinitionMode()`
  Returns the definition mode of this record.
  `PrimaryKey`
  `getOccurrencePrimaryKey()`
  Returns the primary key of this record.
  `Profile`
  `getOwner()`
  Returns the profile that owns the current dataset.
  `Adaptation`
  `getParent()`
  Returns the parent of the current dataset or record.
  `SchemaLocation`
  `getSchemaLocation()`
  Returns the location of the data model document.
  `SchemaNode`
  `getSchemaNode()`
  Returns the root data model node of this dataset or record.
  `Date`
  `getTimeOfCreation()`
  Returns the creation time of this dataset or record.
  `Date`
  `getTimeOfLastModification()`
  Returns the time of the last modification of this dataset or record.
  `AdaptationReference`
  `getTreeReference()`
  Returns the name that uniquely identifies the tree of this dataset in its dataspace.
  `Adaptation`
  `getUpToDateInstance()`
  Returns an object that is up-to-date with respect to the underlying persistent entity (dataset or table record).
  `ValidationReport`
  `getValidationReport()`
  Returns an up-to-date validation report of this dataset or record.
  `ValidationReport`
  `getValidationReport(boolean ensureActivation)`
  Returns an up-to-date validation report of this dataset or record.
  `ValidationReport`
  `getValidationReport(boolean ensureActivation, boolean updateValidationReport)`
  Returns the validation report of this dataset or record.
  `ValidationReport`
  `getValidationReport(ValidationSpec aValidationSpec)`
  Returns the validation report of this dataset or record according to the specified properties.
  `ValidationReport`
  `getValidationReportForNode(SchemaNode aNode)`
  Returns an up-to-date validation report of the specified node.
  `ValidationReport`
  `getValidationReportForNode(SchemaNode aNode, boolean ensureActivation)`
  Returns an up-to-date validation report of the specified node in the current dataset or record.
  `ValidationReport`
  `getValidationReportForNode(SchemaNode aNode, boolean ensureActivation, boolean updateValidationReport)`
  Returns the validation report of the specified node in the current dataset or record.
  `ValidationReport`
  `getValidationReportForNode(SchemaNode aNode, ValidationSpec aValidationSpec)`
  Returns a validation report of the specified node according to the specified properties.
  `Object`
  `getValueWithoutResolution(Path aPath)`
  Returns the value at the path specified, which is either inherited, `null`, or a specific object.
  `boolean`
  `hasSevereError()`
  Returns `true` if the current dataset has severe errors that prevent access to the data.
  `boolean`
  `isActivated()`
  Returns `true` if this dataset or record is activated.
  `boolean`
  `isDeleted()`
  Returns `true` if this dataset or record has become unavailable.
  `boolean`
  `isHistory()`
  Returns `true` if this is a table record AND the dataset that contains it is a history dataset, or this is a dataset AND it is a history dataset.
  `boolean`
  `isOccurrenceHidden()`
  Returns `true` if this is a table record that is in occulting mode or in editing-delete state.
  `boolean`
  `isOccurrenceInheriting()`
  Returns `true` if this is a table record in inheritance mode.
  `boolean`
  `isOccurrenceOcculting()`
  Returns `true` if this is a table record in occulting mode.
  `boolean`
  `isRootAdaptation()`
  Returns `true` if this is a root dataset, meaning it has no parent dataset.
  `boolean`
  `isSchemaDefinitionCompliant(boolean ensureActivation)`
  Returns `true` if the validation report of this dataset or record has no errors.
  `boolean`
  `isSchemaInstance()`
  Returns `true` if this is a dataset, not a table record.
  `boolean`
  `isTableOccurrence()`
  Returns `true` if this is a table record, not a dataset.
  `boolean`
  `matches(String anXPathPredicateExpression)`
  For a table record, this method returns whether the XPath predicate matches the record.
  `boolean`
  `matches(String anXPathPredicateExpression, Locale locale)`
  For a table record, this method returns whether the localized XPath predicate matches the record.
  `void`
  `resetValidationReport(boolean resetChildren)`
  Resets the validation report of this dataset.
  `void`
  `toHtmlString(Writer aWriter)`
  For debugging purposes, adds an HTML representation to the writer specified.
  `String`
  `toPublicReference()`
  Returns a string that identifies this object in the current dataspace, from the user's point of view.
  `String`
  `toString()`
  `String`
  `toXPathExpression()`
  For a table record, this method returns the XPath expression that selects it in its dataset.
  `String`
  `toXPathPredicateString()`
  For a table record, this method returns the XPath predicate that selects it in its table.

  ### Methods inherited from interface com.onwbp.adaptation.ReadContext

  `get_boolean, get_int, getDate, getList, getResourcePathInModule, getResourcePathWithModule, getString, getTable, isEndUserDebug`

- ## Method Details

  - ### getAdaptationName

    AdaptationName getAdaptationName()
    Returns the name that uniquely identifies this dataset or record in the current dataspace.

  - ### getDatasetReference

    AdaptationReference getDatasetReference()
    Returns the reference that uniquely identifies this dataset in its dataspace.

    If this is a table record, then the returned reference is the one of its container dataset.

    Since:
      5.9.0
    See Also:
      - `getOccurrencePrimaryKey()`

  - ### getTreeReference

    AdaptationReference getTreeReference()
    Returns the name that uniquely identifies the tree of this dataset in its dataspace. All the datasets in a tree share the same tree reference, which is the reference of the root dataset.

    If this is a table record, then the returned reference is the one of its container dataset's tree.

    See Also:
      - `getDatasetReference()`

  - ### getOccurrencePrimaryKey

    PrimaryKey getOccurrencePrimaryKey()
    Returns the primary key of this record.

    If this is a dataset, not a table record, the method returns `null`.

    See Also:
      - `getDatasetReference()`

  - ### getHome

    AdaptationHome getHome()
    Returns the dataspace which contains this dataset or record.

  - ### isSchemaInstance

    boolean isSchemaInstance()
    Returns `true` if this is a dataset, not a table record.

    This method returns the opposite result of `isTableOccurrence()`.

  - ### isTableOccurrence

    boolean isTableOccurrence()
    Returns `true` if this is a table record, not a dataset.

    This is the opposite of `isSchemaInstance()`.

    See Also:
      - `isOccurrenceInheriting()`
      - `isOccurrenceOcculting()`

  - ### getContainerTable

    AdaptationTable getContainerTable()
    The method returns the table that contains this adaptation.

    If this instance is a dataset this method returns an empty table. In this case a request cannot be executed from this empty table since it does not define any primary key.

  - ### getContainer

    Adaptation getContainer()
    This method returns the dataset that contains this adaptation.

    If this is a dataset, it returns an adaptation equivalent to itself.

  - ### getOwner

    Profile getOwner()
    Returns the profile that owns the current dataset.

    If no owner is specified for this dataset, it returns the profile that owns its parent. It never returns `null`.

  - ### getCreator

    UserReference getCreator()
    Returns the creator of this dataset or record.

    May return `null` if the record has been created before 5.7.0.

    Since:
      5.7.0
    See Also:
      - `SchemaMetadataConstants`

  - ### getTimeOfCreation

    Date getTimeOfCreation()
    Returns the creation time of this dataset or record.
    See Also:
      - `SchemaMetadataConstants`

  - ### getTimeOfLastModification

    Date getTimeOfLastModification()
    Returns the time of the last modification of this dataset or record.

    Current limitation: if this is a dataset, not a table record, the time returned does not take into account modifications performed on contained table records (dataset time is only updated for local content modifications).

    See Also:
      - `getLastUser()`
      - `SchemaMetadataConstants`

  - ### getLastTransactionId

    long getLastTransactionId()
    Returns the identifier of the last transaction in which this dataset or record has been modified.

    Current limitation: if this is a dataset, not a table record, the transaction id returned does not take into account modifications performed on contained table records (dataset's last transaction id is only updated for local content modifications).

    Since:
      6.1.3
    See Also:
      - `DifferenceHelper.compareDatasetByTransactionID(Adaptation, boolean, long, long)`
      - `DifferenceHelper.compareRecordByTransactionID(Adaptation, boolean, long, long)`

  - ### getLastUser

    UserReference getLastUser()
    Returns the last user who modified this dataset or record.

    Current limitation: if this is a dataset, not a table record, the last user is the user that has modified dataset content locally (if another user has made an update within a table, it is not taken into account).

    See Also:
      - `getTimeOfLastModification()`
      - `SchemaMetadataConstants`

  - ### isActivated

    boolean isActivated()
    Returns `true` if this dataset or record is activated.

    This state impacts validation:

    - disabled:
      the disabled state means that the validation of the dataset or record will accept undefined values on "mandatory" elements (elements with `minOccurs="1"` in the data model). This feature allows for internal EBX® inheritance. It holds common values that will be inherited by child datasets, while other values often remain undefined. Note: A disabled dataset or record should not be exported to or used by external systems, as it may be incomplete. Note: This does not affect the validation of lists (elements with `maxOccurs` greater than 1). That means, an empty list with `minOccurs="1"` will result in an error, notwithstanding whether the dataset or record has been activated or not.
    - activated: the activated state means that the dataset or record is fully validated, including checking that all "mandatory" elements are present. An activated and successfully validated dataset or record can be safely used by external systems.
    See Also:
      - `getValidationReport(boolean)`

  - ### isDeleted

    boolean isDeleted()
    Returns `true` if this dataset or record has become unavailable. This may happen if:
    - the dataset or record has been deleted,
    - its dataspace has been closed, or
    - for a table record, its table has been removed from the data model.

  - ### getUpToDateInstance

    Adaptation getUpToDateInstance()
    Returns an object that is up-to-date with respect to the underlying persistent entity (dataset or table record). It returns `null` if the entity has been persistently deleted or has become unavailable due to its dataspace being closed or due to the table record's container being deleted.

    A dataset or record object can become obsolete for several reasons even if its entity has not been deleted, including a concurrent update, a `data model refresh`, etc. Thus, it is generally not recommended for the client application to hold a dataset or record object for a long period of time, or to regularly invoke this method. The safest way is to put the code in a "SERIALIZABLE" isolation level. For more information, see the section Concurrency and isolation levels).

    This method has the same result as `dataset.getHome().findAdaptationOrNull(dataset.getAdaptationName())`.

  - ### get

    Object get(Path aPath) throws PathAccessException
    Description copied from interface: `ReadContext`
    Returns the value of the specified node. Returns `null` if the value of the node is undefined.

    If this method is called on an `Adaptation`, a lookup mechanism is used to retrieve the value (see Inheritance and value resolution).

    ##### Access and mapping rules

    The access and mapping rules between XML Schema and Java are described in the chapter Mapping to Java.

    Specified by:
      `get` in interface `ReadContext`
    Throws:
      `PathAccessException` - if `aPath` does not refer to an existing node in the underlying type tree structure.
    See Also:
      - `getValueWithoutResolution(Path)`

  - ### get

    Object get(SchemaNode aNode) throws PathAccessException
    Description copied from interface: `ReadContext`
    Returns the value of the specified node.

    This method is equivalent to `get(aNode.getPathInAdaptation())`, but is slightly more efficient.

    Specified by:
      `get` in interface `ReadContext`
    Throws:
      `PathAccessException`

  - ### getValueWithoutResolution

    Object getValueWithoutResolution(Path aPath)
    Returns the value at the path specified, which is either inherited, `null`, or a specific object. Specifically:
    1. If the actual value is inherited, it returns `AdaptationValue.INHERIT_VALUE`.
    2. If the actual value is not inherited and is not `null`, it returns the object defined (it must be an instance of the node's type).
    3. If the actual value is set to `null` (not inherited), it returns `null`.

    See Inheritance and value resolution for more information.

    Parameters:
      `aPath` - location of the node. Only absolute paths are supported and they must specify a `terminal node`. If this is a table record, the path begins at the root of the record.
    Throws:
      `PathAccessException` - If no node exists for the specified path.
    See Also:
      - `ReadContext.get(Path)`

  - ### createValueContext

    ValueContext createValueContext()
    Returns a `ValueContext` for this `Adaptation`.

    This context is standard regarding path resolution: an absolute path is always considered as the dataset's root node, even if this is a table record.

  - ### isSchemaDefinitionCompliant

    boolean isSchemaDefinitionCompliant(boolean ensureActivation)
    Returns `true` if the validation report of this dataset or record has no errors.

    This method is equivalent to:

         ValidationReport report = this.getValidationReport(ensureActivation, true);
         if (report.hasItemsOfSeverityOrMore(Severity.ERROR))
                return false;
         else
                return true;

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

  - ### createQuery

    default Query<Tuple> createQuery(String aSqlString)
    Creates a query over this dataset from the specified SQL string.

    If the current object is a table record, the dataset that is used is its dataset.

    Parameters:
      `aSqlString` - the SQL string that will be used to create the query object.
    Returns:
      a structurally valid query object.
    Throws:
      `RuntimeException` - if the SQL query is not valid (e.g., it contains syntax errors, it references missing tables, missing columns, etc.).
    Since:
      6.0.0
    See Also:
      - `QueryBuilder.build(String)`

  - ### createQueryBuilder

    QueryBuilder createQueryBuilder()
    Returns a query builder initialized with this dataset for unqualified tables. This means that any unqualified tables appearing in the queries created by the builder will be resolved against this dataset.

    If the current object is a table record, the dataset that is used is its dataset.

    Returns:
      a query builder object.
    Since:
      6.0.0

  - ### getValidationReport

    ValidationReport getValidationReport()
    Returns an up-to-date validation report of this dataset or record.

    This method is equivalent to:

    > `Adaptation.getValidationReport(true, true);`

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

  - ### getValidationReport

    ValidationReport getValidationReport(boolean ensureActivation)
    Returns an up-to-date validation report of this dataset or record.

    This method is equivalent to:

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

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

  - ### getValidationReport

    ValidationReport getValidationReport(boolean ensureActivation, boolean updateValidationReport)
    Returns the validation report of this dataset or record.

    This method is equivalent to:

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

         Adaptation.getValidationReport(spec);

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

  - ### getValidationReport

    ValidationReport getValidationReport(ValidationSpec aValidationSpec)
    Returns the validation report of this dataset or record according to the specified properties.

    If this is a `dataset`, the validation takes into account all the constraints defined by the underlying data model.

    If this is a `table record`, all the constraints in the table declaration and the `record-level checks in the table controls` are taken into account.

    This method also returns the validation messages added by a `constraints on table` and related to this table record if the container table has been previously validated. However, if the state of a constraint on table is obsolete and if this constraint does not implement checks at record level, then the returned message(s) can be wrong; as a workaround an explicit validation of the container table must be done just before.

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

    If a validation message threshold is defined in the underlying data model of the container dataset, this threshold is applied to each constraint defined in the data model if this adaptation is a dataset. That is, the validation message threshold is ignored if this instance is a record. When the threshold is reached by a constraint, then the validation of the constraint is stopped and an error message is added to the validation report to indicate that the threshold has been reached for the constraint.

    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 `Adaptation.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.

    Important: existing persisted validation reports are not updated when validating a table record. That is, the container table or dataset must be explicitly validated to take into account in existing persisted validation reports the modifications that have been performed since the last validation.

    Since:
      5.9.0
    See Also:
      - `isSchemaDefinitionCompliant(boolean)`
      - `AdaptationHome.getValidationReportsMap(Severity)`
      - `isHistory()`
      - `AdaptationTable.getValidationReport(ValidationSpec)`
      - `ConstraintOnTableWithRecordLevelCheck`
      - `ValidationSpec`

  - ### getValidationReportForNode

    ValidationReport getValidationReportForNode(SchemaNode aNode)
    Returns an up-to-date validation report of the specified node.

    This method is equivalent to:

    > `Adaptation.getValidationReportForNode(aNode, true, true);`

    See Also:
      - `getValidationReportForNode(SchemaNode, boolean, boolean)`

  - ### getValidationReportForNode

    ValidationReport getValidationReportForNode(SchemaNode aNode, ValidationSpec aValidationSpec)
    Returns a validation report of the specified node according to the specified properties.

    The report returned by this method is not affected by updates done 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.

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

    Important: existing persisted validation reports are not updated when validating a node in a `table record`. That is, the container table or dataset must be explicitly validated to take into account in existing persisted validation reports the modifications that have been performed since the last validation.

    Parameters:
      `aNode` - the node whose validation result is to be returned.
    Returns:
      the validation report associated with the specified node. Note: if the node is `maxOccurs` > 1, the report will contain the messages of its elements.
    Throws:
      `IllegalArgumentException` - If the specified node is:
      - of a complex type (for a table, the method `AdaptationTable.getValidationReport()` must be used instead);
      - is not a node of the current dataset or record.
      - is under an aggregated list.
      `IllegalStateException` - if the current dataset or record holds data that is not subject to validation. This is the case, for instance, for the history.
    Since:
      5.9.0
    See Also:
      - `AdaptationTable.getValidationReport(ValidationSpec)`
      - `isHistory()`

  - ### getValidationReportForNode

    ValidationReport getValidationReportForNode(SchemaNode aNode, boolean ensureActivation)
    Returns an up-to-date validation report of the specified node in the current dataset or record.

    This method is equivalent to:

    > `Adaptation.getValidationReportForNode(aNode, ensureActivation, true);`

    See Also:
      - `AdaptationTable.getValidationReport()`

  - ### getValidationReportForNode

    ValidationReport getValidationReportForNode(SchemaNode aNode, boolean ensureActivation, boolean updateValidationReport)
    Returns the validation report of the specified node in the current dataset or record.

    This method is equivalent to:

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

         Adaptation.getValidationReportForNode(aNode, spec);

    See Also:
      - `getValidationReportForNode(SchemaNode, ValidationSpec)`
      - `ValidationSpec`

  - ### resetValidationReport

    void resetValidationReport(boolean resetChildren)
    Resets the validation report of this dataset.
    Parameters:
      `resetChildren` - if set to `true`, the validation reports of child datasets will also be reset.
    Throws:
      `UnsupportedOperationException` - if the current `Adaptation` is a record.
    Since:
      5.9.0
    See Also:
      - `AdaptationTable.resetValidationReport()`

  - ### getSchemaNode

    SchemaNode getSchemaNode() throws UnavailableContentError
    Returns the root data model node of this dataset or record.
    Throws:
      `UnavailableContentError` - If data model has errors.

  - ### getSchemaLocation

    SchemaLocation getSchemaLocation()
    Returns the location of the data model document.

  - ### hasSevereError

    boolean hasSevereError()
    Returns `true` if the current dataset has severe errors that prevent access to the data. This is the case when the data model has errors, or when some inter-dataset links do not comply with the model.

    Severe errors can be retrieved using the method `getValidationReport()`.

    As this method does not need to validate the dataset, it must be called instead of `Adaptation.getValidationReport().hasItemsOfSeverity(Severity.FATAL)`.

    Since:
      5.6.0
    See Also:
      - `UnavailableContentError`

  - ### getModuleName

    String getModuleName()
    Returns the name of the module that holds the data model document.
    See Also:
      - `getSchemaLocation()`
      - `SchemaLocation.getModuleName()`

  - ### getLabel

    String getLabel(Locale aLocale)
    Returns the label of the dataset or record corresponding to the specified locale.

    If this is a table record, the label is provided by the associated label renderer; if this is a dataset, the label is the associated documentation's label.

    Returns `null` if no label exists for the specified locale.

    Attention: When using this method, permissions are not checked on the fields used in the label. If the permissions should be checked, the method getLabel(Session) should be used instead.

  - ### getLabel

    String getLabel(Session aSession)
    Returns the label of the dataset or record corresponding to the locale in the specified session.

    If this is a table record, the label is provided by the associated label renderer; if this is a dataset, the label is the associated documentation's label.

    Returns `null` if no label exists for the specified locale.

    This method checks the permissions on the fields used in the label and returns the identifier of the adaptation if one or more fields are hidden.
    Since:
      6.1.1

  - ### getLabelOrName

    String getLabelOrName(Locale aLocale)
    Returns the label of the dataset or record corresponding to the specified locale.

    Returns the reference of the dataset or record if no label exists for the locale.

    Attention: When using this method, permissions are not checked on the fields used in the label. If the permissions should be checked, the method getLabelOrName(Session) should be used instead.

  - ### getLabelOrName

    String getLabelOrName(Session aSession)
    Returns the label of the dataset or record corresponding to the locale in the specified session.

    Returns the reference of the dataset or record if no label exists for the locale.

    This method checks the permissions on the fields used in the label and returns the identifier of the adaptation if one or more fields are hidden.
    Since:
      6.1.1

  - ### getDescription

    String getDescription(Locale aLocale)
    Returns the description corresponding to the given locale.

    If this is a table record, the returned description is always `null`; if this is a dataset, the associated documentation's description is returned.

    Returns `null` if no description exists for the specified locale.

  - ### isHistory

    boolean isHistory()
    Returns `true` if
    - this is a table record AND the dataset that contains it is a history dataset, or
    - this is a dataset AND it is a history dataset.
    Since:
      5.2.0
    See Also:
      - `AdaptationTable.getHistory()`

  - ### isRootAdaptation

    boolean isRootAdaptation()
    Returns `true` if this is a root dataset, meaning it has no parent dataset.

    If this is a table record, the method always returns `false`.

    See Also:
      - `getOccurrenceDefinitionMode()`
      - `getParent()`

  - ### getParent

    Adaptation getParent()
    Returns the parent of the current dataset or record.

    If this is a child dataset, this method returns the parent dataset, `null` if this is a `root dataset`. If this is a table record, this method returns:

    - `null`, if the container is a `root dataset`;
    - the record with the same primary key in the parent table (that is, the table with the same path in the parent dataset),
    - `null`, if such a record in the parent table is neither defined nor inherited;
    See Also:
      - `isRootAdaptation()`
      - `getOccurrenceDefinitionMode()`

  - ### getOccurrenceDefinitionMode

    DefinitionMode getOccurrenceDefinitionMode()
    Returns the definition mode of this record.

    If this is a dataset, not a table record, the method returns `null`.

    See Also:
      - `getParent()`

  - ### isOccurrenceInheriting

    boolean isOccurrenceInheriting()
    Returns `true` if this is a table record in inheritance mode.

    If this is a dataset, not a table record, this method always returns `false`. For a table record, it is equivalent to `DefinitionMode.isInherit()`.

    See Also:
      - `getParent()`
      - `getOccurrenceDefinitionMode()`

  - ### isOccurrenceOcculting

    boolean isOccurrenceOcculting()
    Returns `true` if this is a table record in occulting mode.

    If this is a dataset, not a table record, this method always returns `false`. For a table record, it is equivalent to `DefinitionMode.isOcculting()`.

    See Also:
      - `getParent()`
      - `getOccurrenceDefinitionMode()`

  - ### isOccurrenceHidden

    boolean isOccurrenceHidden()
    Returns `true` if this is a table record that is in occulting mode or in editing-delete state.

    If this is a dataset, not an record, the method always returns `false`.

    See Also:
      - `getOccurrenceDefinitionMode()`

  - ### equals

    boolean equals(Object object)
    Overrides:
      `equals` in class `Object`
    See Also:
      - `equalsToAdaptation(Adaptation)`

  - ### equalsToAdaptation

    boolean equalsToAdaptation(Adaptation other)
    Indicates whether the other specified dataset or record is "equal to" this one, that is, it has the `same reference` in the same `dataspace`.

  - ### toPublicReference

    String toPublicReference()
    Returns a string that identifies this object in the current dataspace, from the user's point of view.
    See Also:
      - `getAdaptationName()`

  - ### matches

    boolean matches(String anXPathPredicateExpression)
    For a table record, this method returns whether the XPath predicate matches the record.

    Example:

    > `record.matches("./boolean='true' and date-equal(./date,'2001-01-01')");`

    If this is a dataset, not a table record, the method always returns `false`.

  - ### matches

    boolean matches(String anXPathPredicateExpression, Locale locale)
    For a table record, this method returns whether the localized XPath predicate matches the record.

    Example:

    > `record.matches("osd:label(./localized_field)='A' and ./boolean='true'");`

    If this is a dataset, not a table record, the method always returns `false`.

  - ### toXPathExpression

    String toXPathExpression()
    For a table record, this method returns the XPath expression that selects it in its dataset.

    Example:

    > `/root/categoryX/tableY[pkey1="A01" and pkey2="666"]`

    If this is a dataset, not a table record, the method always returns "`/`" (root path).

    See Also:
      - `AdaptationTable.createRequestResult(String)`

  - ### toXPathPredicateString

    String toXPathPredicateString()
    For a table record, this method returns the XPath predicate that selects it in its table.

    Example:

    > `pkey1="A01" and pkey2="666"`

    If this is a dataset, not a table record, the method always returns `null`.

    See Also:
      - `toXPathExpression()`

  - ### toHtmlString

    void toHtmlString(Writer aWriter)
    Description copied from interface: `ReadContext`
    For debugging purposes, adds an HTML representation to the writer specified. The table hierarchically displays the values in this context.
    Specified by:
      `toHtmlString` in interface `ReadContext`

  - ### toString

    String toString()
    Overrides:
      `toString` in class `Object`