Changes

The changes ("chg") schema defines the serialized form identifying which objects have been created, updated or deleted as the result of invoking an action or editing a property. It also captures a number of other metrics counts (number of objects loaded, number of object properties modified), useful for profiling.

An instance of the DTO (corresponding to this schema) is used within the EntityChangesSubscriber SPI, identifying changed objects that are to be published (as per @DomainObject#entityChangePublishing() or equivalent).

`changesDto`

The changesDto root element is defined as:

<xs:schema targetNamespace="https://causeway.apache.org/schema/chg"                                  (1)
           elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="https://causeway.apache.org/schema/chg"
           xmlns:com="https://causeway.apache.org/schema/common">

    <xs:import namespace="https://causeway.apache.org/schema/common"                                 (2)
               schemaLocation="../common/common-2.0.xsd"/>

    <xs:element name="changesDto">                                                              (3)
        <xs:complexType>
            <xs:sequence>
                <xs:element name="majorVersion" type="xs:string"                                (4)
                            minOccurs="0" maxOccurs="1" default="2"/>
                <xs:element name="minorVersion" type="xs:string"
                            minOccurs="0" maxOccurs="1" default="0"/>

                <xs:element name="interactionId" type="xs:string"/>                             (5)
                <xs:element name="sequence" type="xs:int"/>                                     (6)
                <xs:element name="completedAt" type="xs:dateTime" minOccurs="0" maxOccurs="1"/> (7)
                <xs:element name="username" type="xs:string"/>                                  (8)
                <xs:element name="objects" type="objectsDto"/>                                  (9)
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    ...
</xs:schema>

1	the changes schema has a namespace URI of "https://causeway.apache.org/schema/chg". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
2	uses complex types defined in the "common" schema.
3	definition of the `changesDto` root element. The corresponding XML will use this as its top-level element.
4	each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
5	unique identifier for the interaction wthin which this change occurred. The intraction Id can be used to correlate back to the command that represented the intention to perform this execution, as well as to the interaction that executes said command.
6	Unique sequence number of the transaction committed within the interaction giving rise to this set of changes. Although there is usually just one transaction per interaction, in advanced use cases there could be many.
7	the date/time that the transaction that dirtied this objects completed
8	the user that executed the (top-level) action invocation/property edit.
9	identifies the objects that have changed.

The ChangesDto DTO corresponding to the changesDto root element can be marshalled to/from XML using the ChangesDtoUtils class.

`objectsDto`

The objectsDto complex type actually identifies the objects created, updated or deleted. It also captures additional metrics counters:

<xs:schema targetNamespace="https://causeway.apache.org/schema/chg" ... >
    ...
    <xs:complexType name="objectsDto">
        <xs:sequence>
            <xs:element name="loaded" type="xs:int"/>                                           (1)
            <xs:element name="created" type="com:oidsDto"/>                                     (2)
            <xs:element name="updated" type="com:oidsDto"/>
            <xs:element name="deleted" type="com:oidsDto"/>
            <xs:element name="propertiesModified" type="xs:int"/>                               (3)
        </xs:sequence>
    </xs:complexType>
</xs:schema>

1	the number of objects that were loaded, in total, by the interaction.
2	the identities of the objects that were, respectively, created, updated or deleted within the transaction.
3	the number of objects' properties changed, in total, by the interaction.

The interaction schema also provides metrics on the number of objects loaded/changed, but is more granular, each figure relating to a single (sub-)execution within an interaction.