Part I. Getting Started

This part of the reference documentation aims to provide simple step-by-step instructions to enable application developers to start using the CDM Java Library in their java application. To do this, we will create a small toy application. The CDM Java Library is packaged and published using the Apache Maven software project managment and comprehension tool. To make life easier, we'll use maven to create our application too. Assuming that Maven (2.0.x+) installed, we begin by creating a new maven application (substituting the group id, artifact id, and version of our application):

mvn archetype:create -DgroupId=org.myproject -DartifactId=myapp -Dversion=1.0

The next step is to add the EDIT maven repository to your maven project object model or pom file, thus:

. . .
<repositories>
  <repository>
    <id>EditRepository</id>
    <url>http://wp5.e-taxonomy.eu/cdmlib/mavenrepo/</url>
  </repository>
</repositories>
</project>

We also need to add the specific dependency that we would like our project to include.

. . .
<dependencies>
    <dependency>
      <groupId>eu.etaxonomy</groupId>
      <artifactId>cdmlib-services</artifactId>
      <version>1.1.1</version>
    </dependency>
  </dependencies>
<repositories>
. . .

In most cases, application developers will wish to include the cdmlib services (which include the data model and persistence layer too). In some cases, developers might wish to use components from the cdmlib-io and cdmlib-remote packages too. New releases of the CDM Java Library are published in the EDIT Maven Repository, and maven will download and use these artifacts automatically if you change the version number of the dependency specified in your pom file.

All that remains is to set up the cdmlib services within the application context. The CDM Java Library is uses the Spring Framework to manage its components. Whilst it is not mandatory to wire the CDM services and DAOs using Spring, it is certainly easier to configure your application this way. A minimal applicationContext.xml (placed in src/main/resources) file might look like this:

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

<bean id="dataSource" 
  lazy-init="true"
  class="eu.etaxonomy.cdm.database.LocalHsqldb" 	
  init-method="init"
  destroy-method="destroy">
  <property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
  <property name="username" value="sa"/>
  <property name="password" value=""/>
  <property name="startServer" value="true"/>
  <property name="silent" value="true"/>
</bean>
    
<bean id="hibernateProperties" 
  class="org.springframework.beans.factory.config.PropertiesFactoryBean">
  <property name="properties">
    <props>
      <prop key="hibernate.hbm2ddl.auto">create-drop</prop>
      <prop key="hibernate.dialect">org.hibernate.dialect.HSQLDialect</prop>
      <prop key="hibernate.cache.provider_class">org.hibernate.cache.NoCacheProvider</prop>
    </props>
  </property>
</bean>

The first element imports the cdmlib service definitions. The two other beans supply a data source and a properties object that the CDM library uses to configure the hibernate session factory and connect to the database. In this case, we're using an in-memory HSQL database, but the CDM can be used with many other databases. The only thing left to do is to start using the CDM services. In real applications, CDM services may well be autowired into components using Spring or another dependency injection mechanism. To keep this example simple, we'll initialize the application context and obtain a service programatically.

ApplicationContext context = new ClassPathXmlApplicationContext("applicationContext.xml");

INameService nameService = (INameService)context.getBean("nameServiceImpl");

BotanicalName botanicalName = BotanicalName.NewInstance(Rank.SPECIES());
botanicalName.setGenusOrUninomial("Arum");
botanicalName.setSpecificEpithet("maculatum");
UUID uuid = nameService.saveTaxonName(botanicalName);

System.out.println("Saved \'Arum maculatum\' under uuid " + uuid.toString());

In this simple example, we've covered the basics of using the CDM Java Library. We created a simple maven project, and added the repository and a single dependency to our pom file. We then created a simple application context that used the default CDM configuration, and specified a couple of objects that allowed the CDM to connect to a database. Finally we initialized these services by loading the application context, and then retrieved a specific service, and used it to persist a new taxonomic name.