Getting started with CDO
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.4 (Ganymede). 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 EMFT-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 also can start with you 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. You can either download the CDO Plugins from the CDO Downloadpage or follow the next steps to get a feeling for the needed Plugins.
To install the packages open the Update Manager (Help->Software Updates…) and select the "Available Software" tab.
Now we need the Derby core feature to work with a derby database through the example. Just search for “derby” in the “Available Software” tab and select “Apache Derby Core Feature”
In the next step we need the net4j Platform which is the communication base of CDO.
Finally to work the the example in the latter part of the tutorial we need some EMF.
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 und 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"/> <property name="verifyingRevisions" value="false"/> <property name="currentLRUCapacity" value="10000"/> <property name="revisedLRUCapacity" value="100"/> <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="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.
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:
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"
Now hit the "Run" button. Your CDO Server will start.
Now the server hast started and additionally a derby database. If you have not changed the default settings there will be a new folder "C:\temp\cdodb1" which holds the data for the derby 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".
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)
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.
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.
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"
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:
Here we specified the name of the repository which we will now connect to.
Now open a transaction on the newly created Session.
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.
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.
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.
Congratulation! You managed your first CDO tutorial.
[ERROR] Unknown DB adapter: derby-embedded
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.
<dataSource class="org.apache.derby.jdbc.EmbeddedDataSource" databaseName="/temp/cdodb1" createDatabase="create"/>
Factory not found
It may happen that you will get a "FactoryNotFoundException" (as listed below) while connection 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)