EDIT

# CDM Java Library

{{>toc}}

The CDM Library is meant to be a shared library for the between several applications which can be of any kind, i.e. J2EE having an application container, simple command line tools or swing desktop applications.

The library defines a persistent domain model, EDITs [[CommonDataModel]], that can be serialised and read in XML. Business logic shared between applications should be part of this library as much as possible, while application specific logic has to stay out. We are developing this library in collaboration with the [CATE](http://www.cate-project.org/) project initially, but we seeking development collaboration with other projects like Key2Nature and PESI as well.

## Download

The latest version is available at the [[CdmLibraryDownload|CDM Library Download site]]

## Implementation

We use Wikipedia:Apache_Maven 2 for this project. The CDM library itself is devided into several maven subprojects, providing the following seperation of concerns:

* MavenSite:cdmlib-commons

* MavenSite:cdmlib-model

* MavenSite:cdmlib-persistence

* MavenSite:cdmlib-ext

* MavenSite:cdmlib-services

* MavenSite:cdmlib-remote

* MavenSite:cdmlib-io

### Current layers

![](cdmlib-arch2.png)

### Planned layers

Reuse service layer for all clients (Eclipse editor, CDM Server, CATE webapplication) and create DTOs made of preloaded domain classes instead of seperate classes.

![](cdmlib-arch3.png)

### Domain Model - _cdmlib-model_

Domain objects (also called business objects sometimes) are directly taken as POJOs from the [[CommonDataModel]]. The logic inherent to the domain objects are restricted to their own object graph, i.e. their own properties and related objects. But not unrelated objects available through DAOs only. Typical logic includes validation and calculations.

#### Property change support

We have implemented java.bean propertyChangeSupport methods for the entire cdm domain classes to send change events to registered listeners. 

The [[TaxonomicEditor]] makes use of these through a data binding framework. See wiki:JavaResources#DataBinding for more.

#### XML binding

For data exchange purposes, we want to serialize/deserialize the domain objects of the cdmlib-model to/from XML format using the [JAXB](https://jaxb.dev.java.net/) framework.

### Persistence Layer - _cdmlib-persistence_

we use Hibernate for persistence. We run unit and integration tests for [[MySQL]], Hypersonic, Postgres and MS SQL Server on a regular basis.

### API - _cdmlib-services_

Work in progress. see "CdmLibrary#Servicelayer" or wiki:CdmAPI for now.

### CDM Server - _cdmlib-remote_

That is the CdmServer community store.

### Import/Export - _cdmlib-io_

Supported import formats:

* [[BerlinModel]] database

* TCS

* ABCD

* SDD

* EDIT XML

Planned:

* DarwinCOre

* TaxonX

For more information about data conversion see [[SampleDataConversion]]

## Releases

Releases are currently in 2 flavours:

### Versioning strategy

Starting with the frozen [[CommonDataModel]] v1 we release minor upgrades for every model change in the library. Inferior version numbers (3rd level) are for bug-fixes and library extensions, which do not change the core model classes. This guarantees that all bug-fix releases are still working on the same database structure. 

For example: Svn:tags/cdmlib/rel_1.1.0 and rel_1.1.8 will work both on the same database structure as generated by hibernate. But for rel_1.2.0 you will have to update or better recreate your database, currently still losing all your data. In a later stage we will provide stable import/export formats to migrate your data to new versions.

### Change Log

All substantial changes to the library should be documented. This applies very strictly to all <B>model changes</B>. For them a separate changelog site has been setup at [[CdmChanges]].<BR>

All other changes should be documented at [[CdmLibraryChanges]].

Beside the model changes the highest priority for documentation have changes to signatures of visible methods and changes to semantics of existing methods.

If you just add some new functionality we highly appreciate it's documentation but documentation should not run into a unproductive overhead.

### Sourcecode via Subversion

The Maven project is available from our subversion server. For releases please see:

_http://dev.e-taxonomy.eu/svn/tags/cdmlib/_

### Eclipse plugin

For the cdmlib-service module we host an Eclipse plugin update site which is available here:

_http://wp5.e-taxonomy.eu/cdmlib/update/_

## CDM Library Usage

### Maven repository

To integrate the cdmlibray into your personal Maven project pelase add our Maven repository to your POM: _http://wp5.e-taxonomy.eu/cdmlib/mavenrepo/_

To use the cdm service package add the following dependency to you POM (adapt the right version number !!)

~~~

  	 <dependency>

  		<groupId>eu.etaxonomy</groupId>

  		<artifactId>cdmlib-service</artifactId>

  		<version>1.X</version>

  	</dependency>

~~~

To create a project site use mvn site:site. Due to the number of depencies you will have to increase the available memory by setting the MAVEN_OPTS parameter to 

~~~

   SET MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=512m

~~~

In order to install a file (e.g. a JAR) in you local repositry:

~~~

mvn install:install-file

      -DgroupId=<group-id>

      -DartifactId=<artifact-id>

      -Dversion=<version>

      -Dfile=<path-to-file>

      -Dpackaging=<packaging> (i.e. jar)

      -DgeneratePom=true

~~~

Also see: [How do I install a file in my local repository along with a generic POM](http://docs.codehaus.org/display/MAVENUSER/FAQs-1#FAQs-1-HowdoIinstallafileinmylocalrepositoryalongwithagenericPOM)

### Eclipse setup

To use the entire cdmlibrary with Eclipse, you need some plugins and to follow this installation guide:

* 

  * install maven 2.0.x commandline tools locally (http://maven.apache.org/download.html). Follow the instruction to install maven on your local machine.

  * install subclipse 1.4.x in eclipse if not yet installed (Update Site: http://subclipse.tigris.org/update_1.4.x). 

  * make sure Java JDK >= 1.5 is installed (JRE is not enough) and JAVA_HOME is set to JDK path

  * checkout cdmlib and create eclipse artifacts (using e.g. tortoiseSVN):

  	<pre>

$ svn co dev.e-taxonomy.eu/svn/trunk/cdmlib/

</pre>

  * make sure maven has run at least one time (to create the .m2 folder). If unsure how to do this, run `mvn install` in the new checked out folder ../cdmlib/cmlib-commons

  * Set in Eclipse preferences (not project properties) M2_REPO java class variable (menue: java-buildPath-Classpath), pointing to your local repository. 

    * In OSX for example    /Users/USERNAME/.m2/repository 

    * In WinXP for example  C:\Documents and Settings\USERNAME\.m2\repository

  * setup new eclipse workspace (where ever you want but using the cdmlib folder may be comfortable

  * create new Java project within the new workspace. Check "Create project from existing source" in the dialog. Choose ../cdmlib/cdmlib-commons as the source directory. Use project name "cdmlib-commons".

  * repeat the last step at least for all projects starting with "cdmlib-"

  * Install AspectJ Development Tools (AJDT) - Plugin (for eclipse) (Update-Site:http://download.eclipse.org/tools/ajdt/33/dev/update)

  * run 

  <pre>

$ mvn install

$ mvn eclipse:eclipse 

</pre> 

  in the cdmlib directory

  * Referesh cdmlib-model project within eclipse 

  * Convert the cdmlib-model to AspectJ (right mouse click on project -> AspectJ Tools -> ...).

![]()

* It wasn't clear to me (PC) from the above that at some point, the following must be executed in the "cdmlib" directory. I did this _after_ all the above steps were completed, and the build was successful.

 	<pre>

$ mvn install

$ mvn eclipse:eclipse

</pre>

### Spring applications with cdmlib

In your own applicationContext.xml you can simply import the cdm service spring beans from the library. In addition it also needs a datasource bean and a hibernateProperties bean specific for that datasource. The CDM Library comes with an embedded hypersonic database that is super easy to use. All you need to do is to import that hsql specific spring configuration like this:

applicationContext.xml

~~~

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

	<import resource="classpath:/eu/etaxonomy/cdm/services.xml" />

	<import resource="classpath:/eu/etaxonomy/cdm/hsql-datasource.xml" />

</beans>

~~~

In case you want to define the datasource within your own applicationContext you can surely do so. For a typical mysql database it looks like this: 

applicationContext.xml

~~~

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.springframework.org/schema/beans   http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

	<import resource="classpath:/eu/etaxonomy/cdm/services.xml" />

    <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">

        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>

        <property name="url" value="jdbc:mysql://192.168.2.10/cdm_build"/>

        <property name="username" value="cdm_user"/>

        <property name="password" value="why_do_i_need_this"/>

    </bean>

    <bean id="hibernateProperties" class="org.springframework.beans.factory.config.PropertiesFactoryBean">

        <property name="properties">

            <props>

                <prop key="hibernate.hbm2ddl.auto">validate</prop>

                <prop key="hibernate.dialect">org.hibernate.dialect.MySQLDialect</prop>

                <prop key="hibernate.cache.provider_class">org.hibernate.cache.NoCacheProvider</prop>

                <prop key="hibernate.show_sql">false</prop>

                <prop key="hibernate.format_sql">false</prop>

            </props>

        </property>

    </bean>    

</beans>

~~~

----

## Background

### Hibernate

* Hibernate works with most current RDBMS. See  [supported databases](http://www.hibernate.org/80.html) 

### Spring 2.0 Framework

We use the Spring 2.0 framework to develop the library and keep the coupling of components low.

*  [Spring2.0 Documentation](http://static.springframework.org/spring/docs/2.0.x/reference/index.html) 

*  [Introduction to the Spring Framework](http://www.theserverside.com/tt/articles/content/SpringFramework/article.html) 

*  [Die Rückkehr der POJOs. Das Spring-Framework: leichtgewichtiges Komponentenmodell als Alternative zu EJB](http://javamagazin.de/itr/online_artikel/psecom,id,608,nodeid,11.html) 

### Domain Models

* [Domain Models and Validation. An Architectural Discussion](http://forum.springframework.org/showthread.php?t=18699)

* [Avoiding anemic domain models with Hibernate](http://www.theserverside.com/patterns/thread.tss?thread_id=31010)

* [Business Object Pattern](http://www.corej2eepatterns.com/Patterns2ndEd/BusinessObject.htm)

*  [AnemicDomainModel Anti Pattern](http://www.martinfowler.com/bliki/AnemicDomainModel.html) 

#### Property Change

* http://www.onjava.com/pub/a/onjava/2004/06/02/desktop.html

* http://www.javalobby.org/java/forums/t19476.html

### Useful Patterns

* [ApplicationService Pattern](http://www.corej2eepatterns.com/Patterns2ndEd/ApplicationService.htm)

### Aspect Oriented Programming

We use AspectJ to implement the change property crosscutting concern:

* AspectJ

  * http://today.java.net/pub/a/today/2005/12/15/writing-mixins-with-aop.html

* JBoss AOP

  * http://www.damnhandy.com/javabean-aspect/

* Spring AOP

  * http://forum.springframework.org/archive/index.php/t-13293.html

  * http://forum.springframework.com/viewtopic.php?t=301