CDO/Hibernate Store/Configuration and Setup

The configuration of the CDO server with the CDO Hibernate Store consists of 2 parts:

1. a cdo-server.xml configuration file.
2. a launch configuration in Eclipse.

The description here assumes that the CDO server will be started from Eclipse.

Example Projects

This document discusses the setup and configuration of the CDO server. This page assumes that required plugins have been downloaded and installed and that they are correctly loaded/installed after restarting Eclipse.

This page uses the org.eclipse.emf.cdo.examples.hibernate.server project as an example. In addition there are 2 other examples projects but they relate to the client-side. The server side examples development project can be downloaded using git from here:

• http://git.eclipse.org/c/cdo/cdo.git/
• path: plugins/org.eclipse.emf.cdo.examples.hibernate.server

See CDO/Hibernate_Store/Quick_Start for more information about example projects.

There are a number of relevant (for configuration) files in this example project:

• config/cdo-server.xml (CDO as a default uses the cdo-server.xml in the config directory)
• config/company_model_teneo_annotations.xml: contains model JPA annotations
• config/generated_hbm_xml: is used in the example of using a static hbm file.
• CDOHibernateServer.launch file

You can start the CDO Server directly by right-clicking the CDOHibernateServer.launch and then select: Run As > CDOHibernateServer.launch. The configuration file is discussed in some more detail.

Note: if there is a ClassNotFoundException to org.hsqldb, in org.eclipse.emf.cdo.examples.hibernate.server project, open META-INF/MANIFEST.MF and add dependency to org.hsqldb bundle.

Configuration file

An example configuration file is shown below. It consists of different sections: acceptor definition: defines the communication protocol and port repository: contains CDO properties, Teneo properties and Hibernate properties store: within the repository tag a store is defined (type="hibernate") and a mapping provider is specified (teneo)

Here is the full listing:

<?xml version="1.0" encoding="UTF-8"?>
<cdoServer>
 
	<!--
	<acceptor type="http"/>
	-->
 
	<acceptor type="tcp" listenAddr="0.0.0.0" port="2036">
		<!--
		<negotiator type="challenge" description="/temp/users.db"/>
		-->
	</acceptor>
 
	<repository name="repo1">
		<property name="overrideUUID" value=""/>
		<property name="supportingAudits" value="false"/>
		<property name="verifyingRevisions" value="false"/>
		<property name="currentLRUCapacity" value="10000"/>
		<property name="revisedLRUCapacity" value="10000"/>
 
 
		<!-- 
			NOTE: the following properties are currently defined on repository level.
			In future builds of the CDO Hibernate store these properties are defined
			within the store and mappingProvider tags.
		-->
 
			<!-- 
				Teneo options: 
				see: http://www.elver.org/hibernate/options.html 
				or the org.eclipse.emf.teneo.PersistenceOptions class
			-->
 
			<!-- The following value must be set normally like this, use this in your app also -->
			<property name="teneo.mapping.cascade_policy_on_non_containment" value="PERSIST,MERGE"/>
 
			<!-- some demo settings -->
			<!-- 
				using an external xml file for annotations, note this xml file 
				is located in the org.eclipse.emf.cdo.examples.hibernate.annotations
				which is available on the cdo server by adding it to the CDOHibernateServer.launch configuration
			-->
			<property name="teneo.mapping.persistence_xml" value="/META-INF/company_model_teneo_annotations.xml"/>
			<!-- create tables for each subclass with joining to the parent table -->
			<property name="teneo.mapping.inheritance" value="JOINED"/>
			<!-- create an index for each fk -->
			<property name="teneo.mapping.add_index_for_fk" value="true"/>
 
 
			<!-- Hibernate properties , see: http://docs.jboss.org/hibernate/stable/core/reference/en/html_single/#configuration-optional -->
			<property name="hibernate.hbm2ddl.auto" value="update"/>
			<property name="hibernate.show_sql" value="false"/>
			<property name="hibernate.connection.pool_size" value="10"/>
			<property name="hibernate.cache.provider_class" value="org.hibernate.cache.HashtableCacheProvider"/>
 
			<!-- Setting for hsqldb -->
			<property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
			<property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/>
			<property name="hibernate.connection.url" value="jdbc:hsqldb:mem:cdohibernate"/>
			<property name="hibernate.connection.username" value="sa"/>
			<property name="hibernate.connection.password" value=""/>
			<property name="hibernate.connection.autocommit" value="true"/>
 
			<!-- Setting for mysql
			<property name="hibernate.dialect" value="org.hibernate.dialect.MySQLInnoDBDialect"/>
			<property name="hibernate.connection.driver_class" value="com.mysql.jdbc.Driver"/>
			<property name="hibernate.connection.url" value="jdbc:mysql://localhost:3306/cdohibernate"/>
			<property name="hibernate.connection.username" value="root"/>
			<property name="hibernate.connection.password" value="root"/>
			-->
 
		<store type="hibernate">
			<mappingProvider type="teneo">
			</mappingProvider>
		</store>
	</repository>
 
</cdoServer>

This file is present in the config folder of the org.eclipse.emf.cdo.examples.hibernate.server project.

Note: as is noted in the config file, the location of the Teneo and Hibernate properties will change in future builds (with backward compatibility support). In the future the Teneo properties are placed within the mappingProvider tag and the Hibernate properties directly within the store tag.

Each of the different property sections is discussed in more detail.

Teneo Properties

Teneo supports many (40+) global properties to control the mapping logic itself, database artifact naming and entity naming. All the options are described in the Teneo options page.

The options are also described in the PersistenceOptions class. By installing the Teneo SDK, see the download and install section you will have the source code available in Eclipse. Check this class for textual representation of the options (which prefix to use).

One option: teneo.mapping.cascade_policy_on_non_containment, needs to be set to: PERSIST,MERGE. This is already done in the cdo-server.xml (and the example above).

Hibernate options

There are many hibernate options. The most important ones (to connect to the database) are shown above, there are however many more. Check out the documentation here.

Additional Hibernate or other Config files

There are cases where it is required to add additional Hibernate or EHCache or other configuration files to the CDO server. These files should be made visible to the hibernate plugin on the server. To accomplish this the following has to be done:

1. Option: Additional Plugin

• place the files in a separate plugin
• let this plugin depend on the org.eclipse.emf.cdo.server.hibernate.teneo plugin. And depending on the content of the plugin let it also depend on org.eclipse.emf.cdo.server.hibernate and possibly also on the hibernate plugin (select the correct hibernate plugin with version 3.3.2 or higher)
• add this to the MANIFEST.MF of your project (this ensures that the hibernate store can see your files):

Eclipse-RegisterBuddy: org.eclipse.emf.cdo.server.hibernate, org.eclipse.emf.cdo.server.hibernate.teneo

• make sure that the configuration files are copied to the output folder, they should be listed in the build.properties in the bin.include/binary. In the examples project the files are placed in the META-INF directory which works fine.
• export (in the MANIFEST.MF) the location containing the configuration file (not need if you place the files in META-INF).

The example project: org.eclipse.emf.cdo.examples.hibernate.server (see section on examples projects above) is configured to be visible in the CDO Server.

2. Option: Additional Plugin fragment

• create a new fragment with the host plugin being org.eclipse.emf.teneo (uncheck 'Create a Java project' in the New Fragment Project Wizard, we don't need a java plugin for this)
• place the files in the root of your fragment (or if you prefer create a sub directory)
• add '.' to the bundle class path
• in your teneo properties point to the path of your xml file (relative to the root of your host plugin, e.g. if you placed it into /teneo/my-xml.xml, then 'teneo.mapping.persistence_xml' points to 'teneo/my-xml.xml)

Database

The config file shown above (and in the examples project) defines that hsqldb should be used. This can easily be changed to another database. Make sure that the driver for the other database is available as a plugin.

Also note that Hibernate will not create a database, so if the store is used with another database server then the database needs to be created manually. The tables don't need to be created, this part is done by Hibernate.

Run Launch Config

The examples project contains an example CDOHibernateServer.launch configuration. To run it right click on it and then select: Run As > CDOHibernateServer.

The CDO launch config has a few special settings:

• on the first page of the launch config the 'Program to run' should be set to: an application with selected the org.eclipse.emf.cdo.server.app.

• on the second page the path to the config file is defined, make sure that it is set like this (see the selected text in the arguments):

The config file path points to the org.eclipse.emf.cdo.examples.hibernate.server/config, the cdo-server.xml is automatically found by CDO.

• on the third page, for convenience the plugins are not selected individually but all plugins are selected.

If you want a more specific selection then you need to manually select the correct plugins. For the CDO runtime at least the following plugins need to be selected in the launch config:

• org.eclipse.emf.cdo
• org.eclipse.emf.cdo.common
• org.eclipse.emf.cdo.examples.hibernate.server
• org.eclipse.emf.cdo.server
• org.eclipse.emf.cdo.server.hibernate
• org.eclipse.emf.cdo.server.hibernate.teneo
• org.eclipse.emf.cdo.server.net4j
• org.eclipse.emf.cdo.net4j
• org.eclipse.emf.cdo.net4j.tcp
• org.eclipse.emf.cdo.net4j.util

In addition there are common platgorm plugins which need to be selected.

There is more CDO documentation on creating CDO launch configs:

• Create Launch Config

How to get to the hibernate mapping

The hibernate mapping can be retrieved from the osgi console with the following command (available from 4.1 builds - May 2012):

hibernate mapping <repository-name> <export-file>

Note the export-file is the complete path with filename. For example:

hibernate mapping repo1 /tmp/hbm.xml

The output is the hibernate mapping used to configure hibernate.

How to enable Hibernate logging

Sometimes it is really important to see in detail which queries hibernate fires and what actions are taken. For background information on Hibernate logging see the Hibernate manual.

To see the sql generated by Hibernate, set the following property in the cdo-server.xml config file:

<property name="hibernate.show_sql" value="true"/>

For more extensive logging:

The Hibernate plugin, downloadable from the elver.org update site, contains the SLF4J api jar, the slf4j nop jar and the slf4j log4j jar file.

As the Hibernate store is used in an OSGI environment, the assumption is that you have an org.apache.log4j plugin installed (this is almost done automatically as part of the eclipse install). You can find a log4j plugin on the elver.org update site. The idea is to add the log4j.properties to the org.apache.log4j plugin using a fragment.

This is described in this blog. CDO Hibernate provides an example fragment project which can be downloaded from here. You can create a similar project and directly edit the log4j.properties located in the src directory. Note the log4j.properties needs to be added to the build.properties so that it is copied to the output folder.

As CDO prints both the client and server trace to the console it can make sense to redirect the server output to a file. To do this edit the CDOHibernateServer launch configuration and go to the Common tab, there in the bottom you can specify the destination of the standard output. In the tracing tab you can set which part of CDO are traced.

Running your own junit testcases

Junit testcases can be run as Plugin Testcase and as a normal testcase. In the latter case the classpath is not resolved using an osgi container. The CDO Hibernate plugins make use of import-packages to define dependencies on Hibernate and Teneo plugins. When running a junit testcases in a 'normal' (i.e. non-plugin mode) the import-packages are only resolved against explicitly defined dependencies in the MANIFEST.MF. This means that if you get ClassNotFoundExceptions in CDO Hibernate code that you probably have to define additional dependencies in the MANIFEST.MF of the plugin project with junit testcases. Here is an snippet of the MANIFEST.MF of the org.eclipse.emf.cdo.examples.hibernate.client project:

Require-Bundle: org.eclipse.emf.ecore;bundle-version="2.4.0";visibility:=reexport,
 org.eclipse.emf.cdo;bundle-version="3.0.0",
 org.eclipse.net4j.jvm;bundle-version="3.0.0",
 org.eclipse.emf.cdo.net4j;bundle-version="3.0.0",
 org.eclipse.net4j.tcp;bundle-version="3.0.0",
 org.eclipse.emf.cdo.examples.company;bundle-version="3.0.0",
 org.eclipse.core.runtime;bundle-version="3.4.0",
 org.eclipse.emf.cdo.server.hibernate.teneo;bundle-version="3.0.0",
 org.eclipse.emf.teneo;bundle-version="1.1.2",
 org.eclipse.emf.teneo.hibernate.mapper;bundle-version="1.1.2",
 org.eclipse.emf.teneo.annotations;bundle-version="1.1.2",
 org.eclipse.emf.cdo.server.hibernate;bundle-version="3.0.0",
 org.hibernate;bundle-version="3.3.2"
Import-Package: junit.framework;version="3.8.2",
 org.apache.commons.logging;version="1.0.4"

---

Wikis: CDO | Net4j | EMF | Eclipse