As we explained in the Common Meta-data section, Common meta-data provides a global lookup mechanism for meta-data and alias definitions. It integrates with OSEM definitions and Gps::Jdbc mappings, externalising (and centralising) the actual semantic lookup keys that will be stored in the index. It also provides an Ant task to provides a constant Java class definitions for all the common meta-data definitions which can be used by Java application to lookup and store Compass Resource.

Defining a common meta-data definition is an optional step when integrating Compass. Though taking the time and creating one can provides valuable information and centralisation of the system (or systems) semantic definitions.

In the petclinic sample, the Common meta-data file is located in the org.compass.sample.petclinic package, and is called petclinic.cmd.xml. A fragment of it is shown here:

<?xml version="1.0"?>
<!DOCTYPE compass-core-meta-data PUBLIC
    "-//Compass/Compass Core Meta Data DTD 2.2//EN"
    "http://www.compass-project.org/dtd/compass-core-meta-data-2.2.dtd">

<compass-core-meta-data>

    <meta-data-group id="petclinic" displayName="Petclinic Meta Data">

        <description>Petclinic Meta Data</description>
        <uri>http://compass/sample/petclinic</uri>

        <alias id="vet" displayName="Vet">
            <description>Vet alias</description>
            <uri>http://compass/sample/petclinic/alias/vet</uri>
            <name>vet</name>
        </alias>

        <!-- ...... more alias definitions -->


        <meta-data id="birthdate" displayName="Birthdate">
            <description>The birthdate</description>
            <uri>http://compass/sample/petclinic/birthdate</uri>
            <name format="yyyy-MM-dd">birthdate</name>
        </meta-data>


        <!-- ...... more meta-data definitions -->

    </meta-data-group>

</compass-core-meta-data>

The above fragment of the common meta-data definitions, declares an alias called vet and meta-data called birthdate. The birthdate meta-data example shows one of the benefits of using common meta-data. The format of the date field is defined in the meta-data, instead of defining it in every mapping of birtdate meta-data (in OSEM for example).

One of the features of the search engine abstraction layer is the use of Resource and Property. As well as simple and minimal Resource Mapping definitions.

Although it is not directly used, the Jdbc implementation of the data access layer uses Search Engine API, based on Resources and resource mappings (the Jdbc device of Compass::Gps can automatically generate them).

One of the main features of Compass is OSEM (Object / Search Engine Mapping), and it is heavily used in the petclinic sample. OSEM maps Java objects (domain model) to the underlying search engine using simple mapping definitions.

The petclinic sample uses most of the features provided by OSEM, among them are: contract, with mappings defined for the Entity, NamedEntity, and Person (all are "abstract" domain definitions), Cyclic references are defined (for example between pet and owner), and many more. The OSEM definitions can be found at the petclinic.cpm.xml file.

Compass::Gps comes with the Hibernate device. The device can index the data mapped by Hibernate, and mirror any data changes made by Hibernate to the search engine index. Since we are using Hibernate with Spring, the device used is the Spring Hibernate device.

The integration uses the OSEM definitions, working with Compass object level API to interact with the underlying search engine. The spring application context bean definitions for the compass (required by the Hibernate Gps device) instance is defined with OSEM definitions and spring based transaction support. The applicationContext-hibernate.xml in the test package, and the applicationContext-hibernate.xml in the WEB-INF directory define all the required definitions to work with hibernate and compass. Note, that only the mentioned configuration has to be created in order to integrate compass to the data access layer.

Compass::Gps comes with the JDBC device. The Jdbc device can connect to a database using jdbc, and based on different mappings defentions, index it's content and mirror any data changes. When using the Jdbc device, the mapping is made on the Resource level (cannot use OSEM).

It is important to understand the different options for integrating Compass for a Jdbc (or a Jdbc helper framework like Spring or iBatis) data access implementation. If the system has no domain model, than Resource level API and mapping must be used. The Jdbc device can automate most of the actions needed to index and mirror the database. If the system has a domain model (such as the petclinic sample), two options are available: working on the Resource level and again using the Jdbc device, or using OSEM definitions, and plumb Compass calls to the data access API's (i.e. save the Vet in compass when the Vet is saved to the database). In the petclinic sample, the Jdbc device option was taken in order to demonstrate the Jdbc device usage. An API level solution should be simple, especially if the system has decent and centralized data access layer (which in our case it does).

The integration uses the Jdbc Gps Device mapping definitions and works with Compass object level API to work with the search engine. The spring application context bean definitions for the compass (required by the Jdbc Gps device) instance are defined with Jdbc mapping resolvers, and Local transactions. The applicationContext-jdbc.xml in the test package, and the applicationContext-jdbc.xml in the WEB-INF directory define all the required definitions to work with jdbc and compass. Note, that only the mentioned configuration has to be created in order to integrate compass to the data access layer.

The petclinic sample using the Jdbc Gps Device and defines several Jdbc mappings to the database. Some of the mappings use the more complex Result Set mappings (for mappings that require a join operation) and some use the simple Table mapping. The mapping definitions uses the common meta-data to lookup the actual meta-data values.

Note, that an important change made to the original petclinic sample was the addition the Version column. The version column is needed for automatic data mirroring (some databases, like Oracle, provides a "version column" by default).

The Resource mapping definition are automatically generated using mapping resolvers, and compass use them.

Note, that the Jdbc support currently only works with Hsql database (since the sql queries used in the Result Set mappings use hsql functions).