public interface Adaptation extends ReadContext
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.
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:
ValueContext
, the absolute path always begins at the root of the dataset,
even if it is a table record.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.createValueContext()
Modifier and Type | Method and Description |
---|---|
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()
If this is a table record, the method returns the dataset that contains it;
it returns
null if this is a dataset. |
AdaptationTable |
getContainerTable()
If this is a record, the method returns the table that contains it;
returns
null if this is a dataset. |
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(Locale aLocale)
Returns the label of the dataset or record corresponding to
the specified locale.
|
String |
getLabelOrName(Locale aLocale)
Returns the label of the dataset or record corresponding to
the specified locale.
|
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.
|
get_boolean, get_int, getDate, getList, getResourcePathInModule, getResourcePathWithModule, getString, getTable, isEndUserDebug
AdaptationName getAdaptationName()
AdaptationReference getDatasetReference()
If this is a table record, then the returned reference is the one of its container dataset.
getOccurrencePrimaryKey()
AdaptationReference getTreeReference()
If this is a table record, then the returned reference is the one of its container dataset's tree.
getDatasetReference()
PrimaryKey getOccurrencePrimaryKey()
If this is a dataset, not a table record,
the method returns null
.
getDatasetReference()
AdaptationHome getHome()
boolean isSchemaInstance()
true
if this is a dataset, not a table record.
This method returns the opposite result of isTableOccurrence()
.
boolean isTableOccurrence()
true
if this is a table record, not a dataset.
This is the opposite of isSchemaInstance()
.
isOccurrenceInheriting()
,
isOccurrenceOcculting()
AdaptationTable getContainerTable()
null
if this is a dataset.Adaptation getContainer()
null
if this is a dataset.Profile getOwner()
If no owner is specified for this dataset, it returns the profile that owns its parent.
It never returns null
.
UserReference getCreator()
May return null
if the record has been created before 5.7.0.
Date getTimeOfCreation()
Date getTimeOfLastModification()
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).
getLastUser()
UserReference getLastUser()
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).
getTimeOfLastModification()
boolean isActivated()
true
if this dataset or record is activated.
This state impacts validation:
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.
getValidationReport(boolean)
boolean isDeleted()
true
if this dataset or record has become unavailable.
This may happen if:
Adaptation getUpToDateInstance()
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())
.
Object get(Path aPath) throws PathAccessException
ReadContext
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).
The access and mapping rules between XML Schema and Java are described in the chapter Mapping to Java.
get
in interface ReadContext
PathAccessException
- if aPath
does not refer to an existing node in the underlying
type tree structure.getValueWithoutResolution(Path)
Object get(SchemaNode aNode) throws PathAccessException
ReadContext
This method is equivalent to get(aNode.getPathInAdaptation())
,
but is slightly more efficient.
get
in interface ReadContext
PathAccessException
Object getValueWithoutResolution(Path aPath)
null
, or a specific object. Specifically:
AdaptationValue.INHERIT_VALUE
.
null
, it returns the object defined
(it must be an instance of the node's type).null
(not inherited), it returns
null
.See Inheritance and value resolution for more information.
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.PathAccessException
- If no node exists for the specified path.ReadContext.get(Path)
ValueContext createValueContext()
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.
boolean isSchemaDefinitionCompliant(boolean ensureActivation)
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;
getValidationReport(boolean, boolean)
ValidationReport getValidationReport()
This method is equivalent to:
Adaptation.getValidationReport(true, true);
getValidationReport(boolean, boolean)
ValidationReport getValidationReport(boolean ensureActivation)
This method is equivalent to:
Adaptation.getValidationReport(ensureActivation, true);
getValidationReport(boolean, boolean)
ValidationReport getValidationReport(boolean ensureActivation, boolean updateValidationReport)
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);
ValidationReport getValidationReport(ValidationSpec aValidationSpec)
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 EBX® main configuration file, this threshold is applied to each constraint defined in the underlying data model and for each severity if this instance 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 and a severity: the validation of the constraint is stopped and an error message indicating that the threshold has been reached is added to the validation report.
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.
ValidationReport getValidationReportForNode(SchemaNode aNode)
This method is equivalent to:
Adaptation.getValidationReportForNode(aNode, true, true);
ValidationReport getValidationReportForNode(SchemaNode aNode, ValidationSpec aValidationSpec)
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.
aNode
- the node whose validation result is to be returned.maxOccurs
> 1,
the report will contain the messages of its elements.IllegalArgumentException
- If the specified node is:
AdaptationTable.getValidationReport()
must be used instead);IllegalStateException
- if the current dataset or record holds data that is not subject to validation.
This is the case, for instance, for the history.AdaptationTable.getValidationReport(ValidationSpec)
,
isHistory()
ValidationReport getValidationReportForNode(SchemaNode aNode, boolean ensureActivation)
This method is equivalent to:
Adaptation.getValidationReportForNode(aNode, ensureActivation, true);
AdaptationTable.getValidationReport()
ValidationReport getValidationReportForNode(SchemaNode aNode, boolean ensureActivation, boolean updateValidationReport)
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);
void resetValidationReport(boolean resetChildren)
resetChildren
- if set to true
, the validation reports of
child datasets will also be reset.UnsupportedOperationException
- if the current Adaptation
is a record.AdaptationTable.resetValidationReport()
SchemaNode getSchemaNode() throws UnavailableContentError
UnavailableContentError
- If data model has errors.SchemaLocation getSchemaLocation()
boolean hasSevereError()
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)
.
UnavailableContentError
String getModuleName()
String getLabel(Locale aLocale)
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.
String getLabelOrName(Locale aLocale)
Returns the reference of the dataset or record if no label exists for the locale.
String getDescription(Locale aLocale)
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.
boolean isHistory()
true
if
AdaptationTable.getHistory()
boolean isRootAdaptation()
true
if this is a root dataset,
meaning it has no parent dataset.
If this is a table record,
the method always returns false
.
getOccurrenceDefinitionMode()
,
getParent()
Adaptation getParent()
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
;
null
, if such a record in the parent table is neither defined nor inherited;
isRootAdaptation()
,
getOccurrenceDefinitionMode()
DefinitionMode getOccurrenceDefinitionMode()
If this is a dataset, not a table record,
the method returns null
.
getParent()
boolean isOccurrenceInheriting()
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()
.
getParent()
,
getOccurrenceDefinitionMode()
boolean isOccurrenceOcculting()
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()
.
getParent()
,
getOccurrenceDefinitionMode()
boolean isOccurrenceHidden()
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
.
getOccurrenceDefinitionMode()
boolean equals(Object object)
equals
in class Object
equalsToAdaptation(Adaptation)
boolean equalsToAdaptation(Adaptation other)
same reference
in the same dataspace
.String toPublicReference()
getAdaptationName()
boolean matches(String anXPathPredicateExpression)
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
.
boolean matches(String anXPathPredicateExpression, Locale locale)
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
.
String toXPathExpression()
Example:
/root/categoryX/tableY[pkey1="A01" and pkey2="666"]
If this is a dataset, not a table record,
the method always returns "/
" (root path).
String toXPathPredicateString()
Example:
pkey1="A01" and pkey2="666"
If this is a dataset, not a table record,
the method always returns null
.
toXPathExpression()
void toHtmlString(Writer aWriter)
ReadContext
toHtmlString
in interface ReadContext