# Configuring Repositories

Author: Eike Stepper

The repositories of a CDO Server are configured in the cdo-server.xml file. Here's an example:

| cdo‑server.xml |  |  |  |

`<?xml version="1.0" encoding="UTF-8"?>
<cdoServer>
<repository name="repo1">
<property name="overrideUUID" value=""/>
<property name="supportingAudits" value="true"/>
<property name="supportingBranches" value="true"/>
<property name="ensureReferentialIntegrity" value="false"/>
<property name="allowInterruptRunningQueries" value="true"/>
<property name="idGenerationLocation" value="STORE"/>
<property name="serializeCommits" value="false"/>
<property name="optimisticLockingTimeout" value="10000"/>
<store type="db">
<property name="connectionKeepAlivePeriod" value="60"/>
<property name="readerPoolCapacity" value="20"/>
<property name="writerPoolCapacity" value="20"/>
<mappingStrategy type="horizontal">
<property name="qualifiedNames" value="true"/>
</mappingStrategy>
<dbAdapter name="h2"/>
<dataSource
class="org.h2.jdbcx.JdbcDataSource"
URL="jdbc:h2:database/repo1"/>
</store>
</repository>
<!-- other acceptors and repositories -->
</cdoServer>
`

The following sections describe the various elements and properties.

Table of Contents

1 | Element repository
| 1.1 | Property overrideUUID
| 1.2 | Property supportingAudits
| 1.3 | Property supportingBranches
| 1.4 | Property supportingEcore
| 1.5 | Property supportingUnits
| 1.6 | Property checkUnitMoves
| 1.7 | Property ensureReferentialIntegrity
| 1.8 | Property serializeCommits
| 1.9 | Property_allowInterruptRunningQueries
| 1.10 | Property idGenerationLocation
2 | Element securityManager
3 | Element authenticator
4 | Element initialPackage
5 | Element store
| 5.1 | Property connectionKeepAlivePeriod
| 5.2 | Property readerPoolCapacity
| 5.3 | Property writerPoolCapacity
| 5.4 | Property dropAllDataOnActivate
6 | Element mappingStrategy
| 6.1 | Property toManyReferences
| 6.2 | Property maxTableNameLength
| 6.3 | Property maxFieldNameLength
| 6.4 | Property tableNamePrefix
| 6.5 | Property qualifiedNames
| 6.6 | Property forceNamesWithID
| 6.7 | Property fieldConstructionTracking
| 6.8 | Property objectTypeCacheSize
| 6.9 | Property columnTypeModifier
| 6.10 | Property forceIndexes
| 6.11 | Property withRanges
| 6.12 | Property copyOnBranch
| 6.13 | Property forceZeroBasedIndex
7 | Element dbAdapter
8 | Element dataSource

## 1 Element repository

Defines an `IRepository` instance.

The `name` attribute uniquely identifies a repository in the scope of a repository configurator.

The `repository` element can contain several property elements (see below) and must contain exactly one store element.

### 1.1 Property overrideUUID

Specifies a constant UUID for the repository. If omitted the repository will be created with a random UUID. The format of an override UUID is not further specified but should respect the file naming conventions of the used operating system.

Overriding the default random UUID can be useful if you have scripts that operate on the file system folder that is created on the server for each repository and named after the repository UUID.

### 1.2 Property supportingAudits

Specifies whether the repository will support audit views or not. Please note that a repository can only support audit views if its store supports audit views, as well.

The shipped DBStore does support audit views. Note also that it will not delete or update rows for modified objects if audits are supported. All revised state of the repository will be kept in the DB which can result in databases growing very large!

### 1.3 Property supportingBranches

Specifies whether the repository will support the creation and usage of branches below the always existing main branch or not. Please note that a repository can only support branches if its store supports branches, as well.

Also note that branching support always requires auditing support, too.

### 1.4 Property supportingEcore

Specifies whether the repository will support the storage of instances of the Ecore (meta meta) model or not.

With the advent of the legacy mode in CDO 3.0 you can store instances of any model in CDO repositories. Whether these models have been generated for CDO or not only influences their characteristics (scalability, performance, etc.). As a consequence you can also store instances of the Ecore (meta meta) model in CDO Repositories. Since Ecore is always registered in all package registries the legacy mode would lead to the creation of mapped tables in many types of stores, even if you never planned to store instances of Ecore.

Valid values: `false` (default) or `true`.

This property is deprecated. As of 4.2 instances of Ecore are always supported (on demand).

### 1.5 Property supportingUnits

Specifies whether the repository will support the creation and optimized loading of `units` or not.

Unit support is only available if the configured `store` supports units.

Valid values: `false` (default) or `true`.

### 1.6 Property checkUnitMoves

Specifies whether the repository will apply extra validation to prevent moves of objects between `units` or not.

Valid values: `false` (default) or `true`.

See Also:

- Property supportingUnits

### 1.7 Property ensureReferentialIntegrity

Specifies whether the repository will detect and reject commits that would leave stale references in the object graph.

Valid values: `false` (default) or `true`.

### 1.8 Property serializeCommits

Specifies whether the repository will serialize commit operations by utilizing a lock or not.

Some stores, such as the LissomeStore, require commit operations to be serialized.

Valid values: `false` (default) or `true`.

### 1.9 Property_allowInterruptRunningQueries

Specifies whether the repository will cancel a scheduled query job if it is already running. Some underlying stores (e.g. DBStore with a Derby database) might not be able to deal with this cleanly. For such stores, this parameter can be set to `false`.

Valid values: `false` (default) or `true`.

### 1.10 Property idGenerationLocation

Specifies whether the repository will expect clients to generate IDs for new objects or whether it will ask the backend store to generate them.

Valid values: `STORE` (default) or `CLIENT`.

## 2 Element securityManager

Example: <securityManager type="default" description="/security:annotation:home(/home)"/>

See also: http://wiki.eclipse.org/CDO/Security_Manager

## 3 Element authenticator

Example: <authenticator type="file" description="_database/repo1.users"/>

See also: http://bugs.eclipse.org/302775

## 4 Element initialPackage

Example: <initialPackage nsURI="http://www.eclipse.org/emf/CDO/examples/company/1.0.0"/>

See also: http://bugs.eclipse.org/345431

## 5 Element store

Defines an `IStore` instance.

The `type` attribute corresponds to the type of a store factory that is contributed via the `org.eclipse.emf.cdo.server.storeFactory` extension point. The remaining attributes depend on the specified `type` attribute value. The following values are possible with the shipped distribution (subject to user-supplied extension):

- mem: Store without real persistence. A repository with a MEMStore can function properly as long as the the server is not restarted. No additional attributes are recognized.
- db: Store that connects via JDBC to a relational database and manages persistent revisions and models through a built-in O/R mapper, see [[CDO/DB Store]]. A DBStore element can contain the following nested elements:
  - Element mappingStrategy
  - Element dbAdapter
  - Element dataSource
- hibernate: Store that uses Teneo/Hibernate, see [[CDO/Hibernate Store]].
- objectivity: Store that uses Objectivity/DB, see [[CDO/Objectivity Store]].
- mongodb: Store that uses MongoDB, see [[CDO/MongoDB Store]].
- db4o: Store that uses DB4O, see [[CDO/DB4O Store]].

### 5.1 Property connectionKeepAlivePeriod

Specifies, if the store is a DBStore, at what interval the store will issue an SQL statement to keep the connection to the database alive.

### 5.2 Property readerPoolCapacity

Specifies, if the store is a DBStore, the maximum number of store accessors (JDBC connections) to keep in the reader pool.

The default value is 15.

### 5.3 Property writerPoolCapacity

Specifies, if the store is a DBStore, the maximum number of store accessors (JDBC connections) to keep in the writer pool.

The default value is 15.

### 5.4 Property dropAllDataOnActivate

If set to `true` and the store is a DBStore, drops all database tables of the configured schema at the beginning of the store activation.

The default value is `false`.

## 6 Element mappingStrategy

This element is recognized by DBStores and defines the overall `mapping strategy` of the built-in O/R mapper.

The `type` attribute corresponds to the type of a mapping strategy factory that is contributed via the `org.eclipse.emf.cdo.server.db.mappingStrategies` extension point. The following values are possible with the shipped distribution (subject to user-supplied extension):

- horizontal: Mapping strategy that creates one DB table per concrete model class. The following nested property elements are recognized:
  - Property toManyReferences
  - Property maxTableNameLength
  - Property maxFieldNameLength
  - Property tableNamePrefix
  - Property qualifiedNames
  - Property forceNamesWithID

### 6.1 Property toManyReferences

Specifies how the built-in O/R mapper will handle to-many references (collections). The following values are recognized:

- ONE_TABLE_PER_REFERENCE: Each to-many reference of the model will get its own DB table.
- ONE_TABLE_PER_CLASS: All to-many references of a model class will share a single DB table.
- ONE_TABLE_PER_PACKAGE: All to-many references of a model package will share a single DB table.
- ONE_TABLE_PER_REPOSITORY: All to-many references of all model classes i the repository will share a single DB table.

### 6.2 Property maxTableNameLength

Enables you to override the default value of the chosen DB adapter for the maximum length of table names.

### 6.3 Property maxFieldNameLength

Enables you to override the default value of the chosen DB adapter for the maximum length of column names.

### 6.4 Property tableNamePrefix

Specifies a common fixed prefix for all table names generated by this mapping strategy.

### 6.5 Property qualifiedNames

Specifies whether generated package or class table names are qualified or not.

### 6.6 Property forceNamesWithID

Specifies whether generated names are always suffixed with an internal ID or only in cases where the generated name absolutely needs mangling.

### 6.7 Property fieldConstructionTracking

Specifies whether you want `IDBField` construction stacktrace on schema update to have the origin of the nullable index field.

### 6.8 Property objectTypeCacheSize

Specifies the size of the object type in-memory cache. Possible configuration values are:

- 0 (zero): Don't use memory caching.
- >0: Use memory caching with the cache size given.

The default is a memory cache size of 10,000,000.

### 6.9 Property columnTypeModifier

Specifies the name of a `ColumnTypeModifier`.

### 6.10 Property forceIndexes

Specifies on what types of structural features additional indexes are to be created. The value is either empty or a | (pipe) separated list of the following tokens:

- NONE (default)
- ALL (equal to ATTRIBUTE|REFERENCE)
- ATTRIBUTE
- REFERENCE (equal to CONTAINER|CONTAINMENT|XREF)
- CONTAINER
- CONTAINMENT
- XREF

### 6.11 Property withRanges

Specifies whether new `revisions` create entire new copies of all their list `features` or whether just the list deltas are stored.

Possible configuration values are:

- `false` (store new copies of all lists of a revision; default value)
- `true` (store only list deltas/ranges of a revision)

This property is only applicable to horizontal mapping strategies in auditing or branching repositories.

### 6.12 Property copyOnBranch

Specifies whether the first new `revisions` in a `branch` create entire new copies of all their list `features` or whether just the list deltas (relative to the base revisions in the parent branch) are stored.

Possible configuration values are:

- `false` (store only list deltas/ranges of the first revision in a branch; default value)
- `true` (store new copies of all lists of the first revision in a branch)

This property is only applicable to range-based horizontal mapping strategies in branching repositories.

### 6.13 Property forceZeroBasedIndex

Specifies whether element removals from the beginning of list `features` adjust the list indexes of all following elements or whether the first element is allowed to have a non-zero list index.

Possible configuration values are:

- `false` (allow non-zero list index for the first list elements; default value)
- `true` (force zero list indexes for the first list elements)

This property is only applicable to range-based horizontal mapping strategies in auditing or branching repositories.

## 7 Element dbAdapter

Defines the `IDBAdapter` instance of the store that interprets the SQL dialect of the used database.

The `type` attribute corresponds to the name of a DB adapter factory that is contributed via the `org.eclipse.net4j.db.dbAdapters` extension point. No additional attributes are recognized.

The DB adapter must match the database specified in the dataSource element.

## 8 Element dataSource

Defines the DataSource instance of the store.

The `class` attribute corresponds to the fully qualified name of the data source class. Please refer to your DB manual for details about the supported data sources and their attributes.

Copyright (c) 2014 Eike Stepper (Berlin, Germany) and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html