Getting started with Geomajas

Documentation for developer who want to use and extend the Geomajas GIS framework.

Geomajas is a free and open source GIS application framework for building rich internet applications. It has sophisticated capabilities for displaying and managing geospatial information. The modular design makes it easily extendable. The stateless client-server architecture guarantees endless scalability. The focus of Geomajas is to provide a platform for server-side integration of geospatial data, allowing multiple users to control and manage the data from within their own browsers. In essence, Geomajas provides a set of powerful building blocks, from which the most complex GIS applications can easily be built. Key features include:

See http://www.geomajas.org/.

Copyright © 2009-2010 Geosparc nv.

Licensed under the GNU Affero General Public License. You may obtain a copy of the License at http://www.gnu.org/licenses/

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU Affero General Public License for more details.

The project also depends on various other open source projects which have their respective licenses.

From the Geomajas source (possibly specific module), the dependencies can be displayed using the "mvn dependency:tree" command.

For the dependencies of the Geomajas back-end, we only allow dependencies which are freely distributable for commercial purposes (this for example excludes GPL and AGPL licensed dependencies).

This framework and documentation was written by the Geomajas Developers. If you have questions, found a bug or have enhancements, please contact us through the user fora at http://www.geomajas.org/.

List of contributors for this manual:

As the simple project is created using the Maven archetype, you will need to install Maven on your system, which can be downloaded from http://maven.apache.org/. We recommend using the latest stable version (2.2.1 at the time of writing). Installing Maven is quite simple: just unzip the distribution file in the directory of your choice and make some environment changes so you can access the executable. More information for your specific OS can be found at the bottom of http://maven.apache.org/download.html.

mvn install

mvn jetty:run

mvn gwt:run

The combination of Eclipse, maven and GWT is not quite trivial, especially for complex multi-module projects like Geomajas. There are 2 approaches possible for integrating eclipse with maven:

It is clear that an IDE integrated solution like m2eclipse offers considerable advantages over manually generating Eclipse project configurations:

For a functional Geomajas setup, the following Eclipse plug-ins should be installed on a fresh Galileo download (http://www.eclipse.org/downloads/):

<listener>
 <listener-class>org.geomajas.servlet.PrepareScanningContextListener</listener-class>
</listener>

The setup in IntelliJ IDEA is quite straightforward and does not require running a separate Maven command. Just open the project from IDEA by selecting the pom in the root directory.

Figure 2.11. Open project using pom

IDEA will recognize this as a GWT project and assign the correct facet but as always you will have to make your own run configuration (which is fortunately trivial). You will need version 9.0 or later for the GWT 2.0 support.

Figure 2.12. IDEA GWT run configuration

Before being able to use this configuration, you need to invoke the gwt:i18n Maven target to assure the files which are used for internationalisation are available (otherwise, you will get compilation errors). You can do this from the "Maven projects" tab.

Figure 2.13. run gwt:i18 target

Some additional settings have to be done in the "project structure" dialog. Apart from specifying the GWT installation directory, there is a specific project setting which has to be done manually, which is setting the target Web facet to "Web". The project structure for the simple GWT project should look as follows:

Figure 2.14. Project structure for simple GWT project

After this, you should be able to run the project. Any changes in the source code will be automatically detected, and debugging is possible.

You can both create the project from the archetype or open directly the Maven project in NetBeans. See http://wiki.netbeans.org/MavenBestPractices for more details.

The archetype generates a dependency on the geomajas-dep project to manage the version of the Geomajas dependencies. This project exists for the sole purpose of keeping track of the latest released versions. It is quite likely that a new version of geomajas-dep has been released since the latest release of the archetype. Therefore, we recommend you update this dependency to the latest version. You can check the latest version using this URL: http://apps.geomajas.org/nexus/index.html#nexus-search;quick~geomajas-dep.

The most important configuration files in the project are the following:

More details about the Geomajas configuration are found in the developer's guide.

Reference which may be interesting to read:

In this chapter a step-by-step guide is given of how to create a web-application based on Geomajas from scratch. The application is based on marine information and has the following features :

When using Eclipse and the GWT plug-in we removed the "generateAsync" feature from the pom.xml. Our code already contained manually generated async files, and this caused weird problems/conflicts.

Note that when you are in need of help you can always post questions on the Geomajas mailing list (check this page for instructions on how to join the mailing list) or on the Geomajas forum.

To create a new project based on Geomajas you must execute the following steps:

mvn archetype:generate -DarchetypeCatalog=http://files.geomajas.org/archetype-catalog.xml

Once this is executed you can , among others, use the following commands :

If you are using eclipse you want to start by using the mvn eclipse:eclipse command. This will make your project eclipse compliant. Once this command is finished go to eclipse, right-click on the project, properties, google and check that the project is using GWT. Note that every time you do an mvn eclipse:eclipse you will have to retake the steps. Most times you have to switch off/switch on the GWT marker in eclipse.

Figure 3.1. Update your project as a GWT project in eclipse after each mvn eclipse:eclipseA

Now you can already try and run the project. Either from within eclipse or from the command line using maven: mvn gwt:run. You will see that you now have a basic Geomajas project already showing an OpenStreetMaps layer and a vector layer based on shape files.

In this section we are going to explain how to add a layer to your Geomajas showing some of your own shape files. The layer we will be creating has the name VhaLayer.

To show your own shape files in Geomajas follow these steps :

In this section we are going to explain how to add a layer to your Geomajas showing some of your own shape files. The layer we will be creating has the name EcdisLayer.

Ecdis files are provided as simple feature files. The first step we are going to do is convert these files to PostGIS. After this we will configure Geomajas to display our created PostGIS data using hibernate.

Note that the WMS used in this example is a password protected WMS. Due to privacy reasons the login details are excluded from this example. Please use your own or a public WMS server to test out this part of the guide.

Geomajas doesn't have any native SOAP support implemented. So what you need to is create a normal GWT servlet which does the SOAP handling and sends information back to the client about the locations of the vessels. Finally at the Geomajas client side you can display these vessels.

The following steps should be taken :

FacilityXML documents are XML documents containing information about locks in Belgium. The goal was that when the user clicked on a lock in a certain layer the correct FacilityXML document was requested from the server and shown to the user in a nicely formatted way. The formatting is done using an XSL transformation.

Since the requesting of the XML and the XSL transformations isn't part of Geomajas this will not be discussed here. What will be show however is how you can add a listener to a layer and use data from the selected feature.

Figure 3.18. Controller that shows extra information about a clicked vessel