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 Detail

      • toPublicReference

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

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

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

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