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:

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getTimeOfCreation

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

    • 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:

    • 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).

      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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

      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

      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

      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:

    • 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

      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:
      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • getModuleName

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

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • equals

      boolean equals(Object object)
      Overrides:
      equals in class Object
      See Also:

    • 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:

    • 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:

    • 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:

    • 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