You can use atTime in OCL to inspect a read-only historical representation of a versioned object at a specified point in time; it is intended for modelers who need to review earlier attribute values or object state.
Purpose
The atTime operator returns a read-only representation of a versioned object as that object existed at time X.
Use it when you need to examine history without changing the current object. Typical uses include auditing, history tracking, and temporal analysis.
Requirements
- The object must be versioned. See Versioned on class.
atTimerequires a timestamp that identifies the point in time to inspect.- The returned historical representation is read-only. You can inspect its values, but you cannot use it to modify the current object or its historical state.
Use atTime
Assume that aDepartment refers to a versioned Department object and historicalTime contains the timestamp you want to inspect.
- Start with the versioned object.
- Provide the timestamp for the required historical point.
- Apply
atTimeto obtain the Department representation at that time.
aDepartment.atTime(historicalTime)For example, if a Department's name or other attributes changed after historicalTime, the result represents the values that existed at historicalTime, not the values on the current aDepartment object.
Choose the timestamp
When you need the timestamp of the current version of an object, use objectTimeStamp. Versioning operators such as atTime expect a timestamp value.
For example, use objectTimeStamp when you need to identify when the current object version was recorded, then use an appropriate timestamp to retrieve the representation required for your historical comparison.
Read-only historical results
Treat the result from atTime as historical data.
| You can do | You cannot do |
|---|---|
| Read attribute values from the historical representation. | Modify the historical representation. |
| Compare a historical value with the current object's value. | Use the historical representation to alter the current object. |
| Use it for audit and history analysis. | Treat it as the current editable object. |
Example scenario
A Department is versioned and later changes its attributes. To review the Department as it existed at a selected audit time, evaluate aDepartment.atTime(historicalTime). Read the required attributes from that result. The current aDepartment remains unchanged, and the historical result remains read-only.