Database Driven Generation of SVG-Maps with the Apache Cocoon 2 Framework

Keywords: Apache Cocoon, Cartography, Database

Peter Schaer
University of Berne, Department of Geography


Peter is 28 years old and pursues his studies in geography at the University of Berne (Switzerland) since 1995. The presented paper is a draft from his diploma thesis at the same university. He's hoping to finish his studies by end of june 2003.


The department of geography at the university of Berne (Switzerland) initiated in the year 2000 a project to create a thematic atlas about the urban region of the swiss capital. It will visualize the economic, political and social structure of the bern region (consisting of 89 communities). This atlas will probably be published as a book, as a cd-rom and in the internet. My task in this project is it to find an appropriate method for generating the maps for the atlas.

SVG seemed to be the ideal format for this job. Previous work (e.g. those presented at SVGOpen 2002 in Zurich) showed that SVG is ideally suited for building svg-maps of any kind. Because the atlas will contain quite a lot of maps (50 - 100) a manual generation of these maps is too time-consuming and i had to find an automated method of map generation. I heard of mapmaking with PHP and also with PERL, but because the Apache Cocoon Framework is completely based on XML-workflow, I decided to use it in this project to develop a mapserver.

The data of the thematic atlas consists mainly of swiss census data and some special data ascertained by other students working on the same project. I chose MySQL as the Database-Management-System in this application because it is easy to setup and use and because there is no need to use GIS-enabled Database-Management-Systems like Oracle Spatial or PostgreSQL. The data was filled into the tables very easily and quickly using CSV-import.

The user creates the maps by accessing the webpages of the mapserver. There he can configure the mapdata to be visualized, the map symbols, the map size and several other parameters. The map generation process is controlled by XML Server Pages (XSP) and the ESQL-Logicsheet. Those two cocoon-modules create the SQL-queries and put the results of the queries into a valid XML-stream, which will be transported to the XSL-transformer. The connection to MySQL is controlled by a JDBC-driver. This transformer uses an XSL-processor (by default: xalan) to transform the XML-stream into a SVG-stream using a XSL-stylesheet. The resulting SVG-stream is then being transported back to the user.

To provide maps for three different medias I had to develop different XSL-stylesheets. There is a stylesheet for internet- and CD-ROM-maps (enabling user-interaction) and a stylesheet for maps of the printed atlas (no user-interaction). Those maps for the printed atlas can be imported into an appropriate software (e.g. Corel Draw, Adobe Illustrator and others) to integrate them in the printed atlas.

The Apache Cocoon Framework is an ideal tool for building dynamic SVG-maps for different output-medias, because it is completely based on Open Source-Technology and on XML-workflow. And SVG is not only suited for creating interactive webmaps but also for designing conventional printed maps.

Table of Contents

What is Apache Cocoon?
     Basic Concepts
The Mapmaking Process
     The User Side
     The Database
     The Server Side
The Maps


This presentation is based upon my diploma thesis I finished this spring at the department of geography at the university of Berne. The starting point for my work was a project at our university that intends to create a thematic atlas of the urban region of Berne. Our department has produced such an atlas for another region before. But this time not only a printed atlas was planned but also an online atlas and an atlas on a CD-ROM. While other students will be working on the content of the atlas, my job was to create a concept for processing the data and creating the maps. After some research in the internet it became quite clear to me that SVG has probably the biggest potential to do this job.

The atlas tries to present the spatial, demographic, economic and political structure of the region of Berne. Figure 1 locates this urban region.


Figure 1: The Berne Region in Switzerland.

More information about the intentions and the contents of this thematic atlas can be found at: (in german only)

The region consists of 33 municipalities and the city of Berne. About 320'000 people live there and the region covers an area of about 400 square kilometers. All maps will have this region as a base. Only a few maps have an extended perimeter with 89 municipalities, because they show facts of interregional interest.

I started my work with some simple XSL-Transformations on the command line and had to see very quickly that on the one hand SVG is indeed the right graphics format to build an online atlas with and that on the other hand it is very laborious to transform the maps again and again after each change in the XSL-stylesheets. Therefore I looked for a more appropriate solution to build something like a mapserver. I considered tools like PHP or PERL but in the end I decided to use Apache Cocoon. Because I planned to create all the maps by transforming the basic data into SVG with XSL-stylesheets, Apache Cocoon seemed to be the logic solution, since its completely based on XML and it is able to communicate with a lot of different data sources.

What is Apache Cocoon?

Apache Cocoon is an XML publishing framework developed by the Apache Software Foundation. All the workflow inside Cocoon is based entirely on XML and it is able to communicate with different data sources as RDBMS, LDAP, native XML Databases or the Filesystem. If the right transformation is used, Cocoon can produce content for a lot of devices and a lot of formats like XML, SVG, XHTML (or any other XML-format), PDF (Apache FOP), RTF etc. Cocoon is programmed in Java and is a Java Servlet. Therefore a Servlet 2.2 compliant servlet engine must be available. Since the Apache Foundation also develops the Apache Jakarta Tomcat Servlet Container, I decided to use Tomcat. Currently I use Tomcat v4.1.24 and Cocoon v2.0.4.

Basic Concepts

Cocoon uses the following mechanisms to process XML documents:

All the steps of the XML processing are put together in a pipeline. The next figure shows a pipeline consisting of a generator (file generator: reading a xml document from the file system), a transformer (XSLT Transformer: applies a XSL stylesheet to the XML document) and a serializer (HTML serializer: delivers the transformed document to the requesting user):


Figure 2: Example of a simple Cocoon pipeline.

A Cocoon based XML application may consist of more than one pipeline. The decision about which pipeline is the right one is made by the matchers. These components receive the user request (mostly an HTTP request) and decide which pipeline matches. All those components are configured in one single place called the Sitemap. This is an XML based configuration file where on the one hand all necessary components are defined and where on the other hand all the pipelines and matchers are listed. This is the heart of Apache Cocoon. Figure 3 shows the configuration of the default transformer. In this case the default transformer is Apache Xalan, any other XSL processor (Saxon) could be configured here.

<map:transformers default="xalan">
     <map:transformer name="xalan" src="org.apache.cocoon.transformation.TraxTransformer">

Figure 3: Code snippet 1 from a Cocoon sitemap.

Figure 4 shows a part of a pipeline definition: The first line describes the matcher. All requests matching this matcher will be directed to this pipeline, which consists of a generator, a transformer an a serializer.

<map:match pattern="protected/statweb*">
     <map:generate type="xsp" src="xsp/statweb{1}.xsp"/>
     <map:transform src="transforms/xml2svg.xsl"/>
     <map:serialize type="gzip"/>

Figure 4: Code snippet 2 from a Cocoon sitemap.

The Mapmaking Process

In my Cocoon-based mapserver the map creation consists of three main components:

Figure 5 gives an overview of those components:


Figure 5: Maps with Apache Cocoon.

The User Side

The user wishing to view some maps is communicating with the Cocoon Server through his svg-enabled internet browser. The configuration and the selection of the maps is done on several xhtml pages. The choices made by the user are then handed over to Cocoon via HTTP-Request consisting of several parameters. When the map is produced by Cocoon it is sent back to the users browser and displayed by the SVG-Plugin. All the user needs is an SVG enabled Webbrowser. Figure 6 shows a screenshot of such an map configuration page:


Figure 6: Map Configuration with XHTML pages.

The user has the possibility to choose the data, that has to be visualized by the map, he can change the map symbols (circles, squares etc.), their colors and their relative size.

The Database

Because the structure of the used data is very simple and no special extensions (e.g. GIS-extensions) are needed here, I decided to install an easy to use DBMS and I chose MySQL 3.23.51. The communication betwenn Cocoon and MySQL is enabled by the JDBC-driver.

The data in this project comes from three different sources: The first source is the data from the Swiss Census (1990 and 1980). It is available for this project as a very simply structured CSV-file and can very easily be integrated into the database. The second source is the STATINF database ( of the Swiss Federal Statistical Office. This huge database offers a huge amount of statistical data from various thematical areas (e.g. forest statistics, health statistics, economic statistics etc.) The data can be downloaded as Excel files and then be exported as CSV-files. The third source is data, that has been collected by other students. They had to structure their data in a way, that made an easy integration into the database possible. Most of this self collected data consists of objects of special interest in the Berne region (schools, hospitals, train stations etc.), that are represented by a single point.

Besides the statistical data there is of course some geospatial data needed to draw maps. This data is also provided by the Swiss Federal Statistical Office and it is available as ESRI ArcView Shapefiles. In Arcview they can be exported into CSV-files and those files are imported into the database.

In MySQL the data from each datasource is imported into a separate table. The LOAD DATA INFILE command imports CSV-files into the table, which made the import process very easy.

All the data from the Swiss Federal Statistical Office is not publicly available and it is not free of charge. We had to order the data and pay some amount of money. Because we don't have the right to present the data in the internet, the maps are not open to the public. I had to configure a password protection (done with the tomcat server), for only a small circle is allowed to create and see the maps.

The Server Side

The map configuration is sent by the users webbrowser via an HTTP-request to Cocoon. The request is being matched in the sitemap and the appropriate pipeline is executed. At the beginning of the pipeline is the XSP-generator. XSP is a Cocoon technology that enables creation of dynamic XML data sources for feeding data into pipelines. These data sources are described using a combination of XML markup and application logic that is the automatically compiled into a java class by Cocoon

 <esql:query>SELECT name, <xsp-request:get-parameter name="merkmal"/> AS wert, x, y, 
 (ROUND(SQRT(<xsp-request:get-parameter name="merkmal"/>)*<xsp-request:get-parameter name="mult"/>))
 AS seite FROM datgem<xsp:expr>zusatz</xsp:expr>ORDER BY wert DESC</esql:query>
    <xsp:param name="name">
     <xsp-request:get-parameter name="symb"/>

Figure 7: Code snippet from an XML Server Page.

With XSP it is possible to create XML dynamically. The parameters from the HTTP-request are inserted into the SQL-statement to produce a dynamic SQL-query (see line 2 in Figure 7 ). The query is sent to MySQL, whose result is then transformed by the XSP into valid XML.

The resulting XML is then sent to the next stage in the pipeline: the transformer. In this case the transformer is an XSLT-transformer. There is a central XSLT-stylesheet (xml2svg.xsl) for all the maps of this mapserver. This stylesheet controls the transformation of the XML-data into an SVG-map. Figure 8 shows some lines of the stylesheet, where the border of the municipalities are transformed into a path-element.

<xsl:template match="einheit">
  <xsl:attribute name="id"><xsl:value-of select="name"/></xsl:attribute>
  <xsl:attribute name="d"><xsl:value-of select="koord"/></xsl:attribute>
  <xsl:attribute name="onmouseover"><xsl:text>showname(evt,'</xsl:text><xsl:value-of select="name"/><xsl:text> ','')</xsl:text></xsl:attribute>
  <xsl:attribute name="onmouseout"><xsl:text>showname(evt,'','');unshowcoords(evt)</xsl:text></xsl:attribute>

Figure 8: Creating path-elements in the XSL-stylesheet.

All the other transformations are done in a similar way. All the informations about formatting and scripting are located in external files (svg.css and svg.js).

The Maps

The main purpose of this mapserver is to create screen maps. Figure 9 shows a screenshot of such a map. it offers some basic navigation functionality as e.g. zooming and panning (programmed in javascript) and it displays in the lower left part some basic information (coordinates and values) about the location of the mouse pointer. Some more functionality is planned in the future. All the legends and titles are generated dynamically, they are not hardcoded.


Figure 9: Online SVG-map.

One speciality of Cocoon are its "views". This features allows to apply different XSL-stylesheets to the XML-data. I implemented four different views. The default view is the one for producing screen maps as seen above. The other main view is the one for producing printable and importable svg-maps. These can be imported into a vector graphics software (I tested them only with Corel Draw 11, but it should work too with Adobe Illustrator). They have been optimized for the import. Once they are imported they can be edited and/or printed out. A third view takes one of those import optimized map and creates an bitmap graphics (PNG) out of it with the help of the batik-rasterizer libraries. Figure 10 shows the same map as in Figure 9 in PNG. The fourth view doesn't display a map. It just shows the XML-data before it is transformed by the XSL-transformer. I added this view only for debugging purposes.



The main conclusion is the following: My work shows that it is very well possible to create svg-maps with Apache Cocoon. But beside the advantages of this method some negative points have occurred:



XHTML rendition created by gcapaper Web Publisher v2.0, © 2001-3 Schema Software Inc.