src/docbkx/ReferenceDocumentation.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <book version="5.0"
   3       xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd"
   4       xml:id="cdm-reference-guide" xmlns="http://docbook.org/ns/docbook"
   5       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   6       xmlns:xs="http://www.w3.org/2001/XMLSchema"
   7       xmlns:xlink="http://www.w3.org/1999/xlink"
   8       xmlns:xi="http://www.w3.org/2001/XInclude"
   9       xmlns:ns5="http://www.w3.org/1999/xhtml"
  10       xmlns:ns4="http://www.w3.org/2000/svg"
  11       xmlns:ns3="http://www.w3.org/1998/Math/MathML"
  12       xmlns:ns="http://docbook.org/ns/docbook">
  13   <bookinfo>
  14     <title>EDIT Common Data Model Library</title>
  15
  16     <subtitle>Reference Documentation (Work in Progress)</subtitle>
  17
  18     <corpauthor>
  19       <inlinegraphic fileref="./resources/images/logo.png" />
  20     </corpauthor>
  21
  22     <!-- Please add your names here -->
  23
  24     <authorgroup>
  25       <author>
  26         <personname>Ben Clark</personname>
  27       </author>
  28     </authorgroup>
  29
  30     <releaseinfo>2.1</releaseinfo>
  31
  32     <copyright>
  33       <year>2009</year>
  34
  35       <holder>EDIT - European Distributed Institute of Taxonomy -
  36       http://www.e-taxonomy.eu</holder>
  37     </copyright>
  38
  39     <legalnotice>
  40       <para>The contents of this file are subject to the Mozilla Public
  41       License Version 1.1. See LICENSE.TXT at the top of this package for the
  42       full license terms.</para>
  43     </legalnotice>
  44   </bookinfo>
  45
  46   <toc />
  47
  48   <preface id="preface">
  49     <title>Preface</title>
  50
  51     <para>EDIT's Internet Platform for Cybertaxonomy is a distributed
  52     computing platform that helps taxonomists do revisionary taxonomy and
  53     taxonomic field work efficiently and expediently via the web. At the core
  54     of the platform lies a common data model to enable interoperability
  55     between the different components. The model describes all the commonly
  56     used data that is dealt with in the platform, and therefore covers
  57     taxonomic names and concepts; literature references; authors; (type)
  58     specimen; structured descriptive data; molecular data; related (binary)
  59     files such as images or compiled keys; controlled vocabularies and terms;
  60     and species related content of any kind like economic use or conservation
  61     status.</para>
  62
  63     <para>The cyberplatform consists of interoperable but independent
  64     components. Platform components can take the form of software applications
  65     (desktop or web-based) for human users or (web) services intended to be
  66     used by other software applications. The platform as envisioned does not
  67     have a single user interface or website; rather, it is a collection of
  68     interacting components which may be combined and assembled according to
  69     the task in hand. To facilitate the development of core CDM Applications
  70     such as the CDM Community Server, the CDM Dataportals, and the Taxonomic
  71     Editor, an implementation of the CDM has been created in the java
  72     programming language. In addition to CDM model classes being modelled as
  73     plain-old-java-objects (<link
  74     xlink:href="http://en.wikipedia.org/wiki/Plain_Old_Java_Object">pojo's</link>),
  75     a set of java components has been created that provide common services
  76     across all java applications using the CDM. In addition to serving as the
  77     basis of core components of the Internet Platform for Cyberplatform, they
  78     also allow the development of other applications using the CDM by
  79     providing basic functionality that can be extended for a particular
  80     purpose.</para>
  81
  82     <para>The CDM Library, as it is known, consists of four major modules that
  83     can be used by any java application based on the CDM. These libraries are
  84     used as the foundation of the Taxonomic Editor and the CDM Community
  85     Server. In addition a web application (the CDM Community Server) is
  86     documented here, as its components can be re-purposed or extended by other
  87     web applications based on the CDM.</para>
  88
  89     <figure>
  90       <mediaobject>
  91         <imageobject role="html">
  92           <imagedata fileref="resources/images/cdmlib-arch3.png" format="png" />
  93         </imageobject>
  94
  95         <imageobject role="fo">
  96           <imagedata contentwidth="160mm"
  97                      fileref="resources/images/cdmlib-arch3.png" format="png"
  98                      scalefit="1" />
  99         </imageobject>
 100
 101         <caption>The overall architecture of the EDIT Internet platform for
 102         Cybertaxonomy, showing the core components of the CDM Java Library,
 103         and their use by desktop (Taxonomic Editor) and web-based (CDM
 104         Dataportal, CATE) applications.</caption>
 105       </mediaobject>
 106     </figure>
 107   </preface>
 108
 109   <part>
 110     <title>Common Data Model</title>
 111
 112     <partintro>
 113       <para>The Common Data Model (CDM) is the domain model for the core EDIT
 114       cyberplatform components. The CDM is primarily based on the <link
 115       linkend="???"
 116       xlink:href="http://wiki.tdwg.org/twiki/bin/view/TAG/LsidVocs">TDWG
 117       Ontology</link> and in most cases there is concordance with relevant
 118       TDWG standards such as <link linkend="???"
 119       xlink:href="http://www.tdwg.org/standards/117/">Taxon Concept Transfer
 120       Schema (TCS)</link>, <link linkend="???"
 121       xlink:href="http://www.tdwg.org/standards/117/">Structured Descriptive
 122       Data (SDD)</link> and <link linkend="???"
 123       xlink:href="http://www.tdwg.org/standards/115/">Access to Biological
 124       Collections Data (ABCD)</link>.</para>
 125
 126       <para>The CDM differs from the TDWG standards in its purpose: it is
 127       intended to serve as the basis of software applications in the
 128       cyberplatform (e.g. the taxonomic editor, the CDM Dataportals) rather
 129       than being a standard for data exchange between any resource containing
 130       biodiversity information. Whilst it is certainly possible to exchange
 131       data as CDM domain objects serialized as XML or JSON (the CDM Server and
 132       the CDM Dataportals do this), the common data model is not intended to
 133       replace existing TDWG standards as a general purpose exchange standard.
 134       It is possible to convert data held in a CDM store into a relevant TDWG
 135       standard for exchange and in some cases this may be the desired route
 136       for data held in the CDM (e.g. for exchange with an application that is
 137       not part of the cyberplatform, but which is capable of understanding
 138       data in a TDWG standard).</para>
 139
 140       <para>Thus the CDM is intended for use as</para>
 141
 142       <itemizedlist>
 143         <listitem>
 144           <para>A domain model for applications, particularly those that
 145           enable taxonomists to do revisionary taxonomy and taxonomic field
 146           work</para>
 147         </listitem>
 148
 149         <listitem>
 150           <para>A standard for exchange between applications that are part of
 151           the EDIT Internet Platform for Cybertaxonomy</para>
 152         </listitem>
 153       </itemizedlist>
 154
 155       <para>In terms of scope, the CDM covers information core to the vision
 156       of the cyberplatform i.e. descriptive and revisionary taxonomy,
 157       including taxonomic fieldwork :-</para>
 158
 159       <itemizedlist>
 160         <listitem>
 161           <para>Taxonomic names and nomenclature, typification</para>
 162         </listitem>
 163
 164         <listitem>
 165           <para>Taxonomic concepts and relationships between accepted names
 166           and synonyms, including the placement of the same taxonomic concept
 167           in different taxonomic hierarchies.</para>
 168         </listitem>
 169
 170         <listitem>
 171           <para>Specimens and Observations of individual organisms, their
 172           collection, location, processing and taxonomic determination.</para>
 173         </listitem>
 174
 175         <listitem>
 176           <para>Structured and unstructured information about names, taxa, and
 177           specimens.</para>
 178         </listitem>
 179       </itemizedlist>
 180
 181       <para>In addition to this core area, the CDM covers some related domains
 182       that are important:-</para>
 183
 184       <itemizedlist>
 185         <listitem>
 186           <para>Literature</para>
 187         </listitem>
 188
 189         <listitem>
 190           <para>People, teams of people and institutions in various roles
 191           (i.e. as authors, collectors, artists, rights holders etc)</para>
 192         </listitem>
 193
 194         <listitem>
 195           <para>Media (images, video and audio files, plus more
 196           taxonomy-specific media such as phylogenies and compiled
 197           keys)</para>
 198         </listitem>
 199
 200         <listitem>
 201           <para>Molecular data, such as DNA sequences and loci</para>
 202         </listitem>
 203       </itemizedlist>
 204
 205       <para>As you might expect, there are also a number of data entities
 206       representing controlled vocabularies, identity of users (and their roles
 207       and permissions), and ancillary data common to all major classes such as
 208       multilingual text content, annotations and markers.</para>
 209
 210       <figure>
 211         <title>A UML Package diagram showing the CDM packages and their
 212         members.</title>
 213
 214         <mediaobject>
 215           <imageobject role="html">
 216             <imagedata fileref="resources/images/ModelOverview20.gif" />
 217           </imageobject>
 218
 219           <imageobject role="fo">
 220             <imagedata contentwidth="160mm"
 221                        fileref="resources/images/ModelOverview20.gif"
 222                        scalefit="1" />
 223           </imageobject>
 224         </mediaobject>
 225       </figure>
 226     </partintro>
 227
 228     <xi:include href="base-classes.xml" />
 229
 230     <!--<xi:include href="annotation-and-markers.xml" />-->
 231
 232     <!--<xi:include href="extensions.xml" />-->
 233
 234     <!--<xi:include href="identifiable-entities.xml" />-->
 235
 236     <!--<xi:include href="validation.xml" />-->
 237   </part>
 238
 239   <part>
 240     <title>Persistence Layer</title>
 241
 242     <partintro>
 243       <para>Even the most basic of taxonomic applications have a requirement
 244       for users to be able to save the information that they create. In
 245       addition, a common component of taxonomic applications is the use of a
 246       database to provide users with the ability to filter or search their
 247       data in one way or another. Some applications will require more advanced
 248       functionality, such as auditing or versioning of data. All of this logic
 249       is contained in the persistence layer, providing clean separation
 250       between data access and more taxonomy-centric business logic in the
 251       service layer.</para>
 252
 253       <para>Persistence is not a simple problem to solve, especially in
 254       application developed in Object-Oriented languages, with large amounts
 255       of data, or with many users accessing data at the same time. The CDM
 256       Library uses the <link
 257       xlink:href="http://www.hibernate.org">Hibernate</link> object/relational
 258       persistence and query service as the basis of its persistence layer.
 259       Several member projects of the Hibernate stable, including <link
 260       xlink:href="http://annotations.hibernate.org">Hibernate
 261       Annotations</link>, <link linkend="???"
 262       xlink:href="http://search.hibernate.org">Hibernate Search</link> and
 263       <link linkend="???">Hibernate Envers</link> (part of Hibernate Core)
 264       provide the basis of the more advanced persistence-related functionality
 265       in the CDM Library. As a consequence some of the behaviour of the CDM
 266       Library is constrained by the underlying ORM technology. The advantage
 267       of using an ORM is that the same software can be used with multiple
 268       database systems with (almost) no changes to the application. Currently
 269       the CDM Library has been tested with (version numbers &amp; platforms in
 270       brackets)</para>
 271
 272       <!--I don't know how many of these have been tested, on which platforms, but it would be good to include some measure of which platform / database combinations
 273 have been used and how, so that potential users can evaluate the technology. In an ideal world, we would pick some databases as "supported" and ensure that
 274 the test suite runs on that platform / db combination (i.e. you don't release until the tests pass). For the others, we still might want to say: "We tested
 275 the CDM on this platform and it seemed to work".-->
 276
 277       <itemizedlist>
 278         <listitem>
 279           <para>IBM <link
 280           xlink:href="http://www.ibm.com/software/data/db2/">DB2</link></para>
 281         </listitem>
 282
 283         <listitem>
 284           <para><link xlink:href="???">H2</link> (default local database used
 285           by the Taxonomic Editor, 1.0.73)</para>
 286         </listitem>
 287
 288         <listitem>
 289           <para>
 290             <link xlink:href="http://hsqldb.org">HSQLDB</link>
 291           </para>
 292         </listitem>
 293
 294         <listitem>
 295           <para><link xlink:href="http://www.mysql.com">MySQL</link> (4.1.20:
 296           linux; 5.1.32: windows)</para>
 297         </listitem>
 298
 299         <listitem>
 300           <para>
 301             <link xlink:href="???">ODBC</link>
 302           </para>
 303         </listitem>
 304
 305         <listitem>
 306           <para>
 307             <link
 308             xlink:href="http://www.oracle.com/database/index.html">Oracle
 309             Database 11<emphasis>g</emphasis></link>
 310           </para>
 311         </listitem>
 312
 313         <listitem>
 314           <para>
 315             <link xlink:href="http://www.postgresql.org/">PostgreSQL</link>
 316           </para>
 317         </listitem>
 318
 319         <listitem>
 320           <para>
 321             <link xlink:href="???">Microsoft SQL Server 2000</link>
 322           </para>
 323         </listitem>
 324
 325         <listitem>
 326           <para>
 327             <link linkend="???"
 328             xlink:href="http://www.microsoft.com/sqlserver/2005/">Microsoft
 329             SQL Server 2005</link>
 330           </para>
 331         </listitem>
 332
 333         <listitem>
 334           <para>
 335             <link linkend="???" xlink:href="http://www.sybase.co.uk/">Sybase
 336             Advantage Database Server</link>
 337           </para>
 338         </listitem>
 339       </itemizedlist>
 340
 341       <para>In theory, application developers should not need to use the
 342       persistence layer directly, but should instead use the <link
 343       linkend="api">API</link>, which provides a <emphasis>facade</emphasis>
 344       over the persistence layer and extra business logic that most
 345       applications using the CDM will require.</para>
 346     </partintro>
 347
 348     <xi:include href="basic-persistence.xml" />
 349
 350     <!--<xi:include href="listing-sorting-initializing.xml" />-->
 351
 352     <!--<xi:include href="versioning.xml" />-->
 353
 354     <!--<xi:include href="free-text-search.xml" />-->
 355   </part>
 356
 357   <part xml:id="api">
 358     <title>API Methods</title>
 359
 360     <partintro>
 361       <para>This part discusses the service layer:</para>
 362     </partintro>
 363
 364     <!--<xi:include href="service.xml" />-->
 365
 366     <!--<xi:include href="paging-resultsets.xml" />-->
 367
 368     <!--<xi:include href="application-controller.xml" />-->
 369
 370     <!--<xi:include href="transactions.xml" />-->
 371
 372     <!--<xi:include href="guid-resolution.xml" />-->
 373
 374     <!--<xi:include href="security.xml" />-->
 375   </part>
 376
 377   <part>
 378     <title>CDM Input / Output Layer</title>
 379
 380     <partintro>
 381       <para>This part describes the input output routines:</para>
 382     </partintro>
 383
 384     <!--<xi:include href="base-io-usage.xml" />-->
 385
 386     <!--<xi:include href="cdm-xml-input-output.xml" />-->
 387
 388     <!--<xi:include href="abcd-input-output.xml" />-->
 389
 390     <!--<xi:include href="berlinmodel-input-output.xml" />-->
 391
 392     <!--<xi:include href="excel-input-output.xml" />-->
 393
 394     <!--<xi:include href="sdd-input-output.xml" />-->
 395
 396     <!--<xi:include href="taxonx-input-output.xml" />-->
 397
 398     <!--<xi:include href="tcsrdf-input-output.xml" />-->
 399
 400     <!--<xi:include href="tcsxml-input-output.xml" />-->
 401   </part>
 402
 403   <part>
 404     <title>CDM Server</title>
 405
 406     <partintro>
 407       <para>This part describes the cdm-server application:</para>
 408     </partintro>
 409
 410     <!--<xi:include href="cdm-server.xml" />-->
 411
 412     <!--<xi:include href="instalation.xml" />-->
 413
 414     <!--<xi:include href="configuration.xml" />-->
 415   </part>
 416 </book>