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/redmine/projects/edit/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://cybertaxonomy.eu/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-services</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.cj.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 3 commandline tools. Follow the instruction to install maven on your local machine. See {{{https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/GeneralDev#Maven}}} for installation instructions.
|
97
|
|
98
|
* Git
|
99
|
|
100
|
* Java JDK >= 1.8 (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 git repository:
|
107
|
|
108
|
---
|
109
|
$ git clone https://dev.e-taxonomy.eu/git/cdmlib.git
|
110
|
$ git clone ssh://git@dev.e-taxonomy.eu/var/git/cdmlib.git
|
111
|
---
|
112
|
|
113
|
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.
|
114
|
You will need to configure the MAVEN_OPTS environment variable to configure JVM memory (-Xmx600M). The below example commands uses the 'export' command which is available in most default shells in Linux.
|
115
|
|
116
|
---
|
117
|
$ cd cdmlib
|
118
|
$ export MAVEN_OPTS=-Xmx600M
|
119
|
$ mvn install
|
120
|
---
|
121
|
|
122
|
Let maven create project dependencies and Eclipse metafiles (.project s.o.)
|
123
|
|
124
|
---
|
125
|
$ mvn eclipse:eclipse
|
126
|
---
|
127
|
|
128
|
** Configuring Eclipse
|
129
|
|
130
|
* Setup a new Eclipse workspace (where ever you want but using the cdmlib folder may be comfortable)
|
131
|
|
132
|
* In Eclipse preferences (not project properties) set a java class variable called <<<M2_REPO>>>, pointing to your local repository.
|
133
|
|
134
|
* Eclipse Preferences: Java -> Build Path -> Classpath
|
135
|
|
136
|
* Click <<<New>>>. In the upcoming dialog, enter <<<M2_REPO>>> as the variables name and browse the filesystem for the location of the maven repository
|
137
|
|
138
|
* In OSX for example <<</Users/USERNAME/.m2/repository>>>
|
139
|
|
140
|
* In WinXP for example <<<C:\Documents and Settings\USERNAME\.m2\repository>>>
|
141
|
|
142
|
* Import the cdmlib projects:
|
143
|
|
144
|
* In Eclipse open the Import Wizard: File -> Import -> General -> Existing Projects into Workspace
|
145
|
|
146
|
* Choose "Select root directory". Click "Browse" and navigate to your cdmlib folder and confirm the file dialog.
|
147
|
|
148
|
* The projects should now show in the Import Wizard window. Select the projects you want wo work on (usually all) and hit OK.
|
149
|
|
150
|
* Getting started with the cdmlib based web services
|
151
|
|
152
|
A good starting point for getting familiar with the cdmlib based web services is this documentation
|
153
|
on the cdm-server in general, and the documentation on the {{{rest-api.html} CDM REST API}}.
|
154
|
Usually you will be mostly interested into the generic API Service which exposes more or less
|
155
|
one to one the service layer of the CDM architecture to the web.
|
156
|
|
157
|
If you want to take a look at the code, the almost all of the web service implementation
|
158
|
is found in the maven sub module <<<cdmlib/cdmlib-remote>>>. Inside this module the controllers
|
159
|
are found in <<</src/main/java/eu/etaxonomy/cdm/remote/controller>>>.
|
160
|
The serialization to json and xml is done by <<<JSON-lib>>> but we might switch to Jackson in the future.
|
161
|
Beans which support the serialization are found in <<</src/main/java/eu/etaxonomy/cdm/remote/json>>>,
|
162
|
and last but not least you will also be interested into the configuration which ties everything
|
163
|
together: <<</src/main/resources/eu/etaxonomy/cdm/remote/json/jsonConfigurations.xml>>>
|
164
|
The maven module module <<<cdmlib/cdmlib-remote>>> only contains the views and the controllers.
|
165
|
All parts (mostly configuration) required to let it run in a web application context are
|
166
|
contained in another module <<<cdmlib/cdmlib-remote-webapp>>>, this module actually is run as a
|
167
|
server instance by the {{{/cdm-server}cdm-server}}, configuration files are found in <<</src/main/webapp/WEB-INF/>>>
|
168
|
|
169
|
* Where do I go from here?
|
170
|
|
171
|
Now that you have integrated or installed the CDM Library you are probably looking for documentation
|
172
|
on how to develop with it. A good start is to read the {{{./reference.html}reference documentation}}
|
173
|
of the CDM Library. The {{{./cdm-uml}UML diagrams}} are also a good starting point to get familiar
|
174
|
with the structure of the Common Data Model itself or consult the {{{./apidocs}javadoc}} for the API documentation.
|
175
|
Please also have a look at the {{{https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/GeneralDev} general information}} and
|
176
|
{{{https://dev.e-taxonomy.eu/redmine/projects/edit/wiki/CdmLibraryDev} further information about coding with the CDM Library}} in the development wiki.
|
177
|
|
178
|
|
179
|
|