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 Detail

      • getAdaptationName

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

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

      • getContainerTable

        AdaptationTable getContainerTable()
        If this is a record, the method returns the table that contains it; returns null if this is a dataset.

      • getContainer

        Adaptation getContainer()
        If this is a table record, the method returns the dataset that contains it; it returns null if this is a dataset.

      • 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

      • 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

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

      • 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​(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,
                                            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:
        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()

      • 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

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

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

      • 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