Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Getting started with CDO Helios

Introduction

This tutorial will help you to get started with CDO. Therefore we will set up a small project to show the CDO basics. This tutorial was build on Eclipse 3.6 (Helios) but should also work with Eclipse 3.7 (Indigo). If you like to work through this tutorial with Eclipse 3.5 Galileo switch to "Galileo CDO getting started".

Maybe, hopefully not, you will experience some trouble through the tutorial. At the end of this tutorial you will find a Trouble-Shooting which might help you to handle the problems. If not, please contact the EMF-Newsgroup.

Set up Eclipse

To ensure that everyone starts from the same point and to avoid conflicts with the tutorial we first will download a fresh Eclipse installation. You are free to use your still existing application through the tutorial. You can also start with your own and return to this point if something described in the tutorial does not meet your settings.

Download the Classic version of Eclipse from the following link.

We will use the Classic version because this will give you a good overview which additional Plugins are needed. So if you are running another distribution you can add the missing Plugins, if needed. Unpack the archive and copy the “eclipse” folder to a directory of your choice. This tutorial will use “C:/eclipse”. So far with the installation. Now start the IDE.

Set Up the Environment

The IDE will start with a fresh workspace Now we need to configure the environment with the CDO Plug-ins. To install the packages open the Update Manager (Help-->Install new software…) and select the Helios update site. Select "CDO Model Repository SDK". This will install the needed CDO Plugins. Other download repositories with more plugins are listed here.


In the next step we will installe CDO and the Net4j Signalling Platform, which is the default communication base of CDO.

InstallCDO Net4J.png

Finally to work the the example in the latter part of the tutorial we need some EMF.

CDO installEMF 2.6.png


In this tutorial we will use a H2 database. Install the "Net4j DB Framework H2 Adapter" from http://download.eclipse.org/modeling/emf/cdo/drops/R20120612-1449/ and the "H2 Database Engine" from http://download.eclipse.org/tools/orbit/downloads/drops/R20120526062928/repository/

The adapter allows Net4j to talk to an H2 database. The engine contains both the JDBC driver for H2 and the database engine.

Note: These links will probably get stale fast. Here are some guidelines to figure out where things might be:

Search for "bookmarks.xml" on the page http://www.eclipse.org/cdo/downloads/ This file contains the repositories which were imported while building CDO. You can find anything that CDO needs in there somewhere.

Get the server started

Before you can start the server it needs to be configured. CDO makes use of a configuration file. Copy the following file to a “config” folder under the root of your Eclipse folder (C:/eclipse/config) and name it cdo-server.xml.

<?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="1ff5d226-b1f0-40fb-aba2-0c31b38c764f"/>
		<property name="supportingAudits" value="true"/>

		<store type="db">
			<mappingStrategy type="horizontal">
				<property name="qualifiedNames" value="false"/>
				<property name="toManyReferences" value="ONE_TABLE_PER_REFERENCE"/>
				<property name="toOneReferences" value="LIKE_ATTRIBUTES"/>
			</mappingStrategy>
			
                        <dbAdapter name="h2"/>
			<dataSource class="org.h2.jdbcx.JdbcDataSource"
				uRL="jdbc:h2:_database/cdodb1"/>			

                   <!-- <dbAdapter name="derby-embedded"/>
			<dataSource class="org.apache.derby.jdbc.EmbeddedDataSource"
				databaseName="/temp/cdodb1"
				createDatabase="create"/>-->
                        

			<!--<dbAdapter name="hsqldb"/>
			<dataSource class="org.eclipse.net4j.db.hsqldb.HSQLDBDataSource" 
				database="jdbc:hsqldb:mem:cdodb1"
				user="sa"/>-->
			
			<!--<dbAdapter name="mysql"/>
			<dataSource class="com.mysql.jdbc.jdbc2.optional.MysqlDataSource" 
				url="jdbc:mysql://localhost/cdodb1"
				user="root"/>-->
			
			<!--<dbAdapter name="postgresql"/>
			<dataSource class="org.postgresql.ds.PGSimpleDataSource"
				url="jdbc:postgresql://localhost:5432/cdo"
				databaseName="cdo"
				user="cdo"
				password="cdo"/>-->
		</store>
	</repository>
	
</cdoServer> 

Now let us start the server. This can be achieved by creating a new run configuration. Open the Run dialog by selection Run->Run Configurations. Right click the "Eclipse Application" entry and create a new configuration. Just name it "CDO_Server". Select the "org.eclipse.emf.cdo.server.product" as new product on the "Program to Run" field.


CDO runconfig1.png

Note: On the arguments tab you can configure where your configuration file is stored. Therefore you need to add the following entry to the VM Arguments:

-Dnet4j.config=${resource_loc:<path>}

By default the "config" folder under the distribution root will be used.


On the configuration tab select "Generate a config.ini file with default content"

CDO runconfig2.png


Now hit the "Run" button. Your CDO Server will start.

CDO server started.png


Now the server hast started and additionally a H2 database. If you have not changed the default settings there will be a new folder "C:\eclipse\_database" which holds the data for the H2 db.

Prepare the Client

To prepare the client we will use the very basic EMF-library example. If you are not familiar with EMF or this famous tutorial at all, please refer to this instruction Create a new Java-Project and name it "CDO_Client" (or any other name). Create a folder called “model”. We will us the *.mdl file from the tutorial. If you have still executed the tutorial you will not need this steps. Create a new EMF-Model and name your generation model "library.genmodel".

CDO library1.png

Select import from rose model and use the following mdl file for the import (http://help.eclipse.org/help32/topic/org.eclipse.emf.doc/tutorials/clibmod/library.mdl)

CDO rose.png


This will create the generation model and the ecore for your. Now we need to convert the generation model to meet the need of CDO. Right click the genmodel and select CDO->Migrate EMF Model. This will change the model. Now you can open it and generate the code by invoking "generate all" an the model root.

CDO ecoretocdo.png

Connect the clients

Now it is time to play with CDO. Start on client by right clicking the editor plugin and selecting “Run as…->Eclipse Application”.

To start another client open the run configuration in the host eclipse. “Duplicate” the “Eclipse Application” and give the “Location” on the main tab a new folder.

CDO eclipse instance.png


Now run the second client, too. To Play with CDO we will use the CDO session view. This can be opened under "Windows->show View->Others…CDO session View"

CDO sessionview1.png


To open a new Session just click the green plus symbol. Add the location of the server. Remember the config.xml. Here we configured the port. We will use tcp as protocol by setting the acceptor to "tcp".

<acceptor type="tcp" listenAddr="0.0.0.0" port="2036">
		<!-- negotiator type="challenge" description="/temp/users.db"/ -->
	</acceptor>

That’s why we will now connect to this protocol. You might also remember the repository settings:

<repository name="repo1">…</repository>

Here we specified the name of the repository which we will now connect to.

CDO sessionview2.png

Now open a transaction on the newly created Session.

CDO transaction.png

To work with the library we need to create a new session. This can be done on the transaction itself. Name it "/res1".


This will open an editor for you. In this editor create a new Library by rightclicking the editor pane and choosing “New Root->library.ecore->Library”. After saving the editor the local data will be published to the repository.

CDO createresource.png

CDO createresource2.png


By now we have connected to the repository and created a new resource in it. Automatically a new editor has opened. Right-click the empty editor pane and add a library object as new root. You can also add a book and/or a writer.

CDO newlib.png

CDO library.png


To connect the second client repeat the previous steps in the other instance. Open the CDO view, add a session and open a transaction. But now do not create but open a resource. Again enter "/res1" as resource name.

You will see the data you added to the repository on the other client. Remember that we have an opened session on both clients. Add another book on one client and watch the other. The book will appear on the other site. Because the transaction is opened on both clients you can produce a conflict and wee what happens. Change the name of a book on one client and try to commit the data on both. The second committer will not be able to publish the book and will receive an error message.

CDO conflicts.png

Congratulation! You managed your first CDO tutorial.

Trouble Shooting

[ERROR] Unknown DB adapter: XYZ

If this error occurs while starting the server, please make sure that the correct entry is set in the config.xml. Make also sure that you have download a plugin which contains the specific database driver for your choosen database system. For example for Derby:

<dataSource class="org.apache.derby.jdbc.EmbeddedDataSource"
				databaseName="/temp/cdodb1"
				createDatabase="create"/>

org.eclipse.net4j.db.DBException: Column 'CREATED'…

If you receive the following exeption….

[ERROR] Column 'CREATED' is either not in any table in the FROM list or appears within a join specification and is outside the scope of the join specification or appears in a HAVING clause and is not in the GROUP BY list. If this is a CREATE or ALTER TABLE  statement then 'CREATED' is not a column in the target table.
org.eclipse.net4j.db.DBException: Column 'CREATED' is either not in any table in the FROM list or appears within a join specification and is outside the scope of the join specification or appears in a HAVING clause and is not in the GROUP BY list. If this is a CREATE or ALTER TABLE  statement then 'CREATED' is not a column in the target table.
	at org.eclipse.net4j.spi.db.DBAdapter.validateTable(DBAdapter.java:428)
	at org.eclipse.net4j.spi.db.DBAdapter.createTable(DBAdapter.java:144)
	at org.eclipse.net4j.spi.db.DBAdapter.createTables(DBAdapter.java:109)
	at org.eclipse.net4j.spi.db.DBSchema.create(DBSchema.java:106)
	at org.eclipse.emf.cdo.server.internal.db.DBStore.doActivate(DBStore.java:235)
	at org.eclipse.net4j.util.lifecycle.Lifecycle.activate(Lifecycle.java:65)
	at org.eclipse.net4j.util.lifecycle.LifecycleUtil.activate(LifecycleUtil.java:94)
	at org.eclipse.net4j.util.lifecycle.LifecycleUtil.activate(LifecycleUtil.java:84)
	at org.eclipse.emf.cdo.internal.server.Repository.doActivate(Repository.java:581)
	at org.eclipse.net4j.util.lifecycle.Lifecycle.activate(Lifecycle.java:65)
	at org.eclipse.net4j.util.lifecycle.LifecycleUtil.activate(LifecycleUtil.java:94)
	at org.eclipse.net4j.util.lifecycle.LifecycleUtil.activate(LifecycleUtil.java:84)
	at org.eclipse.emf.cdo.server.CDOServerUtil.addRepository(CDOServerUtil.java:73)
	at org.eclipse.emf.cdo.internal.server.RepositoryConfigurator.configure(RepositoryConfigurator.java:83)
	at org.eclipse.emf.cdo.internal.server.bundle.CDOServerApplication.doStart(CDOServerApplication.java:51)
	at org.eclipse.net4j.util.om.OSGiApplication.start(OSGiApplication.java:61)
	at org.eclipse.equinox.internal.app.EclipseAppHandle.run(EclipseAppHandle.java:194)
	at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.runApplication(EclipseAppLauncher.java:110)
	at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.start(EclipseAppLauncher.java:79)
	at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:368)
	at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:179)
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
	at java.lang.reflect.Method.invoke(Unknown Source)
	at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:559)
	at org.eclipse.equinox.launcher.Main.basicRun(Main.java:514)
	at org.eclipse.equinox.launcher.Main.run(Main.java:1311)
	at org.eclipse.equinox.launcher.Main.main(Main.java:1287)

…it may be that you have created the database specified in the server-config.xml with an older CDO version. Maybe, because you ran the Ganymede CDO getting started first. To solve this problem remove you database and let CDO create a new one.

Store factory not found: db

If you receive an exception like the following...

java.lang.IllegalStateException: Store factory not found: db
	at org.eclipse.emf.cdo.internal.server.RepositoryConfigurator.getStoreFactory(RepositoryConfigurator.java:225)
	at org.eclipse.emf.cdo.internal.server.RepositoryConfigurator.getStore(RepositoryConfigurator.java:234)
	at org.eclipse.emf.cdo.internal.server.RepositoryConfigurator.getRepository(RepositoryConfigurator.java:162)
	at org.eclipse.emf.cdo.internal.server.RepositoryConfigurator.configure(RepositoryConfigurator.java:91)
	at org.eclipse.emf.cdo.internal.server.bundle.CDOServerApplication.doStart(CDOServerApplication.java:58)
	at org.eclipse.net4j.util.om.OSGiApplication.start(OSGiApplication.java:61)
	at org.eclipse.equinox.internal.app.EclipseAppHandle.run(EclipseAppHandle.java:196)
	at org.eclipse.equinox.internal.app.AnyThreadAppLauncher.run(AnyThreadAppLauncher.java:26)
	at java.lang.Thread.run(Unknown Source)

...make sure you installed CDO and Net4J properly. In cases of doubt just re-install both SDKs.


Factory not found

It may happen that you will get a "FactoryNotFoundException" (as listed below) while connecting to the server. If so, please check igf you have correctly addressed the name of the repository. The reporitory name must match the name specified in your cdo-server.xml.


org.eclipse.net4j.util.container.FactoryNotFoundException: Factory not found: org.eclipse.emf.cdo.server.repositories[default]
	at org.eclipse.net4j.util.container.ManagedContainer.getFactory(ManagedContainer.java:193)
	at org.eclipse.net4j.util.container.ManagedContainer.createElement(ManagedContainer.java:490)
	at org.eclipse.net4j.util.container.ManagedContainer.getElement(ManagedContainer.java:281)
	at org.eclipse.net4j.util.container.ManagedContainer.getElement(ManagedContainer.java:265)
	at org.eclipse.emf.cdo.spi.server.RepositoryFactory.get(RepositoryFactory.java:43)
	at org.eclipse.emf.cdo.spi.server.ContainerRepositoryProvider.getRepository(ContainerRepositoryProvider.java:38)
	at org.eclipse.emf.cdo.internal.server.protocol.OpenSessionIndication.responding(OpenSessionIndication.java:85)
	at org.eclipse.emf.cdo.internal.server.protocol.CDOServerIndication.responding(CDOServerIndication.java:119)
	at org.eclipse.net4j.signal.IndicationWithResponse.doExtendedOutput(IndicationWithResponse.java:96)
	at org.eclipse.net4j.signal.Signal.doOutput(Signal.java:282)
	at org.eclipse.net4j.signal.IndicationWithResponse.execute(IndicationWithResponse.java:65)
	at org.eclipse.net4j.signal.Signal.runSync(Signal.java:239)
	at org.eclipse.net4j.signal.Signal.run(Signal.java:147)
	at java.util.concurrent.ThreadPoolExecutor$Worker.runTask(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
	at java.lang.Thread.run(Unknown Source)

Back to the top