CentraSite Database Handling

1 Introduction

CentraSite is a platform to govern a company's service landscape. To do this, lots of data both predefined as well as created (or modified) by the customer is necessary. This data is stored in a database.

The data CentraSite's functioning is based upon is organized adhering to two different standards. The data that is referred to as 'registry' data, meaning data representations of assets as organizations, services, methods, etc. is modelled after the JAXR standard. Those parts of the data that rather belong to the 'repository' side, specification documents, WSDLs, etc., adhere to the WebDAV standard.
The fact that there is an underlying database manifests in many useful features that databases typically offer. Such features are direct accessibility via a query language (here XQuery), the recovery capacities via backup, or enhanced means of keeping the data compact.
In addition of being in XML, the data mostly also adheres to the JAXR standard. This is, data corresponding to a CentraSite asset, e.g. a service, is represented as an XML document in JAXR format.

2 Database Querying

Since all data supporting and occurring alongside the design of a customer's service landscape is kept in a database in a form according to predefined schemas, such data can be queried using an appropriate query language. Since the data is in XML (mostly) the language of choice is XQuery.

There are different options to address an XQuery towards the CentraSite database. For some sample queries, we will use the Tamino Interactive Interface (TII) that is available from the Software AG Installer license-free (below 'Tamino XML Server / XTools'). The screenshot shows a comparatively simple query issued from the TII in Firefox. The query retrieves all service's names.
As we see in the query the standard JAXR objects (services, organizations, operations, etc.) are contained in CentraSite's JAXR namespace. CentraSite makes use of JAXR's extensibility mechanisms - first - by defining its own object types (e.g. 'Report') and - second - by allowing the CentraSite user to add own asset types. These objects then belong to different namespaces.
XQuery is also a means to access the repository part of the database which adheres to the WebDAV standard. This works via suitable extensions to the XQuery standard namely predefined functions as tdf:resource(), tdf:getProperties(), etc.
For detailed documentation of the complete XQuery enablement refer to the Tamino documentation and the CentraSite XQuery cookbook. As the Tamino documentation shows, there is also a Software AG proprietary XQuery extension that allows database updates. The usage of this with CentraSite, however, is discouraged. Although the database integrity is ensured XML-wise, it is not so w.r.t. JAXR. So for changes please use the appropriate CentraSite APIs as the CentraSite BusinessUI.

3 Database Backups

For recovering a broken CentraSite registry/repository, backups and log spaces are used. A backup (.2B0 file) is a logical copy of a CentraSite registry/repository, a log space (.2L0 file) contains data about modifications done in the CentraSite registry/repository. A new log space is created when creating a backup has finished or when the CentraSite server is started. When a log space is created, it is associated to the latest backup.

The existing backups and log spaces can be viewed with the inoadmin listdbspaces command. For better readability, switch the output format to text (default is XML).
In the example, 3 backups exist and the latest log space 570 is associated to the backup with the key 001568386722, the log spaces 568 and 569 are associated to backup 001568343021 and the log spaces 564 to 567 are associated to the oldest backup 001568340547.

When using the inoadmin restore command without any additional parameters, the latest backup is used to restore the CentraSite registry/repository and the associated log space 570 is used to re-apply the updates done since the latest backup was created. If the latest backup is not accessible for any reason, another backup can be used. For example, inoadmin backup CentraSite 001568343021 will use the backup with the key 001568343021 for restore and the subsequent recovery phase will use the log spaces 568 to 570 to re-apply updates.

Because log spaces are associated to backups, they will be deleted when the oldest backup is deleted. If a single backup is deleted, but not the oldest one, the log spaces remain. For example, if backup 001568386722 is deleted, no log space is removed, because the associated log space 570 can still be used for recovery with backup 001568343021. Only if the oldest backup is deleted, the associated log spaces can be deleted as well. In the example above, the log spaces 564 to 567 will be automatically deleted when deleting the oldest backup 001568340547.

Deleting the oldest backup and the associated log spaces can be automated using the sever property "number of backup generations" to delete all backups (and the associated log spaces) but the number of newest backups specified by this property. When using "number of backup generations" = 3 in the example above the following situation will be present after creating a new backup: The new backup, backup 001568386722 and backup 001568343021 and the log spaces 568 to 571 will remain, the oldest backup 001568340547 and the associated log spaces 564 to 567 are removed.

CentraSite Space Management

The CentraSite Registry/Repository data is stored in a database which physically consists of data space (.2D0), index space (.2I0) and journal space (.2J0) container files. When the database is running, the journal space is used to store autorestart data for repairing the database during restart in case the database was not shut down normally (database abort, power outage, etc.). By default, the CentraSite data spaces are located on the CentraSite data directory <INST-ROOT>/CentraSite/data. On Windows, it might be necessary to select the 'hidden items' checkbox.

Additionally CentraSite stores files for backups (.2B0) and log spaces (.2L0). Log spaces are associated to backups and contain data to redo all modifications done since the creation of the associated backup. When using inoadmin restore without additional parameters the last backup will be used for restoring and the associated log spaces are used to redo the subsequent updates. The inoadmin command line tool can be found at <INST-ROOT>/CentraSite/bin.

In case of space problems on the disc with the data directories and because it is anyway better to have backups on another disc than the data itself, the backup and log locations can be moved to other locations (inoadmin setlocation command). When backups are deleted – also when using the property "number of backup generations" – the associated log spaces are deleted as well. When still having space problems after backups and log spaces were directed to other discs, it is also possible to move the data or index spaces (inoadmin movedbspace command).

A CentraSite database with a data space (.2D0) much larger than 10 GB most often contains event data or log data of different type (e.g. audit log, policy log, approval log). Information on how much space is allocated for which doctype can be retrieved with the command line tool inodba, also at <INST-ROOT>/CentraSite/bin. Previous to inodba run the centrasite_setenv script.

Log data should be purged regularly using CentraSiteCommand.[sh|cmd] to avoid an unnecessary amount of data. The CentraSiteCommand tool can be found at<INST-ROOT>/CentraSite/utilities. 

When the legacy mode of run-time event storage is used, and the runtime event data is consuming a lot of space it is possible to use less space by switching to the enhanced mode of run-time event storage (flat file model).

When deletion leads to only partially used data blocks, these blocks will be re-used when new data of the same type is stored again. However, when log data is purged regularly, most often not that many consecutive data blocks may become empty requiring database reorganization. So, when a large amount of data was purged (for example because log purging was done for the first time) or after switching to enhanced mode of run-time event storage and deleting the legacy mode run-time event data, it may be possible to shrink the data space using inoadmin reorganize.

Using inoadmin reorganize will only shrink the data space when the amount of free space is more than 10% of the total space. Reorganization is done in three phases where the last two phases requires much more time and resources than the first one. The three phases are:

  1. search for consecutive empty data blocks and return them to the free space area
  2. defragment the free space area by creating and restoring a temporary backup
  3. shrink the data space by cutting off the defragmented free space area

A reorganization that only carries out phase 1 and does not shrink the database returns empty blocks still assigned to a specific doctype to the free space area.

When new data is to be stored and no more space is available within the blocks assigned for this data's doctype, blocks from the free space area are used. Only if no more free blocks are available, the data space is enlarged.