com.onwbp.adaptation

Interface AdaptationTable

public interface AdaptationTable

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

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

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

See Also:

Request

Method Summary

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

Method Detail

toPublicReference

String toPublicReference()

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

lookupAdaptationByPrimaryKey

Adaptation lookupAdaptationByPrimaryKey(ValueContext aContext)

Returns the record that has its primary key specified by the specified context. Returns null if it does not exist or is in occulting mode.

See Also:

lookupAdaptationByPrimaryKey(ValueContext, boolean)

lookupAdaptationByPrimaryKey

Adaptation lookupAdaptationByPrimaryKey(ValueContext aContext,
                                        boolean includeOcculting)

Returns the record specified by its primary key. Returns null if:

• the record does not exist in this table or in any ancestor tables, or
• the record with the key specified is in occulting mode and includeOcculting is false.

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

Parameters:

aContext - Context that specifies the primary key of the record to look up.

includeOcculting - If true, a record in occulting mode can be returned. If false, null will be returned if the record with the specified primary key is in occulting mode.

See Also:

Adaptation.isOccurrenceOcculting()

lookupAdaptationByPrimaryKey

Adaptation lookupAdaptationByPrimaryKey(PrimaryKey aKey)

Returns the record specified by its primary key. Returns null if it the record does not exist or if it is in occulting mode.

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

See Also:

SchemaFacetTableRef.getLinkedRecord(ValueContext)

lookupAdaptationByPrimaryKey

Adaptation lookupAdaptationByPrimaryKey(PrimaryKey aKey,
                                        boolean includeOcculting)

Returns the record specified by its primary key. Returns null if:

• the record does not exist in this table or any ancestor tables, or
• the record with the key specified is in occulting mode and includeOcculting is false.

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

Parameters:

aKey - Identity of the record to look up.

includeOcculting - If true, a record in occulting mode can be returned. If false, null will be returned if the record with the specified primary key is in occulting mode.

See Also:

Adaptation.isOccurrenceOcculting(), SchemaFacetTableRef.getLinkedRecord(ValueContext)

lookupFirstRecordMatchingPredicate

Adaptation lookupFirstRecordMatchingPredicate(String aPredicateExpression)

Returns the first record that matches the specified XPath predicate, null if no such record exists.

This method is equivalent to:

 AdaptationTable.lookupFirstRecordMatchingPredicate(
        false,
        aPredicateExpression,
        false);
 

Since:

5.4.3

See Also:

lookupFirstRecordMatchingPredicate(boolean, String, boolean)

lookupFirstRecordMatchingPredicate

Adaptation lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey,
                                              String aPredicateExpression)

Returns the first record that matches the specified XPath predicate, null if no such record exists.

This method is equivalent to:

 AdaptationTable.lookupFirstRecordMatchingPredicate(
        checkActualPrimaryKey,
        aPredicateExpression,
        false);
 

Since:

5.4.3

See Also:

lookupFirstRecordMatchingPredicate(boolean, String, boolean)

lookupFirstRecordMatchingPredicate

Adaptation lookupFirstRecordMatchingPredicate(boolean checkActualPrimaryKey,
                                              String aPredicateExpression,
                                              boolean includeOcculting)

Returns the first record that matches the specified XPath predicate, null if no such record exists.

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

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

Throws:

IllegalArgumentException - if one of the specified arguments is not defined.

IllegalArgumentException - if the specified Adaptation is not a dataset.

IllegalArgumentException - if checkActualPrimaryKey is true and the specified XPath expression argument is not a primary key expression.

MalformedXPathExpressionException - if the specified XPath expression is not syntactically correct.

PathAccessException - if the extracted table path expression does not reference an existing table node in the underlying structure.

Since:

5.4.3

See Also:

Supported XPath syntax, XPathExpressionHelper.lookupFirstRecordMatchingXPath(boolean, Adaptation, String, boolean)

computePrimaryKey

PrimaryKey computePrimaryKey(Adaptation anOccurrence)

Returns the same result as Adaptation.getOccurrencePrimaryKey().

computePrimaryKey

PrimaryKey computePrimaryKey(ValueContext aContext)

computePrimaryKey

PrimaryKey computePrimaryKey(Object[] primaryKeyValues)

Returns the PrimaryKey object that corresponds to the specified raw values.

Parameters:

primaryKeyValues - values of the primary key fields. They must be in the same order as the fields declared in in the osd:table/primaryKeys element.

Throws:

IllegalArgumentException - if either the argument or the osd:table/primaryKeys element is null, if the specified array does not have the same length as the osd:table/primaryKeys element, or if a value in the argument is not of the expected type.

ClassCastException - if a value in the specified array is not of the expected Java type.

See Also:

SchemaNode.getTablePrimaryKeyNodes(), SchemaNode.getTablePrimaryKeyValues(String), SchemaFacetTableRef.getLinkedRecord(ValueContext)

isPrimaryKeyComplete

boolean isPrimaryKeyComplete(ValueContext aContext)

Returns false if at least one field in the primary key in the specified context is not set.

getPrimaryKeySpec

Path[] getPrimaryKeySpec()

Returns the paths of the data model nodes that compose the primary key of this table.

getTableOccurrenceRootNode

SchemaNode getTableOccurrenceRootNode()

Returns the root node that defines the record structure.

See Also:

getTableNode()

getTableNode

SchemaNode getTableNode()

Returns the node of the table, which is a terminal node, in the dataset.

See Also:

getTableOccurrenceRootNode(), SchemaNode.isTableNode()

getContainerAdaptation

Adaptation getContainerAdaptation()

Returns the dataset that contains this table.

getLastModificationDate

Date getLastModificationDate()

Returns the last modification date of a table; that is, the date when any record creation, modification and deletion last happened for this table. If the table is empty and never contained any values, 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

AdaptationName getRootKey()

Deprecated. Does not work for mapped tables.

Returns the key to the virtual root record of this table. This technical record is not seen by the end user, but is useful for managing a hierarchical set of all records in this table and its descendants, for example for performing a deletion.

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

Returns:

the key of the virtual root record of this table.

See Also:

AdaptationHome.findAllDescendants(Adaptation), ProcedureContext.doDelete(AdaptationName, boolean)

lookupAdaptationByName

Adaptation lookupAdaptationByName(AdaptationName aName)

Returns the record based on the name specified; returns null if no record by that name exists.

createRequest

Request createRequest()

Creates a new request for this table.

createRequestResult

RequestResult createRequestResult(String aPredicate,
                                  RequestSortCriteria sortCriteria)

Returns the RequestResult for the specified predicate and sort criteria.

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

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

Parameters:

aPredicate - Simplified XPath expression of a filter to be applied to the table records. If null, no filter is applied.

sortCriteria - Criteria for sorting the result. If null, no sort order is applied.

See Also:

Request.setXPathFilter(XPathFilter), Request.setSortCriteria(RequestSortCriteria)

createRequestResult

RequestResult createRequestResult(String aPredicate)

Returns the RequestResult for the specified predicate.

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

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

Parameters:

aPredicate - Simplified XPath expression of a filter to apply to the table records. If null, no filter is applied.

See Also:

Request.setXPathFilter(XPathFilter)

selectOccurrences

List<Adaptation> selectOccurrences(String aPredicate,
                                   RequestSortCriteria sortCriteria)

Returns a list of records for the specified predicate and sort criteria.

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

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

Parameters:

aPredicate - Simplified XPath expression of a filter to apply on the table records. If null, no filter is applied.

sortCriteria - Criteria for sorting the result. If null, no sort order is applied.

Returns:

a List of records, where each element is an Adaptation.

See Also:

XPath supported syntax, Request.setXPathFilter(XPathFilter)

selectOccurrences

List<Adaptation> selectOccurrences(String aPredicateExpression)

Returns a list of records for the specified predicate.

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

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

Parameters:

aPredicateExpression - Simplified XPath expression of a filter to apply on table records. If null, no filter is applied.

Returns:

a List of records, where each element is an Adaptation.

See Also:

Request.setXPathFilter(XPathFilter)

getValidationReport

ValidationReport getValidationReport()

Returns an up-to-date validation report associated with this table.

This method is equivalent to:

AdaptationTable.getValidationReport(true);

See Also:

Adaptation.getValidationReport(), getValidationReport(boolean), getValidationReport(boolean, boolean)

getValidationReport

ValidationReport getValidationReport(ValidationSpec aSpec)

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

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

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

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

Throws:

IllegalStateException - if the current table holds data that is not subject to validation. This is the case, for instance, for the history.

Since:

5.9.0

See Also:

ValidationSpec

getValidationReport

ValidationReport getValidationReport(boolean ensureActivation)

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

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

This method is equivalent to:

AdaptationTable.getValidationReport(ensureActivation, true);

Parameters:

ensureActivation - if true, the validation also checks that the dataset is activated (it adds an error if this is not the case).

See Also:

Adaptation.getValidationReport(boolean), getValidationReport(), getValidationReport(boolean, boolean), ValidationSpec

getValidationReport

ValidationReport getValidationReport(boolean ensureActivation,
                                     boolean updateValidationReport)

Returns the validation report associated with this table.

This method is equivalent to:

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

 AdaptationTable.getValidationReport(spec);
 

See Also:

getValidationReport(ValidationSpec), ValidationSpec

resetValidationReport

void resetValidationReport()

Resets the validation report of this table.

Since:

5.9.0

See Also:

Adaptation.resetValidationReport(boolean)