View source for Documentation:OCLOperators changePoints

You can use <code>changePoints</code> in [[Documentation:Learn OCL|OCL]] to retrieve the recorded historical versions of one object over a timestamp range; it is for models where [[Documentation:Versioned on class|versioning is enabled on the class]].

== What changePoints returns ==
When versioning is enabled, MDriven records a '''change point''' each time a versioned object is modified. The <code>changePoints</code> operator retrieves the stored versions for an object whose change points fall within the requested timestamp range.

Use this operator when you need to inspect how one object changed over time. For example, you can retrieve the recorded versions of a <code>Customer</code> and evaluate each returned version in an OCL expression.

== Syntax ==
<syntaxhighlight lang="ocl">
self.changePoints(startTime, stopTime)
</syntaxhighlight>

{| class="wikitable"
! Argument
! Meaning
|-
| <code>startTime</code>
| Integer timestamp in UTC ticks at which the search begins.
|-
| <code>stopTime</code>
| Integer timestamp at which the search stops. Use <code>-1</code> to search until the end of recorded history.
|}

== Use changePoints ==
# Enable versioning on the class whose object history you need. <code>changePoints</code> is intended for versioned classes.
# Identify the object whose history you want to retrieve.
# Choose the starting timestamp in UTC ticks.
# Choose the ending timestamp, or use <code>-1</code> to include the object's remaining recorded history.
# Call <code>changePoints</code> on that object.

== Examples ==
=== Retrieve the complete recorded history ===
The following expression retrieves every recorded version of the first <code>Customer</code>, from timestamp <code>0</code> to the latest recorded change point:

<syntaxhighlight lang="ocl">
Customer.allInstances->first.changePoints(0, -1)
</syntaxhighlight>

=== Retrieve history within a selected range ===
Replace the timestamps with the UTC-tick range you need:

<syntaxhighlight lang="ocl">
self.changePoints(startTime, stopTime)
</syntaxhighlight>

For example, use <code>-1</code> as <code>stopTime</code> when the starting point is known but you want all change points recorded after that point.

== Work with timestamps ==
The versions returned by <code>changePoints</code> have timestamps. Use [[Documentation:OCLOperators objectTimeStamp|objectTimeStamp]] when you need to access the timestamp of the current object version. This is also relevant when working with other versioning operators that expect a timestamp.

== Notes ==
* <code>changePoints</code> returns recorded versions, not an unversioned object's current state.
* A class must have versioning enabled before MDriven can record the changes that this operator retrieves.
* <code>-1</code> has a specific meaning only for <code>stopTime</code>: search until the end of recorded history.

== See also ==
* [[Documentation:Versioned on class|Versioned on class]]
* [[Documentation:OCLOperators objectTimeStamp]]
* [[Documentation:OCL General Operators]]
* [[Documentation:OCL Boolean Operators]]

[[Category:Intermediate-Friendly]]
[[Category:OCL (Object Constraint Language)]]
[[Category:OCL Operators: Date & Time]]
[[Category:Priority 60]]
[[Category:EAL (Executable Action Language)]]
[[Category:Utilities]]