+ <part>
+ <title>Getting Started</title>
+
+ <partintro>
+ <para>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):</para>
+
+ <screen>mvn archetype:create -DgroupId=<emphasis>org.myproject</emphasis> -DartifactId=<emphasis>myapp</emphasis> -Dversion=<emphasis>1.0</emphasis></screen>
+
+ <para>The next step is to add the EDIT maven repository to your maven
+ <emphasis>project object model</emphasis> or <emphasis>pom</emphasis>
+ file, thus:</para>
+
+ <programlisting>. . .
+<repositories>
+ <repository>
+ <id>EditRepository</id>
+ <url>http://wp5.e-taxonomy.eu/cdmlib/mavenrepo/</url>
+ </repository>
+</repositories>
+</project></programlisting>
+
+ <para>We also need to add the specific dependency that we would like our
+ project to include.</para>
+
+ <programlisting>. . .
+<dependencies>
+ <dependency>
+ <groupId>eu.etaxonomy</groupId>
+ <artifactId>cdmlib-services</artifactId>
+ <version>1.1.1</version><!--ben: We will need to change this to reflect the new release once it is available-->
+ </dependency>
+ </dependencies>
+<repositories>
+. . .</programlisting>
+
+ <para>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
+ <package>cdmlib-io</package> and <package>cdmlib-remote</package>
+ 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.</para>
+
+ <para>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
+ <filename>src/main/resources</filename>) file might look like
+ this:</para>
+
+ <programlisting><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></programlisting>
+
+ <para>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.</para>
+
+ <programlisting>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);<!--ben: Again, this example reflects the 1.1.1 release, and will need to be changed slightly once the new release is available-->
+
+System.out.println("Saved \'Arum maculatum\' under uuid " + uuid.toString());</programlisting>
+
+ <para>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.</para>
+ </partintro>
+ </part>
+