EbRim implementation with GeoNetwork

EbRim implementation

with GeoNetwork

Architectural Design Document

Authors:

Jeroen Ticheler – GeoCat

Erik van Ingen – GeoCat

Heikki Doeleman - GeoCat

Reviewed by:

Approved by:

Document Id:

ERGO-ADD-3300-GCT

Issue:

1.0

24/02/2009

Revision:

Document Id: ERGO-ADD-3300-GCT

Issue: 1.0 - 24/04/2009

Revision:

This document is a property of “GeoCat bv” and cannot be distributed or duplicated without written authorization.

GeoCat bv 2/35

Document change record

Issue Issue date Pages effected Reason for change

0.1 19/12/2008 All Initial draft version

0.2 16/02/2009 All Changes related to ERGO-RID-ADD-1.0

1.0 24/-04/2009 All Changes related to ERGO-RID-ADD-2.0


Issue: 1.0 - 24/04/2009

Revision:


GeoCat bv 3/35

Distribution List

Company Name Function N° of copies

Intecs S. Gianfranceschi ERGO project manager 1

ESA P.G. Marchetti ESA project manager 1


Issue: 1.0 - 24/04/2009

Revision:


GeoCat bv 4/35

Table of Content

1. INTRODUCTION 8

1.1. PURPOSE 8

1.2. SCOPE 8

1.3. GLOSSARY 8

1.3.1. ABBREVIATIONS 8

1.3.2. DEFINITION OF TERMS 9

1.4. REFERENCES 9

1.4.1. NORMATIVE REFERENCES 9

1.4.2. INFORMATIVE REFERENCES 9

1.5. DOCUMENT OVERVIEW 9

2. SYSTEM DESIGN OVERVIEW 11

2.1. SOFTWARE STATIC ARCHITECTURE 11

2.2. SOFTWARE DYNAMIC ARCHITECTURE 12

2.3. INTERFACES CONTEXT 12

2.4. MEMORY AND CPU BUDGET 13

2.5. DESIGN STANDARDS, CONVENTIONS AND PROCEDURES 13

2.5.1. SOFTWARE ARCHITECTURAL DESIGN METHOD 13

2.5.2. SOFTWARE DETAILED DESIGN METHOD 14

2.5.3. CODE DOCUMENTATION STANDARDS 14

2.5.4. NAMING CONVENTIONS 14

2.5.5. PROGRAMMING STANDARDS 14

3. SOFTWARE TOP-LEVEL ARCHITECTURAL DESIGN 16

3.1. OVERALL ARCHITECTURE 16

3.2. GEONETWORK-DOMAIN-EBRIM 18

3.2.1. INTRODUCTION 18

3.2.2. IMPLEMENTATION 19

3.2.3. XML BINDING 19

3.3. EBXML XSD AND THE EBXML SPECIFICATION 20

3.3.1. NAMESPACE FOR ATTRIBUTE "LANG" IN LOCALIZEDSTRING 20

3.3.2. NO SLOTS FOR POSTALADDRESS 21

3.3.3. REFERENCEURI INSTEAD OF OBJECTREF 21

3.4. BASIC EXTENSION PACKAGE MODEL 21


3.4.2. IMPLEMENTATION 21

3.5. EBXML PERSISTENCE 22


3.5.2. IMPLEMENTATION DETAILS 22

3.5.2.1. Inheritance 22

3.5.2.2. Custom Types 23

3.5.2.3. ID generator 23

3.6. HIBERNATE SEARCH 23


3.6.2. DIRECTORY 23

3.6.3. ANALYZER 23

3.6.4. INDEXING 24

3.6.5. LUCENE PERFORMANCE 24

3.6.6. SUPPORTED QUERY TYPES AND STORED QUERIES 24

3.7. TARGET NAMESPACES 24


3.8. EBXML SERVICE LAYER 25


3.8.2. WEB SERVICES 26

4. SOFTWARE ARCHITECTURAL DESIGN 27

4.1. SOFTWARE ITEM COMPONENTS 27

4.1.1. GEONETWORK-LEGACY 27

4.1.1.1. Type 27

4.1.1.2. Purpose 27

4.1.1.3. Function 27

4.1.1.4. Subordinates 27

4.1.1.5. Dependencies 27

4.1.1.6. Interfaces 27

4.1.1.7. Resources 27

4.1.1.8. Data 27

4.1.2. GEONETWORK-CLIENT-EBRIM 28

4.1.2.1. Type 28

4.1.2.2. Purpose 28





4.1.2.7. Resources 28

4.1.2.8. Data 28

4.1.3. GEONETWORK-WEB-EBRIM 29

4.1.3.1. Type is a J2EE web application 29

4.1.3.2. Purpose 29





4.1.3.7. Data 30

4.1.4. GEONETWORK-SERVICES-EBRIM 30

4.1.4.1. Type 30


4.1.4.3. Purpose 30




4.1.4.7. Data 31

4.1.5. GEONETWORK-DAO-EBRIM 31

4.1.5.1. Type 31

4.1.5.2. Purpose 32




4.1.5.6. Data 33

4.1.6. GEONETWORK-DOMAIN-EBRIM 33

4.1.6.1. Type 33

4.1.6.2. Purpose 33




4.1.6.6. Data 33

5. SOFTWARE REQUIREMENTS TRACEABILITY MATRIX 34

1.Introduction

1.1. Purpose

This document describes the architectural design for the ebRIM implementation for GeoNetwork.

GeoNetwork opensource is a standardized and decentralized spatial information management environment, designed to enable access to geo-referenced databases, cartographic products and related metadata from a variety of sources, enhancing the spatial information exchange and sharing between organizations and their audience, using the capacities of the internet. This approach of geographic information management aims at facilitating a wide community of spatial information users to have easy and timely access to available spatial data and to existing thematic maps that might support informed decision making.

Maps, including those derived from satellite imagery, are effective communicational tools and play an important role in the work of various types of users:

Decision Makers: e.g. Sustainable development planners and humanitarian and emergency managers in need of quick, reliable and up to date user-friendly cartographic products as a basis for action and better plan and monitor their activities.

GIS Experts in need of exchanging consistent and updated geographical data.

Spatial Analysts in need of multidisciplinary data to perform preliminary geographical analysis and reliable forecasts to better set up appropriate interventions in vulnerable areas.

The main goal of the GeoNetwork opensource software is to improve the accessibility of a wide variety of data, together with the associated information, at different scale and from multidisciplinary sources, organized and documented in a standard and consistent way.

The ebRIM registry interface provides another important catalogue interface on top of a geospatial metadata database. It will allow to expose geospatial data to a wider user community, connecting the earth observation communities with more traditional geospatial data communities like governments providing access to vector data and the like.

1.2. Scope

GeoNetwork implements a large range of geographical related functions. This document describes the ebRIM functionality and only briefly those functions relevant in the context of ebRIM.

1.3. Glossary

1.3.1. Abbreviations

Acronym Extended Form GeoNetwork GeoNetwork opensource

CSW Catalog Service for the Web

XML Extensible Markup Language

XSD XML Schema

ebRIM Enterprise Business Registry Information Model

ebXML Enterprise Business XML

DAO Data Access Object

CRUD Create Read Update and Delete

DB Database

SOA Service Oriented Architecture

JMS Java Messaging Service

Acronym Extended Form TDD Test Driven Development

JiBX Binding XML to Java Code

1.3.2. Definition of Terms

1.4. References

1.4.1. Normative References

In case of conflict between two or more applicable documents, the higher document will prevail.

[NR1] GeoNetwork opensource Software Requirement document - ERG-SRD-2100-GCT-1.1

[NR2] GeoNetwork opensource Technical Proposal - 200711-ESA01-TEC-PROP

[NR3] ERGO Requirement Baseline, ERG-RB-2100-INT Issue 1, Revision 0, 16/05/2008

[NR4] ebXML Registry Information Model Version 3.0 - http://www.oasis-

open.org/committees/download.php/13591/docs.oasis-open.orgregrepv3.0specsregrep-rim-3.0-

os.pdf

[NR5] ebXML Schema v3.0 - http://docs.oasis-open.org/regrep/v3.0/regrep-3.0-os.zip

[NR6] CSW-ebRIM Registry Service - Part 1: ebRIM profile of CSW (1.0.0)

http://portal.opengeospatial.org/files/?artifact_id=27092

[NR7] CSW-ebRIM Registry Service – Part 2: Basic extension package (1.0.0)


[NR8] OGC Cataloguing of ISO Metadata (CIM) using the ebRIM profile of CS-W (0.1.7)


1.4.2. Informative references

The following documents, although not a part of this test procedure, amplify or clarify its contents.

[IR1] Software — Part 2: Document requirements definitions (DRDs), ECSS--E--40 Part 2B, 31 March 2005.

[IR2] JiBX - http://jibx.sourceforge.net/

[IR3] JUnit - http://www.junit.org/

[IR4] XMLUnit - http://xmlunit.sourceforge.net/

[IR5] Hibernate - http://www.hibernate.org/

[IR6] Hibernate Search - http://search.hibernate.org

[IR7] Lucene - http://lucene.apache.org

[IR8] Axis2 - http://ws.apache.org/axis2/

1.5. Document Overview

Chapter 1 provides the general introduction and context of the project. It also gives the normative and informative references.

http://www.oasis-open.org/committees/download.php/13591/docs.oasis-open.orgregrepv3.0specsregrep-rim-3.0-os.pdf




http://jibx.sourceforge.net/

http://www.junit.org/

http://xmlunit.sourceforge.net/

http://www.hibernate.org/

Chapter 2 provides the system design overview, describing the software components and interface operations. It also provides design and implementation choices.

Chapter 3 describes the software artifacts, their function and their coherence. It details implementation choices at the component level.

Chapter 4 describes the software item components, detailing the purpose, functions, dependencies and interfaces with other components of the software.

2.SYSTEM DESIGN OVERVIEW

2.1. Software static architecture

GeoNetwork implements a set of catalog interfaces, one of them is the ebRIM CSW interface (see Figure 1). Every model is running on the GeoNetwork opensource platform. The ebRIM registry is running as a separate servlet that is loaded by the GeoNetwork opensource application and kept synchronized. Metadata in ISO format is transformed on import in ebRIM objects that are stored in the registry and are indexed for fast searching. An geonetwork-client-ebrim component has been added to the geonetwork-legacy code base and is triggered by the GeoNetwork opensource

harvesting timer every three minutes. The client will ensure that every change in the GeoNetwork metadata catalog is reflected in the ebRIM registry.

The newly developed ebRIM web application will form the basis for future GeoNetwork opensource development.

The high-level static architecture diagram shows the dependencies with the most important libraries/frameworks used in the application (see Figure 2).

Figure 1 - Available catalog interfaces

Figure 2 - High-level architecture diagram

Figure 3 shows the architectural layers, which are also expressed by design in artifacts. From the Internet an HTTP request will be picked up by the web service layer. This layer is responsible for handling the HTTP and SOAP protocols. Then a request will be passed to the (logical) service layer. The service layer uses the persistence layer to interact with the database. Because of the domain driven design approach, the domain layer is isolated from every other layer. But in the mean while, the domain layer is also the centre for every layer.

2.2. Software dynamic architecture

Not Applicable

2.3. Interfaces context

The interfaces implemented by the tool are the CSW operations described in OGC 07-110r2 CSW-ebRIM Registry Service - Part 1: ebRIM profile of CSW. These are:

GetCapabilities

The mandatory GetCapabilities request allows a client to retrieve information about the service. The body of the response message contains a service description that advertises the basic operational and non-operational characteristics of the service; the description is structured into subsections that may be retrieved individually by name.

DescribeRecord

The mandatory DescribeRecord request is specified in clause 10.6 of OGC 07-006r1. This request allows a client to discover the information model(s) supported by the catalogue and to retrieve record type definitions.

GetRecords

The mandatory GetRecords request is described in clause 10.8 of OGC 07-006r1. This is the principal request used to search and retrieve catalogue content. Some, all, or none of the registry objects in the result set may be included in the response message. Asynchronous or distributed query processing is beyond the scope of this profile.

GetRecordById

Figure 3 – Layers in the ebRIM registry architecture

The mandatory GetRecordById request is specified in clause 10.9 of OGC 07-006r1. This request provides a simple means of retrieving one or more registry objects by identifier. The supplied identifier values are checked for matches against either the id attribute of a registry object (rim:RegistryObject/@id) or an external identifier (rim:ExternalIdentifier/@value) assigned to a registry object.

GetRepositoryItem

The mandatory GetRepositoryItem request is used to retrieve the repository item corresponding to some extrinsic object. If available, the item is included in the body of the response; it shall be an instance of the media type indicated by the value of the Content-Type entity header field.

External interfaces relevant in the context of this document are the CSW-ebRIM interface and the User Interface (see Figure 4).

2.4. Memory and CPU budget

GeoNetwork opensource can run either on MS Windows, Linux or Mac OS X.

Some general system requirements for the software to run without problems are listed here:

Processor: 2 GHz or higher

Memory (RAM): 1GB or higher

2.5. Design standards, conventions and procedures

This section summarizes the software methods adopted for the architectural and the detailed design.

2.5.1. Software architectural design method

UML as the modeling language: UML is unambiguous and therefore very effective for communication within the team and outside of the team. Version 2.0 of UML is used in this project. Domain Driven Design: This means that a domain model is designed and implemented. Domain Driven Design enforces having an explicit domain model. This domain model is only representing the functional domain of the application. A great advantage is that the domain knowledge of the application is isolated in this way and not mixed up with

Figure 4 - Exposed interfaces related to the ebRIM registry

implementation technologies. In the geonetwork-ebrim application there is an artifact called geonetwork-domain-ebrim (referred to as 'the domain'). The domain does not have dependencies with other components within the application. See also the Artifact dependency diagram (see Figure 6). The domain represents the semantics of the application. The OGC specs and its corresponding XSD’s have been the basis for the domain. All other artifacts of the application do depend on the domain. The major effect within the application is that domain objects can be used everywhere in the application. Rather than processing xml within the application, domain objects are used. Xml processing is only done on the outer level of the application, in the web layer. Therefore there are two levels of interfaces within the application. First interface is the CSW interface, defined in the web layer (artifact geonetwork-ebrim-web). Second level interface is the so-called 'logical service' interface (artifact geonetwork-ebrim-services). It has a logical interface, based on domain objects and the CSW operation names. Dependency injection: Dependency Injection (DI) is the process of supplying an external dependency to a software component. It is a specific form of inversion of control where the concern being inverted is the process of obtaining the needed dependency. It is used in the project to inject all kind of functionalities that are part of a framework. Functionalities injected are for instance transaction management. The great advantage is that the application only consists of its core functions, more generic functions are injected.

2.5.2. Software detailed design method

Test Driven Development (TDD): TDD means first writing the test before writing the application. It encourages developers to write pieces of software with a clear input and output. It enforces the developer to think before writing the logic. For the short term it delivers higher quality software. For the long term it delivers better maintainable software.

2.5.3. Code documentation standards

There are great standards available on http://java.sun.com/docs/codeconv/CodeConventions.pdf that are considered as de facto standards for Java development. These standards will be applied to development. Another practical convention that will be used is to use as much as possible java 1.5 generics in order to be more type safe. List<Resource> myList instead of just List myList.

2.5.4. Naming conventions

Naming convention is used for artifacts: [software name] - [architecture level name] - [function name]. This convention is applied and results in these artifacts: - geonetwork-domain-ebrim - geonetwork-persistence-ebrim - geonetwork-service-ebrim - geonetwork-web-ebrim Doing this has the great advantage that scaling is easy. Scaling requires first of all a layered architecture on the technical level. The different functions are added within a certain technical architectural level.

2.5.5. Programming standards

Every piece of software has a unit test associated. The unit tests for the persistence layer create the database through Hibernate and then insert data into it, again using Hibernate. The resulting state of the database is verified by executing HQL queries. Where applicable, polymorphic HQL queries are tested as well. The tests use the well-known unit-testing framework JUnit. The tests are modeled such

http://java.sun.com/docs/codeconv/CodeConventions.pdf

that they use an embedded database server; this removes the dependency of the test suite on a pre-installed external database server. Continuous integration with Hudson is implemented. This means that after a change to the code repository, it will be checked and built by Hudson. Maven is implemented for configuration management. Configuration management means that Maven manages all dependencies to other libraries.

3.SOFTWARE TOP-LEVEL ARCHITECTURAL DESIGN

This chapter should describe the software Top-Level Architectural Design and it shall be provided by the PDR. The top-level structure of the software item design shall be described, identifying the software components, their hierarchical relationships any dependency and interfaces between them. The following structure is recommended.

3.1. Overall Architecture

This section describes the software architectural design, from a static point of view and also, when the software to be developed has real time constraints, from a dynamic point of view.

Service DAO Pattern

The application is split in three layers, service, DAO and domain object layer (see Figure 5). Dao stands for Data Access Object. Every service can use one or more DAO. Every DAO provides access to one or more domain objects. The layering has been chosen for these reasons:

Having layers gives the possibility to test on layer level. Since TDD is used, this is considered as an important.

Having layers is a little bit more code. However it implements in a concrete way the design principal separation of concerns.

Artifact dependency diagram

Figure 5 - Layers in the application

Figure 6 - Artifact dependency diagram

artifact name responsibility

geonetwork-domain-ebrim Represents the domain model of the ebRIM function.

geonetwork-persistence-ebrim

Provides the persistence layer for the ebRIM function. The persistence layer consists of a set of DAO's. A DAO can be used to do CRUD operations on domain objects towards the DB.

geonetwork-services-ebrim

Provides the service layer for the function. On this level everything is an official transaction. Every service call will probably use one or more DAO's This layer can also be exposed to any other technical protocol like web services, JMS, SMTP and so on. Fits well in a Service Oriented Architecture. Currently this layer will be exposed as web services in the layer below, geonetwork-web-ebrim.

geonetwork-web-ebrim

Provides the application layer of the application. The application layer interacts with the users of the web application. A user can be a browser or a machine. It parses the http request into a service call. The service call goes to the service layer.

geonetwork-client-ebrim The client that stores ISO documents in the ebRIM web application via a web service. The component has been added to the geonetwork-legacy software.

geonetwork-axis2-gen-ebrim This is used to generate a skeleton for the CSW web services. It is only of importance during development time, not runtime.

geonetwork-axis2-home

This artifact is used by geonetwork-axis2-gen-ebrim. It contains the Axis2 framework. It is only of importance during development time, not runtime.

geonetwork_legacy

The legacy system that uses geonetwork-client-ebrim in order to store ISO documents in the ebRIM web application. The component triggers the geonetwork-client-ebrim component to update the registry every three minutes.

Functional Application Architecture

The ebRIM updater (synchronizer) updates the ebRIM registry with ISO19139 data. The metadata flows from the GN persistence (ISO19139 format) through the updater into the ebRIM persistence component, never the other way around. The ebRIM Updater does this every time ISO19139 metadata is added or updated in the GN persistent layer.

Other behavior:

An ebRIM CSW client only searches and reads from GeoNetwork opensource

An ISO 19139 CSW client can read and write (harvest)

The ebRIM Updater does a one time conversion of all the ISO 19139 metadata into the ebRIM registry

The ebRIM Updater updates the ebRIM Persistence whenever GeoNetwork Persistence gets updated

All information at course grained level can be found either via CSW ebRIM ISO or CSW ISO interfaces

All information at fine grained level can be found via the CSW ISO interface

Not all information at fine-grained level can be found via CSW ebRIM ISO interface. This because the ebRIM model does not cover all the details/semantics of the ISO19115 model

3.2. geonetwork-domain-ebRIM

3.2.1. Introduction

The ebXML Object Model is specified in "ebXML Registry Information Model Version 3.0" (see Normative Reference section). It defines the types of metadata and content that can be stored in an ebXML Registry. The specification is the basis for an XML Schema for this model (see Normative Reference section).

GeoNetwork has implemented the Information Model in Java. The implementation is capable of marshalling, unmarshalling and validating XML documents that conform to the XSD mentioned above. The implementation will be loosely coupled to the persistence layer (ebXML Persistence) for storage and retrieval.

Figure 7 - Functional application architecture

3.2.2. Implementation

The implementation of the Information Model is referred to as ebXML Object Model. It consists of a set of Java Beans representing the objects in the specification mentioned above. Where there are discrepancies between the specification and the XSD mentioned above, preference was given to the definition in the XSD. See section 3.3. , the ebXML XSD and the ebXML specification discrepancies for a list of these.

The implementation is structured in the following packages, largely corresponding to the specification:

org.geonetwork.ebxml.informationmodel.association

org.geonetwork.ebxml.informationmodel.classification

org.geonetwork.ebxml.informationmodel.cooperatingregistries

org.geonetwork.ebxml.informationmodel.core

org.geonetwork.ebxml.informationmodel.core.datatype

org.geonetwork.ebxml.informationmodel.event

org.geonetwork.ebxml.informationmodel.provenance

org.geonetwork.ebxml.informationmodel.service

org.geonetwork.ebxml.informationmodel.xsd

All of these packages correspond to a section in the specification except the org.geonetwork.ebxml.informationmodel.xsd package, which contains Java Beans to assist in representing XSD data types that have no equivalent in the Java language, such as xsd:duration.

Note: The Access Control section of the Information Model specification is not (yet) part of the implementation.

The implementation is complemented with a suite of unit tests, for each of the objects that may be used as a top-level element in an ebXML document. The unit tests are written in the well-known JUnit framework. For each of these objects there is a test case for marshalling and a test case for unmarshalling. Since we are dealing with XML, the tests use the complimentary test library XML Unit. This allows among others to ignore differences in whitespace and the ordering of elements and attributes in the XML where that should be ignored. An automatic run of the test suite has been incorporated into the Ant build script and will be made part of the Continuous Integration build process.

3.2.3. XML binding

In order to efficiently establish an XML binding, that is to say the ability to marshal and unmarshal XML documents, the Java Beans implementation is decorated with a JiBX binding. JiBX was chosen over other binding frameworks such as XMLBeans, Castor and JAXB because of its high performance, ease of use, and non-intrusive programming model.

The core of the binding is an XML definition that relates XML elements to Java Beans (and vice versa). A simple snippet from the binding is the following, which relates a LocalizedString from the ebXML XSD and its Java Bean representation:

A sample of code that marshals a RegistryObject to an ebXML RIM document is the following. This and similar code you can find in the Object Model's unit test suite.

A perhaps remarkable feature of JiBX is that it requires a post-compilation step where the JiBX binding compiler generates the binding code. Although it can be skipped and the binding done at runtime, doing this improves performance and also helps signaling possible errors in the binding definition. This has been made part of the automated build process.

For the developers, there is an Eclipse plug-in (http://jibx.sourceforge.net/eclipse/index.html) available that will automatically run the binding compiler every time you build.

3.3. ebXML XSD and the ebXML specification

This section describes discrepancies between the ebXML schema and the ebXML specification. Also other details of interest regarding the schema are listed here.

3.3.1. Namespace for attribute "lang" in LocalizedString

The whole schema has targetNamespace "urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0", except for one attribute of the LocalizedString type. The attribute "lang" is in the XML namespace, "http://www.w3.org/XML/1998/namespace".

This different namespace for "lang" is reflected in the JiBX binding.

RegistryObject registryObject = new RegistryObject();

//

// set data to this registryObject

//

IBindingFactory bfact = BindingDirectory.getFactory(RegistryObject.class);

IMarshallingContext marshallingContext = bfact.createMarshallingContext();

Writer out = new BufferedWriter(new OutputStreamWriter(new

ByteArrayOutputStream()));

marshallingContext.setOutput(out);

// pretty-print the XML output

marshallingContext.setIndent(3);

marshallingContext.marshalDocument(registryObject, "UTF-8", null);

<mapping name="LocalizedString"

class="org.geonetwork.ebxml.informationmodel.core.datatype.LocalizedString"

>

<value style="attribute" name="lang" field="lang" usage="optional"/>

<value style="attribute" name="value" field="value"

usage="optional"/>

<value style="attribute" name="charset" field="charset"

usage="optional"/>

</mapping>

3.3.2. No Slots for PostalAddress

The type PostalAddress has an attribute Slots according to the specification, but this is left out in the XSD. Likewise it's not there in the Java implementation.

3.3.3. referenceURI instead of ObjectRef

In almost all cases where the specification says of a property that it is of type ObjectRef, the XSD has modeled them as type referenceURI. So has the Java implementation.

3.4. Basic Extension Package Model

This section describes the GeoNetwork opensource implementation of CSW-ebRIM Registry Service specification's Basic Extension Package (OGC 07-144 r2).

3.4.1. Introduction

The ebXML Object Model is specified in "CSW-ebRIM Registry Service – Part 2: Basic extension package v1.0.0". The Basic package concentrates on the provision of service-related information in support of geospatial applications. It adopts concepts from a variety of sources, including the ISO 19100 series of geomatics standards. The specification is the basis for an XML Schema for this model.

GeoNetwork has implemented the Basic Extension Package in Java. The implementation is capable of marshalling, unmarshalling and validating XML documents that conform to the XSD mentioned above. The implementation will be loosely coupled to the Persistence Layer for storage and retrieval.

3.4.2. Implementation

The implementation of the Basic Extension Package is referred to as Basic Extension Package Model. It consists of a set of Java Beans representing the objects in the specification mentioned above.

The implementation is structured in the following packages, largely corresponding to the specification:

org.geonetwork.domain.ebxml.extensionpackage.basicextension.association

org.geonetwork.domain.ebxml.extensionpackage.basicextension.datatype

org.geonetwork.domain.ebxml.extensionpackage.basicextension.extrinsicobject

org.geonetwork.domain.ebxml.extensionpackage.basicextension.slottype

org.geonetwork.domain.ebxml.extensionpackage.basicextension.storedquery

org.geonetwork.domain.ebxml.extensionpackage.basicextension.xsd

All of these packages correspond to a section in the specification except the org.geonetwork.ebxml.informationmodel.xsd package, which contains Java Beans to assist in representing XSD data types that have no equivalent in the Java language, such as xsd:duration.

The implementation is complemented with a suite of unit tests, for each of the objects that may be used as a top-level element in an ebXML document. The unit tests are written in the well-known JUnit framework. For each of these objects there is a test case for marshalling and a test case for unmarshalling. As we're dealing with XML the tests use the complimentary test library XML Unit. This allows among others to ignore differences in

whitespace and the ordering of elements and attributes in the XML where that should be ignored. An automatic run of the test suite has been incorporated into the Maven build script and has been made part of the Continuous Integration build process.

3.5. ebXML Persistence

3.5.1. Introduction

The ebXML Object Model has the capability of being persisted to permanent storage (a database). In order to achieve a vendor-independent code base and to maintain the Object Oriented paradigm in the face of the Relational paradigm employed by databases, we use Hibernate as an Object/Relational Mapping tool. Hibernate was chosen over other solutions such as EJB 3.0 (http://java.sun.com/products/ejb/) as that would require a J2EE container for runtime platform.

The persistence layer comes equipped with a unit test suite. The unit tests for the persistence layer create the database through Hibernate and then insert data into it, again using Hibernate. The resulting state of the database is verified by executing HQL queries. Where applicable, polymorphic HQL queries are tested as well.

The tests use the well-known unit testing framework JUnit. Although developed against a local MySQL database, the tests are currently being remodeled such that they use an embedded McKoi database server; this removes the dependency of the test suite on a pre-installed external database server. Some peculiarities of McKoi are being accommodated, for instance it chokes if you try to create a table called "user". This last point is addressed by invoking an ImprovedNamingStrategy on the Hibernate configuration that causes all table names to be automatically prefixed by "RIM_".

3.5.2. Implementation details

Here is a list of design decisions regarding the Hibernate mapping.

3.5.2.1. Inheritance

The OO notion of inheritance may be expressed in Hibernate using 4 different strategies, see "Java Persistence with Hibernate" by Christian Bauer and Gavin King. They are

Table per concrete class with implicit polymorphism

Table per concrete class with unions

Table per class hierarchy

Table per subclass

The first strategy creates a different table for each subclass, and those tables all contain (repeat) the properties from the common base class. The Hibernate mapping is unaware of the inheritance relation. The base class definition is thus denormalized. It is impossible to define polymorphic associations and problematic to define polymorphic queries.

The second strategy also employs different tables for each subclass (thus base class columns are denormalized), but now the Hibernate mapping is made aware of the inheritance relation. This allows for polymorphic associations and avoids repeating the base class mapping multiple times in the Hibernate mapping.

The third strategy uses a single table for the base class and all subclasses. The table's columns are a union of all columns of the base and subclasses. This will require that all

subclass properties are nullable. In case of larger inheritance structures, this strategy would lead to everything being chucked together in one table.

The fourth strategy is to represent inheritance relationships as relational foreign key associations. Every class/subclass that declares persistent properties—including abstract classes and even interfaces—has its own table. The primary advantage of this strategy is that the SQL schema is normalized. A polymorphic association to a particular subclass may be represented as a foreign key referencing the table of that particular subclass. This seems a preferred strategy but its performance may be detrimental for large class hierarchies, as queries require a join across many tables.

At this point the second strategy, "Table per concrete class with unions", has been chosen to map the OO inheritance relations in the ebXML Object Model to the relational database realm.

3.5.2.2. Custom Types

The following classes are represented as Custom Types in the Hibernate mapping:

Duration

This class represents the XML xsd:duration type in Java. The source for this class was taken from the Axis project. This class is mapped using a custom Hibernate type that will map an instance to a SQL STRING type using its toString() and Duration(String) methods. So in the database the duration will be stored in the PnYnMnDTnHnMnS format.

3.5.2.3. ID generator

The Identifiable class is the superclass for a lot of classes. It had as a generator this definition: <generator class="native"/> Probably this has been taken from the book or reference documentation. The Hibernate forum tells that is should be <generator class="sequence"/> for the chosen inheritance strategy (Table per concrete class with unions).

3.6. Hibernate Search

3.6.1. Introduction

Hibernate Search is a library that combines the strengths of full text search using Lucene with Hibernate's O/R mapping capabilities. Queries in Hibernate Search are expressed as wrappers around Lucene queries. Hibernate Search seems to offer 2 principal advantages over directly using Lucene plus a database: (1) Lucene information (about the index, analyzers to be used, etc.) is expressed using annotations on the domain objects involved; and (2) synchronization (re-indexing) is automatically triggered when Hibernate makes a change to the database.

3.6.2. Directory

A Lucene index is represented by a Directory. We will use a file system directory provider to persistently store the Lucene index; and we will use an in-memory directory provider to use with unit test.

3.6.3. Analyzer

Lucene offers a lot of functions in order to search more precise. It can be done by defining tokenizers and filters.

Those filters and tokenizers have been chosen who makes the most sense. Using all filters makes no sense because there are too much and would be bad for the performance. Every installation of the ebRIM application can be easily configured with its own set of tokenizers and filters.

These are the tokenizers and filters used:

StandardTokenizer

The StandardTokenizer should support most needs for English (and most European languages) texts. It splits words at punctuation characters and removing punctuation signs with a couple of exception rules

StandardFilter

The StandardFilter removes apostrophes and remove dots in acronyms.

LowerCaseFilter

The LowerCaseFilter changes all characters to lower case.

ISOLatin1AccentFilterFactory

Abstract over accented characters.

3.6.4. Indexing

It seems straightforward to use an asynchronous thread in Hibernate Search to do the indexing.

We use transparent indexing except in the case of application start-up, where we must define a strategy. The current way in GeoNetwork is to check if a Lucene index is present and if not, build it.

3.6.5. Lucene performance

Lucene is known to be superfast. Even so we can and should do a performance analysis, using Search Quality Benchmarking (see http://lucene.apache.org/java/2_4_0/api/contrib-benchmark/org/apache/lucene/benchmark/quality/package-summary.html).

3.6.6. Supported Query types and stored queries

The supported type of queries for GetRecords request are expressions conforming OGC Filter specification, using mandatory Title, AnyText and Identifier queryables defined in 07-038 OGC Cataloguing of ISO metadata (Annex E).

Stored queries supported are mandatory stored queries defined in OGC 07-0114r2 CSW-ebRIM Registry Service - Part 2: Basic extension package (chapter 10):

• listExtensionPackages

• showStoredQueries

• findServices

• findObjectsByClassificationNode

• findObjectsByClassificationPath

3.7. Target Namespaces

This section describes the target namespaces of the XML Schemas pertaining to the XML documents this project is about.

3.7.1. Introduction

The target namespace of an XML Schema is the namespace of documents that are described by that schema. Documents described by the schemas used in the CSW-ebRIM Registry Service specification (OGC 07-110r2 and OGC 07-144r2) are in the WRS namespace; although there is a slight difference is the actual namespace between the schema for the ebRIM profile of CSW (target namespace: http://www.opengis.net/cat/wrs/1.0) and the schema for the Basic extension package (target namespace: http://www.opengis.net/cat/wrs).

The XML Schema for the ebRIM profile of CSW is included in OGC 07-110r2.

The XML Schema for the Basic Extension package is reprinted in Annex I.

Both these schemas use other schemas with different target namespaces, and those other schemas in turn often use yet other schemas with yet other target namespaces. A visualization of which target namespace uses which other target namespace is shown in Figure 8.

3.8. ebXML Service Layer

3.8.1. Introduction

The Service Layer exposes various services to the outside world. This section describes these services along with how they are implemented.

Figure 8 - Relation between namespaces



3.8.2. Web Services

Figure 9 shows the position of Axis2 in the GeoNetwork architecture. A client will use both gn-legacy and gn-ebrim via web services. The ebRIM registry uses Axis2 as the framework for web services. By using Axis2, web services over SOAP and HTTP are supported. As a binding framework JiBX is used. Axis2 is configured to use JiBX, while also application logic is using JiBX. JiBX is proven to be fast and is also very flexible. JiBX can be configured to map any XML document to any Java object graph.

The Axis2 framework's configuration is based on WSDL documents available from

http://schemas.opengis.net/csw/2.0.2/profiles/ebrim/1.0/wsdl/1.1/

These WSDL do use Document/Literal and therefore used in the Axis2 configuration of gn-ebrim. The Axis2 code generation is used to provide the stubs and skeletons for the server side and the test client side.

Figure 9 - The position of the web services framework Axis2 in the GeoNetwork architecture

4.Software architectural design

4.1. Software Item components

4.1.1. geonetwork-legacy

4.1.1.1. Type

Type is a java web application. The component is the GeoNetwork opensource software, and is referred to as geonetwork-legacy in the context of this project. The implementation technology is Java.

4.1.1.2. Purpose

The purpose of the component is storing, maintaining and retrieving ISO19139 metadata documents as well as other geospatial metadata documents. In the context of the ebRIM project, only the first are of concern.

4.1.1.3. Function

It manages the geospatial metadata database and provides a graphical user interface on the web as well as a range of administrative functions.

4.1.1.4. Subordinates

The component has no subordinates

4.1.1.5. Dependencies

The GeoNetwork opensource application needs to be deployed and started on a J2EE servlet engine like Jetty or Tomcat. The database needs to contain ISO19139:2007 compliant metadata records.

4.1.1.6. Interfaces

This component has a range of interfaces. In the context of this project these are not relevant however.

The component activates the geonetwork-client-ebrim component that inserts and updates metadata documents into the ebRIM registry. The schedule of activation is every three minutes.

4.1.1.7. Resources

The component needs a JRE and a servlet engine (Tomcat or Jetty) in order to run.

4.1.1.8. Data

The data stored and processed is an ISO 191139 document, represented as an XML object. An object represents only one ISO 191139 document. The document structure is defined by the ISO19139:2007 standard and can be found here:

http://schemas.opengis.net/iso/19139/

4.1.2. geonetwork-client-ebrim

4.1.2.1. Type

Type is a java archive. This component is named geonetwork-client-ebrim and is a file named geonetwork-client-ebrim.jar. Its namespace is org.geonetwork.client.ebrim.csw202. The implementation technology is Java.

The content type of the component is JAR. Inside the jar, only the content types java class files are used.

4.1.2.2. Purpose

It integrates geonetwork-legacy with the geonetwork-web-ebrim application. The component is available within the geonetwork-legacy application.

4.1.2.3. Function

It synchronizes the metadata content of the geonetwork-legacy registry with the geonetwork-web-ebrim.


The geonetwork-client-ebrim has one subordinate and that is the geonetwork-legacy application. It will communicate via the HTTP protocol.


The geonetwork-web-ebrim needs to be deployed and started on a J2EE servlet engine like Jetty or Tomcat.

Before this operation is called, an ISO 19139 document needs to be stored in the geonetwork-legacy database.

4.1.2.6. Interfaces

This component has a simple interface:

webInsert(InputStream isoDocumentInputStream) throws GeoNetworkClientException.

The component has only one operation, webInsert. The webInsert operation needs one parameter, an inputStream, representing the ISO191139 document.

Interruption of the invocation results in a GeoNetworkClientException. Possible causes are a HttpException or IOException.

4.1.2.7. Resources

The component needs a JRE in order to run.

4.1.2.8. Data

The data internal to a component is in this case the same as the external one. This is an ISO 191139 document, represented as an InputStream. The inputStream represents only one ISO 191139 document. The document structure is defined by the ISO19139:2007 standard and can be found here:


4.1.3. geonetwork-web-ebrim

4.1.3.1. Type is a J2EE web application

4.1.2.1.Type

Type is a java web archive. This component is named geonetwork-web-ebrim and is a file named geonetwork-web-ebrim.war. Its namespace is org.geonetwork.web.ebrim. Implementation technology is Java. The component is a J2EE compliant web application.

The content type of the component is WAR. Inside the war different content types are used like Java classes, property files, XML and XSD files.

4.1.3.2. Purpose

The purpose of the component is to provide services on HTTP level for ebRIM related services.

4.1.3.3. Function

The function of the component is to provide an ebRIM registry interface to the GeoNetwork ISO repository.

Process descriptions may use such techniques as Structured English, Precondition-Postcondition specifications and State-Transition Diagrams


The subordinate of this component is the component geonetwork-services-ebrim. The component geonetwork-services-ebrim should be available on the java classpath of the application.


The component needs to be deployed on a J2EE compliant servlet container. The component has connected itself to its database before it is called. The web service framework Axis2 should start before this component is started. The Inversions of Control Container (Spring) needs to start before this component is used. Before this component is called, Axis should have done all the xml marshalling.

4.1.3.6. Interfaces

This component contains two interfaces:

(1)ISO19139InsertionWebService has this interface:

doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException

This interface receives calls from the geonetwork-client-ebrim component. It routes the calls to the interface ISO19139InsertionService part of the component geonetwork-services-ebrim

(2) CSWEBRIMSOAPServiceSkeleton has this interface:

Capabilities getCapabilities(GetCapabilities request) throws MsgInvalidRequestFault;

GetRecordsResponse getRecords(GetRecords request) throws MsgInvalidRequestFault;

GetRecordByIdResponse getRecordById(GetRecordById request) throws MsgInvalidRequestFault;

GetDomainResponse getDomain(GetDomain request) throws MsgInvalidRequestFault;

DescribeRecordResponse describeRecord(DescribeRecord request) throws MsgInvalidRequestFault;

HarvestResponse harvest(Harvest request) throws MsgInvalidRequestFault;

TransactionResponse transaction(Transaction request) throws MsgInvalidRequestFault;

GetRepositoryItemResponse getRepositoryItem(String id, String request, String service) throws MsgInvalidRequestFault;

This interface receives calls from any HTTP of SOAP client. It routes the calls to the interface CSW202Service, part of the component geonetwork-services-ebrim. This component is in practice a very thin layer. It receives calls from the Axis2 framework, does proper exception interpretation and routes the call to the geonetwork-services-ebrim component.

4.1.3.7. Data

The data of the ISO19139InsertionWebService is described in the XSD’s to be found here:


The data of the ISO19139InsertionWebService is described in the XSD's to be found here:

http://schemas.opengis.net/csw/2.0.2/profiles/ebrim/1.0/

The exception type MsgInvalidRequestFault extends CSW202ServiceException. It is a 'technical' equivalent of the CSW202ServiceException, which is described in the XSD as mentioned above.

4.1.4. geonetwork-services-ebrim

4.1.4.1. Type

Type is a java archive. This component is named geonetwork-services-ebrim and is a file named geonetwork-services-ebrim.jar. Its namespace is org.geonetwork.services.ebrim. The implementation technology is Java.

The content type of the component is JAR. Inside the jar there are 2 content types are used. Java classes and xml files.

4.1.4.2. Function

The function is this component is to implement the specs as defined by CSW ebRIM spec documents.

4.1.4.3. Purpose

The purpose of the component is to be the logical service layer within the architecture.


The subordinate of this component is the component geonetwork-dao-ebrim. The component geonetwork-dao-ebrim should be available on the java classpath of the application.

Another subordinate of this component is the component geonetwork-domain-ebrim. The component geonetwork-dao-ebrim should be available on the java classpath of the application.


The component needs its parent geonetwork-services-ebrim as part of the running web application geonetwork-web-ebrim.

Before this component is called, geonetwork-services-ebrim should have done all the technical interpretations in order to make any call a ' logical' call. A logical call is a call that is only java-to-java and stripped from any binding or protocol issues like HTTP and/or xml marshalling or technical exception handling.

4.1.4.6. Interfaces

First interface (CSW202Service) comprises these operations:

Capabilities getCapabilities(GetCapabilities request) throws CSW202ServiceException;

GetRecordsResponse getRecords(GetRecords request) throws CSW202ServiceException;

GetRecordByIdResponse getRecordById(GetRecordById request) throws CSW202ServiceException;

GetDomainResponse getDomain(GetDomain request) throws CSW202ServiceException;

DescribeRecordResponse describeRecord(DescribeRecord request) throws CSW202ServiceException;

HarvestResponse harvest(Harvest request) throws CSW202ServiceException;

TransactionResponse transaction(Transaction request) throws CSW202ServiceException;

GetRepositoryItemResponse getRepositoryItem(String id, String request, String service) throws CSW202ServiceException;

This interface receives calls from the interface CSWEBRIMSOAPServiceSkeleton from the component geonetwork-web-ebrim.

Second interface (ISO19139InsertionService) comprises these operations:

void insert(InputStream iso19139) throws GeonetworkServiceException

This interface receives calls from the interface ISO19139InsertionWebService from the component geonetwork-web-ebrim.

4.1.4.7. Data





4.1.5. geonetwork-dao-ebrim

4.1.5.1. Type

Type is a java archive. This component is named geonetwork-dao-ebrim and is a file named geonetwork-dao-ebrim.jar. Its namespace is org.geonetwork.dao.ebrim. The implementation technology is Java.

4.1.5.2. Purpose

The purpose is to be a data access layer in order to abstract from the data layer.

4.1.5.3. Function

Its function is to do CRUD operations towards the data stores.


The subordinate of this component is the component geonetwork-domain-ebrim. The component geonetwork-domain-ebrim should be available on the java classpath of the application.

4.1.5.5. Interfaces

The interface (CoreDao) comprises these operations:

void saveExternalIdentifier(ExternalIdentifier externalIdentifier);

void mergeExternalIdentifier(ExternalIdentifier externalIdentifier);

void deleteExternalIdentifier(ExternalIdentifier externalIdentifier);

List<ExternalIdentifier> loadAllExternalIdentifier();

ExternalIdentifier findExternalIdentifierById(long id);

/** * ExternalLink */

void saveExternalLink(ExternalLink externalLink);

void mergeExternalLink(ExternalLink externalLink);

void deleteExternalLink(ExternalLink externalLink);

List<ExternalLink> loadAllExternalLink();

ExternalLink findExternalLinkById(long id);

/** * ExtrinsicObject */

void saveExtrinsicObject(ExtrinsicObject extrinsicObject);

void mergeExtrinsicObject(ExtrinsicObject extrinsicObject);

void deleteExtrinsicObject(ExtrinsicObject extrinsicObject);

List<ExtrinsicObject> loadAllExtrinsicObject();

ExtrinsicObject findExtrinsicObjectById(long id);

/** * ObjectRef */

void saveObjectRef(ObjectRef objectRef);

void mergeObjectRef(ObjectRef objectRef);

void deleteObjectRef(ObjectRef objectRef);

List<ObjectRef> loadAllObjectRef();

ObjectRef findObjectRefById(long id);

/** * RegistryObject */

void saveRegistryObject(RegistryObject registryObject);

void mergeRegistryObject(RegistryObject registryObject);

void deleteRegistryObject(RegistryObject registryObject);

List<RegistryObject> loadAllRegistryObject();

RegistryObject findRegistryObjectById(long id);

This interface receives calls from the component geonetwork-services-ebrim.

4.1.5.6. Data

The data of the component is described in the XSD’s to be found here:


4.1.6. geonetwork-domain-ebrim

4.1.6.1. Type

Type is a java archive. This component is named geonetwork-domain-ebrim and is a file named geonetwork-domain-ebrim.jar. Its namespace is org.geonetwork.domain.ebrim. The implementation technology is Java.

4.1.6.2. Purpose

The purpose is to be the isolated independent representation of the information model of the application.

4.1.6.3. Function

To have a java representation of all the possible types with their relations.


There are no subordinates for this component.

4.1.6.5. Interfaces

The domain is its own interface.

4.1.6.6. Data

The data of the component is described in the XSD’s to be found here:


5.Software Requirements Traceability Matrix

The SDD shall provide traceability matrices

1. from the software requirements to component down to the lower identified component in the software hierarchy (forward traceability) and

2. from the software components to its upper level component up to the software requirements (backward traceability).

b. In case the information in a. is provided as separate documentation in the DJF, a reference to it shall be stated.

Annex I <?xml version="1.0" encoding="UTF-8"?>



<xsd:schema xmlns:wrs="http://www.opengis.net/cat/wrs"

xmlns:rim="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:dc="http://purl.org/dc/elements/1.1/"

xmlns:gml="http://www.opengis.net/gml"

targetNamespace="http://www.opengis.net/cat/wrs" elementFormDefault="qualified"

version="1.0.0" id="pkg-basic.xsd">

<xsd:annotation>

<xsd:appinfo>

<dc:identifier>

http://schemas.opengis.net/csw-ebrim/1.0.0/pkg-basic.xsd

</dc:identifier>

</xsd:appinfo>

<xsd:documentation xml:lang="en">

The Basic package defines extensions that must be supported by all

conforming implementations.

</xsd:documentation>

</xsd:annotation>

<xsd:import namespace="urn:oasis:names:tc:ebxml-regrep:xsd:rim:3.0"

schemaLocation="http://www.oasis-

open.org/committees/regrep/documents/3.0/schema/rim.xsd"/>



<xsd:import namespace="http://www.opengis.net/gml"

schemaLocation="http://schemas.opengis.net/gml/3.1.1/base/gml.xsd"/>

<xsd:element name="ValueList" type="wrs:ValueListType"

substitutionGroup="rim:ValueList"/>

<xsd:complexType name="ValueListType">

<xsd:annotation>


More permissive slot values not restricted to simple types.


</xsd:annotation>

<xsd:complexContent>

<xsd:extension base="rim:ValueListType">

<xsd:sequence minOccurs="0" maxOccurs="unbounded">

<xsd:element ref="wrs:AnyValue"/>

</xsd:sequence>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

<xsd:element name="AnyValue" type="wrs:AnyValueType"/>

<xsd:complexType name="AnyValueType" mixed="true">

<xsd:sequence>

<xsd:any minOccurs="0"/>

</xsd:sequence>

</xsd:complexType>

<xsd:element name="StoredQuery" type="rim:IdentifiableType"

id="StoredQuery">

<xsd:annotation>


Specifies a stored query to execute. Slots may be used to pass in any

required parameters.


</xsd:annotation>

</xsd:element>

</xsd:schema>