src/site/apt/getting-started.apt

   1                 ----
   2                 Developing with the CDM Library
   3                 ----
   4
   5
   6 Developing with the CDM Library
   7
   8         <Table of Contents>
   9
  10 %{toc|section=0|fromDepth=2|toDepth=3}
  11
  12
  13   <<Note:>> The CDM Library uses Apache Maven for dependency management. If you are not familiar with that please take a look at the {{{https://dev.e-taxonomy.eu/trac/wiki/GeneralDev#Maven}developer resources on the wiki}}. In case you run into problems, you might want to check {{{./troubleshooting.html}Troubleshooting}} or contact {{{mailto:editsupport@bgbm.org}editsupport@bgbm.org}} directly.
  14
  15 * Integrating the CDM Library into a maven project
  16
  17         To integrate the CDM Library into your personal maven project pelase add our maven repository to your POM:
  18         {{http://wp5.e-taxonomy.eu/cdmlib/mavenrepo/}}. To use the <cdmlib-service> package add the following
  19         dependency to you POM (adapt the right version number !!):
  20
  21 ---
  22 <dependency>
  23         <groupId>eu.etaxonomy</groupId>
  24         <artifactId>cdmlib-service</artifactId>
  25         <version>x.x</version>
  26 </dependency>
  27 ---
  28
  29
  30 * Spring applications with the CDM Library
  31
  32         In your own applicationContext.xml you can simply import the cdm service spring beans from the library.
  33         In addition it also needs a datasource bean and a hibernateProperties bean specific for that datasource.
  34         The CDM Library comes with an embedded hypersonic database that is super easy to use. All you need to do
  35         is to import that hsql specific spring configuration like this:
  36
  37 ---
  38 applicationContext.xml
  39
  40 <?xml version="1.0" encoding="UTF-8"?>
  41 <beans xmlns="http://www.springframework.org/schema/beans"
  42     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  43     xsi:schemaLocation="http://www.springframework.org/schema/beans
  44                 http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
  45
  46         <import resource="classpath:/eu/etaxonomy/cdm/services.xml" />
  47         <import resource="classpath:/eu/etaxonomy/cdm/hsql-datasource.xml" />
  48
  49 </beans>
  50 ---
  51
  52         In case you want to define the datasource within your own applicationContext you can surely do so.
  53         For a typical mysql database it looks like this:
  54
  55 ---
  56 applicationContext.xml
  57
  58 <?xml version="1.0" encoding="UTF-8"?>
  59 <beans xmlns="http://www.springframework.org/schema/beans"
  60     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  61     xsi:schemaLocation="http://www.springframework.org/schema/beans
  62                 http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
  63
  64         <import resource="classpath:/eu/etaxonomy/cdm/services.xml" />
  65
  66     <bean id="dataSource"
  67                         class="org.springframework.jdbc.datasource.DriverManagerDataSource">
  68         <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
  69         <property name="url" value="jdbc:mysql://192.168.2.10/cdm_build"/>
  70         <property name="username" value="cdm_user"/>
  71         <property name="password" value="why_do_i_need_this"/>
  72     </bean>
  73
  74     <bean id="hibernateProperties"
  75                         class="org.springframework.beans.factory.config.PropertiesFactoryBean">
  76         <property name="properties">
  77             <props>
  78                 <prop key="hibernate.hbm2ddl.auto">validate</prop>
  79                 <prop key="hibernate.dialect">org.hibernate.dialect.MySQLDialect</prop>
  80                 <prop key="hibernate.cache.provider_class">
  81                                         org.hibernate.cache.NoCacheProvider
  82                                 </prop>
  83                 <prop key="hibernate.show_sql">false</prop>
  84                 <prop key="hibernate.format_sql">false</prop>
  85             </props>
  86         </property>
  87     </bean>
  88 </beans>
  89 ---
  90
  91
  92 * Developing the CDM Library with Eclipse
  93
  94         To use the entire CDM Library with {{{http://www.eclipse.org/} Eclipse}}, you must meet the following prerequisites:
  95
  96     * Maven 2.2.1 commandline tools. Follow the instruction to install maven on your local machine. See {{{https://dev.e-taxonomy.eu/trac/wiki/GeneralDev#Maven}}} for installation instructions.
  97
  98     * Subclipse 1.6.x (for convenient subversion access from Eclipse). {{{http://subclipse.tigris.org/}}}
  99
 100     * Java JDK >= 1.6 (JRE is not enough) and JAVA_HOME is set to JDK path
 101
 102         []
 103
 104 ** Preparing the CDM Library
 105
 106         Start by checking out the source code from the subversion repository:
 107
 108 ---
 109 $ svn co http://dev.e-taxonomy.eu/svn/trunk/cdmlib/ .
 110 ---
 111
 112         Change into the cdmlib directory, compile and install the cdmlib packages in your local repository. This will also download the dependencies into your local repository.
 113
 114 ---
 115 $ cd cdmlib
 116 $ mvn install
 117 ---
 118
 119         Let maven create project dependencies and Eclipse metafiles (.project s.o.)
 120
 121 ---
 122 $ mvn eclipse:eclipse
 123 ---
 124
 125 ** Configuring Eclipse
 126
 127         * Setup a new Eclipse workspace (where ever you want but using the cdmlib folder may be comfortable)
 128
 129         * In Eclipse preferences (not project properties) set a java class variable called <<<M2_REPO>>>, pointing to your local repository.
 130
 131                 * Eclipse Preferences: Java -> Build Path -> Classpath
 132
 133                 * Click <<<New>>>. In the upcoming dialog, enter <<<M2_REPO>>> as the variables name and browse the filesystem for the location of the maven repository
 134
 135                         * In OSX for example    <<</Users/USERNAME/.m2/repository>>>
 136
 137                         * In WinXP for example  <<<C:\Documents and Settings\USERNAME\.m2\repository>>>
 138
 139         * Import the cdmlib projects:
 140
 141                 * In Eclipse open the Import Wizard: File -> Import -> General -> Existing Projects into Workspace
 142
 143                 * Choose "Select root directory". Click "Browse" and navigate to your cdmlib folder and confirm the file dialog.
 144
 145                 * The projects should now show in the Import Wizard window. Select the projects you want wo work on (usually all) and hit OK.
 146
 147 * Getting started with the cdmlib based web services
 148
 149     A good starting point for getting familiar with the cdmlib based web services is this documentation
 150     on the cdm-server in general, and the documentation on the {{{rest-api.html} CDM REST API}}.
 151     Usually you will be mostly interested into the generic API Service which exposes more or less
 152     one to one the service layer of the CDM architecture to the web.
 153
 154     If you want to take a look at the code, the almost all of the web service implementation
 155     is found in the maven sub module <<<cdmlib/cdmlib-remote>>>. Inside this module the controllers
 156     are found in <<</src/main/java/eu/etaxonomy/cdm/remote/controller>>>.
 157     The serialization to json and xml is done by <<<JSON-lib>>> but we might switch to Jackson in the future.
 158     Beans which support the serialization are found in <<</src/main/java/eu/etaxonomy/cdm/remote/json>>>,
 159     and last but not least you will also be interested into the configuration which ties everything
 160     together: <<</src/main/resources/eu/etaxonomy/cdm/remote/json/jsonConfigurations.xml>>>
 161     The maven module module <<<cdmlib/cdmlib-remote>>> only contains the views and the controllers.
 162     All parts (mostly configuration) required to let it run in a web application context are
 163     contained in another module <<<cdmlib/cdmlib-remote-webapp>>>, this module actually is run as a
 164     server instance by the {{{/cdm-server}cdm-server}}, configuration files are found in <<</src/main/webapp/WEB-INF/>>>
 165
 166 * Where do I go from here?
 167
 168         Now that you have integrated or installed the CDM Library you are probably looking for documentation
 169         on how to develop with it. A good start is to read the {{{./reference.html}reference documentation}}
 170         of the CDM Library. The {{{./cdm-uml}UML diagrams}} are also a good starting point to get familiar
 171         with the structure of the Common Data Model itself or consult the {{{./apidocs}javadoc}} for the API documentation.
 172         Please also have a look at the {{{http://dev.e-taxonomy.eu/trac/wiki/GeneralDev} general information}} and
 173         {{{http://dev.e-taxonomy.eu/trac/wiki/CdmLibraryDev} further information about coding with the CDM Library}} in the development wiki.
 174
 175
 176