[[chg]]
= Changes

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
:page-partial:


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 xref:refguide:applib:index/services/publishing/spi/EntityChangesSubscriber.adoc[EntityChangesSubscriber] SPI, identifying changed objects that are to be published (as per xref:refguide:applib:index/annotation/DomainObject.adoc#entityChangePublishing[@DomainObject#entityChangePublishing()] or equivalent).


== `changesDto`

The `changesDto` root element is defined as:

[source,xml]
----
<xs:schema targetNamespace="http://isis.apache.org/schema/chg"                                  <!--.-->
           elementFormDefault="qualified"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://isis.apache.org/schema/chg"
           xmlns:com="http://isis.apache.org/schema/common">

    <xs:import namespace="http://isis.apache.org/schema/common"                                 <!--.-->
               schemaLocation="../common/common-2.0.xsd"/>

    <xs:element name="changesDto">                                                              <!--.-->
        <xs:complexType>
            <xs:sequence>
                <xs:element name="majorVersion" type="xs:string"                                <!--.-->
                            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"/>                             <!--.-->
                <xs:element name="sequence" type="xs:int"/>                                     <!--.-->
                <xs:element name="completedAt" type="xs:dateTime" minOccurs="0" maxOccurs="1"/> <!--.-->
                <xs:element name="username" type="xs:string"/>                                  <!--.-->
                <xs:element name="objects" type="objectsDto"/>                                  <!--.-->
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    ...
</xs:schema>
----
<.> the changes schema has a namespace URI of "http://isis.apache.org/schema/chg".
Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
<.> uses complex types defined in the xref:refguide:schema:common.adoc["common" schema].
<.> definition of the `changesDto` root element.
The corresponding XML will use this as its top-level element.
<.> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
<.> unique identifier for the interaction wthin which this change occurred.
The intraction Id can be used to correlate back to the xref:refguide:schema:cmd.adoc[command] that represented the intention to perform this execution, as well as to the xref:refguide:schema:ixn.adoc[interaction] that executes said command.
<.> 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.
<.> the date/time that the transaction that dirtied this objects completed
<.> the user that executed the (top-level) action invocation/property edit.
<.> 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:

[source,xml]
----
<xs:schema targetNamespace="http://isis.apache.org/schema/chg" ... >
    ...
    <xs:complexType name="objectsDto">
        <xs:sequence>
            <xs:element name="loaded" type="xs:int"/>                                           <!--.-->
            <xs:element name="created" type="com:oidsDto"/>                                     <!--.-->
            <xs:element name="updated" type="com:oidsDto"/>
            <xs:element name="deleted" type="com:oidsDto"/>
            <xs:element name="propertiesModified" type="xs:int"/>                               <!--.-->
        </xs:sequence>
    </xs:complexType>
</xs:schema>
----
<.> the number of objects that were loaded, in total, by the interaction.
<.> the identities of the objects that were, respectively, created, updated or deleted within the transaction.
<.> the number of objects' properties changed, in total, by the interaction.

The xref:refguide:schema:ixn.adoc[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.
