CDO/Hibernate Store/Configuration and Setup
- a cdo-server.xml configuration file.
- a launch configuration in Eclipse.
The description here assumes that the CDO server will be started from Eclipse.
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 CVS from here:
- server: dev.eclipse.org
- main directory: /cvsroot/modeling
- path: org.eclipse.emf/org.eclipse.emf.cdo/examples/org.eclipse.emf.cdo.examples.hibernate.server
There are a number of relevant (for configuration) files in this example project:
- the 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.
- the 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.
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 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/Hibernate/Configuration_Options|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).
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:
- 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.
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:
In addition there are common platgorm plugins which need to be selected.
There is more CDO documentation on creating CDO launch configs:
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.
This section describes how to enable logging in the examples project. The approach is generic and can be applicable also in other cases.
The Hibernate plugin, downloadable from the net4j update site, contains the SLF4J api jar and the slf4j nop jar file. To enable logging you need to add jar files to the classpath for a specific logging system. Assume that you want to use log4j then you need the following:
- log4j jar file
- slf4j-log4j jar file
Place these jar files somewhere that hibernate can find them. For the examples project this means:
- add them to the org.eclipse.emf.cdo.examples.hibernate.server plugin, for example in a lib folder.
- in the Manifest.MF make three changes:
- add them in the runtime classpath (tab: Runtime, section classpath)
- export their packages on the Runtime tab
- make sure that the build.properties are set such that the files are copied to the output path (add them to the Binary Build part).
The examples server project has a log4j.properties file which you can try, it is located in the src folder.
When you use your own log4j.properties or log4j.xml file then make sure that it is copied to the output, i.e. specify it in the binary build part of the build.properties.
Inside the log4j.properties set the debug level you want.
Now when restarting you should see log statements from Hibernate (they are prefixed with Hibernate:).
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"