Change Registry

Overview

The Sophora Change Registry records every changed sophora document and persists metadata of the change. Whenever a document is changed this data is saved:

• The document's identifiers (uuid, externalId and sophoraId)
• The document's primary type
• The change cause
• The date at which the change occured
• The date when this change has been written to the persistence of the Sophora Change Registry

The possible change causes are:

• SAVED
• PUBLISHED
• SET_TO_OFFLINE
• DELETED
• COMPLETELY_DELETED
• STRUCTURE_NODE_CHANGED
• INHERITED_PROPERTY_CHANGED
• SELECTVALUE_CHANGED
• VIRTUAL_PROPERTY_CHANGED
• RELEASED
• ENABLED
• DISABLED
• SET_TO_PUBLISHED_AT
• PRE_PUBLISHED
• VERSIONED
• YELLOW_DATA_DELETED
• YELLOW_DATA_CHANGED

Only the latest change for a document is saved. Thus for every document in the Sophora repository there is at most one entry in the Sophora Change Registry.

The Change Registry is maintained by each Sophora Server individually and is constantly updating itself as documents are changed.

Persistence and Queueing

The Sophora Change Registry stores the most recent change for every document within an embedded Derby database. The database files are located in the folder ${sophora.home}/repository/changeregistry/derby.

Events that need to end up being written to the Change Registry are queued. Commonly this queue is worked off rapidly. Bulk-Actions like renaming top-level structure nodes however might result in huge amounts of events and can delay changes from appearing in the Change Registry. The queue size can be seen via JMX.

Additionally, if there is a notable gap between change date and persistence date on a Change Registries entry, this indicates that there has been a delayed processing due to a long queue size.

The queue is persisted in case the Sophora Server is getting shut down while per are still pending events. The chronology of events is kept in any case.

Using the Change Registry

The Sophora Change Registry can be accessed using the Sophora Servers Content API or by using the Sophora Client. Both ways work in a similar fashion.

A query is always composed by specifying a time range (referring to the change date) a sort direction (default: ascending by change date) and parameters for paging.

Using the Change Registry by calling the Sophora-Server-internal Content API

The Content API provides a new method for accessing the Change Registry. A sample call using all possible parameters might look like that:

http://my-sophora-server:1196/content-api/changeregistry?since=2019-10-17T12:00:00Z&until=2020-01-01T00:00:00Z&pageIndex=0&pageSize=1&sort=desc

The parameter sort should be either asc, ascending, desc or descending (ignoring case).

The corresponding JSON-Response will look like that:

{
	"contentChanges": [
		{
			"documentUuid": "25b80524-f999-4540-839d-7ec66caf45fd",
			"sophoraId": "mystory100",
			"externalId": "25b80524-f999-4540-839d-7ec66caf45fd",
			"primaryType": "demo-nt:story",
			"changeCause": "SAVED",
			"changeDate": "2019-10-18T16:47:22Z",
			"persistedDate": "2019-10-18T16:47:23Z"
		}
	],
	"searchParameters": {
		"pageIndex": 0,
		"pageSize": 1,
		"since": "2019-10-17T12:00:00Z",
		"until": "2020-01-01T00:00:00Z",
		"sortOrder": "DESCENDING"
	},
	"pageCount": 24174,
	"numberOfElements": 24174
}

Using the Change Registry by calling the external Content API

Sophora 5 introduces the Content API as a stand-alone tool. This new external Content API works the same way, the Sophora-Server.internal Content API does by calling

http://content-api-hostname:8080/api/v1/changeregistry?since=2019-10-17T12:00:00Z&until=2020-01-01T00:00:00Z&pageIndex=0&pageSize=1&sort=desc

Using the Change Registry through the ISophoraClient

The Sophora Client provides the new method com.subshell.sophora.client.ISophoraClient#findContentChanges(ContentChangeSearch). The request object com.subshell.sophora.api.content.changeregistry.ContentChangeSearch has equivalent parameters as the request towards the Content API. These are:

• pageIndex, 0 by default
• pageSize, 1000 by default
• since, 1970-01-01T00:00:00.00 by default
• until, 2100-01-01T00:00:00.00 by default
• sortOrder, ASCENDING by default

The result is equivalent to the Content API's response as well. It provides a list of changes and reflects the requested search-parameters.

Since the Sophora Change Registry is updating itself all the time, an end date of the time range is necessary to define an exact time window.

A typical user of the Change Registry would at first register itself as a ServerEventListener after it's startup and would than query for content changes which are missing because of a downtime. In order to receive derived document changed event, the Sophora Client must call the method com.subshell.sophora.client.ISophoraClient#setListeningToDerivedDocumentChanges. This approach ensures that no event is missed out.