Copyright © 2010-2012 Geosparc nv
Documentation for first time users to get started with the Geomajas GIS framework.
Table of Contents
List of Figures
Table of Contents
Geomajas uses the Apache Maven project management tool for its build and documentation process. The easiest way to start using Geomajas is by creating a new project using the Maven archetype. This will create a simple working project that you can use as a starting point.
To create the simple project with the Maven archetype, you need to
install Maven on your system. Maven 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: unzip the distribution file in the
directory of your choice and make some environment changes so you can run
mvn. More information for your specific OS can
be found at the bottom of http://maven.apache.org/download.html.
At this point it is assumed that Maven has been successfully installed. Using Maven, you can now create your Geomajas project, called the Geomajas GWT Application archetype.
Step1: Go to the folder you want to create the Geomajas application in, and execute the following command:
Example 1.1. Create project using Maven archetype
mvn archetype:generate -DarchetypeCatalog=http://files.geomajas.org/archetype-catalog.xml
Maven will now prompt the user for input.
If anything fails with these Maven commands, you need to check the output to check the problem. One typical problem is the need to define a proxy to allow Maven to access external repository websites. See the http://maven.apache.org/guides/mini/guide-proxies.html for details.
Step2: Maven will display the full list of available archetypes. Make sure you select the correct one: geomajas-gwt-archetype. In the image below, the correct number would be 36:
Step3: Next Maven asks for the groupId. Often the package name is used, but any other name will do (e.g. myGroupId).
Step4: Next Maven asks for the artifactId. This represents the name for your application (e.g. myApp).
The artifactId cannot contain special characters!
Step5: Next Maven asks for the first version for your application. 1.0-SNAPSHOT is a good first version.
Step6: Next Maven asks for the base package wherein to place Java files. By default this is the same as the groupId. Just hit "enter" to continue with the default or enter another package name (e.g. my.app).
You have now created a Geomajas project! Now you are ready to run it.
Step1: Go to the folder with the artifactId name (myApp in the example above) and execute the following command:
The "install" target will create a web archive (.war file) for
the project in the
target directory. This .war file can
be dropped into a Java application container such as Tomcat.
The "jetty:run" target will immediately start a jetty server and start the application in it. Jetty is a Java application container that can run your project without the need to install a separate Java application.
Step2: Open a web browser and access your Geomajas application at http://localhost:8080/.
Once you have your Geomajas project running, you might want to make some modifications to the Geomajas configuration and customize it. More details about the Geomajas configuration can be found in the developer's guide.
Here you find the most important configuration files used in your Geomajas project:
main configuration : src/main/webapp/WEB-INF/applicationContext.xml
map configuration : src/main/webapp/WEB-INF/mapMain.xml
overview map configuration : src/main/webapp/WEB-INF/mapOverview.xml
countries layer configuration : src/main/webapp/WEB-INF/clientLayerCountries.xml and src/main/webapp/WEB-INF/layerCountries.xml
OpenStreetMap layer configuration : src/main/webapp/WEB-INF/clientLayerOsm.xml and src/main/webapp/WEB-INF/layerOsm.xml
GWT configuration file : src/main/java/Application.gwt.xml
If you have the jetty server running and you make changes to the configuration, press ENTER to reload the application without stopping the server.
The Geomajas sample application comes with a predefined layer configuration for PostgreSQL/PostGIS and SQLServer databases (configurations for other supported databases like Oracle and MySQL can be added in a similar way).
To activate the database layer, the following steps should be taken:
Create the sample database. This should be a spatially enabled database with name 'app' and login user 'app' with password 'app'.
Import the layer data in the database. For reference , the data is provided as a shape file in the directory: src/main/resources/context/shapes/road.shp. There are also 2 scripts available for both the PostGIS and SQLServer databases: src/main/webapp/WEB-INF/example/road_postgres.sql and src/main/webapp/WEB-INF/example/road_sqlserver.sql. These can be run from PgAdmin or SQL Server Management Studio respectively.
Uncomment the necessary dependencies in your pom.xml file. Geomajas provides 2 layer plugins that can work with databases: Geotools layer and Hibernate layer plugin. The Geotools layer plugin does not require the creation of a Java mapping, which makes it easier to configure, but it also has no support for complex attributes (many-to-one, one-to-many). The Hibernate layer plugin does require Java mapping objects (have a look at the Road.java class to see how the mapping works) but offers complex attribute support instead. The choice of layer plugin will depend on the needs of your application and whether or not you want to make use of the advanced feature editing capabilities of Geomajas. As an example, for the Geotools layer with a PostGIS database, the following dependencies should be uncommented:
<!-- uncomment if you want to use geotools with postgis, for another db you will need similar dependencies --> <dependency> <groupId>org.postgis</groupId> <artifactId>postgis-jdbc</artifactId> </dependency> <dependency> <groupId>postgresql</groupId> <artifactId>postgresql</artifactId> </dependency>
Uncomment the necessary application context entries in your web.xml file. This is necessary to add the roads layer to your Spring context definition. The specific entries to uncomment will again depend on your choice of layer plugin and database. For he Geotools layer with a PostGIS database, the following entries should be uncommented:
<!-- To use Roads layer stored in PostGIS through GeoTools layer, uncomment the following --> WEB-INF/example/geotools/mapMain.xml WEB-INF/example/geotools/spring-geotools.xml WEB-INF/example/geotools/clientLayerRoads.xml <!-- for PostGIS --> WEB-INF/example/geotools/postgis/layerRoads.xml
Restart your application. An editable road layer should appear.
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://repo.geomajas.org/nexus/index.html#nexus-search;quick~geomajas-dep.
References which may be interesting to read:
GWT project page: http://code.google.com/webtoolkit/.
SmartGWT showcase: http://www.smartclient.com/smartgwt/showcase/.
DZone's GWT refcardz: http://refcardz.dzone.com/refcardz/gwt-style-configuration-and-js.
Spring documentation: http://www.springsource.org/documentation.
DZone's Spring configuration refcardz: http://refcardz.dzone.com/refcardz/spring-configuration.
Maven project: http://maven.apache.org/.
Maven by example book: http://www.sonatype.com/books/mvnex-book/reference/public-book.html.
Maven reference book: http://www.sonatype.com/books/mvnref-book/reference/public-book.html.
DZone's maven 2 refcardz: http://refcardz.dzone.com/refcardz/apache-maven-2.
Table of Contents
This chapter is aimed at Java developers that whish to import the Geomajas project in their favourite IDE and start programming. The use of an IDE is not really required if you only want to configure layers, styles, etc.
The combination of Eclipse, maven and GWT is not quite trivial, especially for advanced multi-module projects like Geomajas. There are 2 approaches possible for integrating eclipse with maven:
Eclipse plug-in for maven, avoiding the use of the maven command-line interface: m2eclipse (http://m2eclipse.sonatype.org/) is the most mature project here
Maven plug-in to generate eclipse project configurations: maven-eclipse-plugin (http://maven.apache.org/plugins/maven-eclipse-plugin/)
It is clear that an IDE integrated solution like m2eclipse offers considerable advantages over manually generating Eclipse project configurations:
direct import of maven projects
support for maven properties and filtering
In-place editing of poms
full dependency support
For a functional Geomajas setup, the following Eclipse plug-ins should be installed on a fresh Galileo download (http://www.eclipse.org/downloads/):
m2eclipse: update site http://m2eclipse.sonatype.org/sites/m2e
m2eclipse extras (especially WTP extension): http://m2eclipse.sonatype.org/sites/m2e-extras
checkstyle: update site http://eclipse-cs.sf.net/update/
SVN team provider: update site http://download.eclipse.org/releases/helios, choose Collaboration ->Subversive SVN Team Provider (Incubation)
Google's GWT Eclipse plug-in: http://dl.google.com/eclipse/plugin/3.6 (Plugin and SDK)
There is a classpath issue with the Google Plug-in for Eclipse (GPE) that prevents us from using it in a reliable way when there are multiple versions of artifacts in the maven dependency tree: http://code.google.com/p/google-web-toolkit/issues/detail?id=5033
On top of that, GPE forces the use of the built-in jetty launcher, which has problems with loading libraries from the maven repository. Recent development by Google points in the direction of better maven support, but a as far as we know a stable solution which does not require explicit user interaction is not available. (see http://googlewebtoolkit.blogspot.com/2010/08/how-to-use-google-plugin-for-eclipse.html).
In view of these problems, the following workaround seems to be the most reliable way of using the GWT plugin for us:
Run the GWT plug-in with the no-server option (this can be done straight from the project since GWT 2.1
Run an embedded Jetty server to replace the GWT server
The following series of steps have to be performed to achieve a working project.
Import the project as a maven project
After the project has been imported and the workspace has been built, you should now manually mark the project as a GWT project in the project properties dialog. Open the Google -> Web Toolkit section and mark the checkbox. If the eclipse GWT version differs from the project version, the "Use specific SDK" checkbox will be enabled:
In the Google -> Web Application section, the WAR directory should be changed to the default maven war sources directory (src/main/webapp)
Open the debug configurations dialog and create a new Java application:
Search for JettyRunner as the main class. JettyRunner is a specially prepared main class that starts up Jetty with the correct parameters (port 8888 and src/main/webapp as webapp directory)
Run the new Jetty server configuration (in debug mode):
Now, run the GWT plug-in in no-server mode by by right-clicking on the project and selecting Debug As -> Web Application (running on an external server):
Click ok on the dialog screen
You can now add breakpoints and debug your application as if it was a normal Java application.
If you have multiple versions of GWT in your project workspace, make sure that the gwt-dev jar is in front of the default classpath (reported GWT issue):
If you want to run your application directly with GPE, some extra actions are needed to avoid classpath problems. You will have to change your web.xml by adding a special context listener that allows Spring component scanning and circumvents a GeoTools problem with the builtin Jetty classloader:
<listener> <listener-class>org.geomajas.servlet.PrepareScanningContextListener</listener-class> </listener>
This solves most of the classpath problems but does not cure the problem of having multiple artifact versions in the classpath! This is usually only a problem when you have several Geomajas projects opened in your workspace. If this is the case, run the GWT plug-in with an embedded Jetty server as explained in the previous chapter and you should be fine. Note that this should be the first listener in your web.xm files, before the spring listeners.
The following steps are needed to run GPE directly:
Follow the configuration steps of the indirect mode, right up to the Jetty part
Run the project as a GWT Web application by right-clicking
on the project and selecting
Run as -> Web
For debugging, debug the project as a GWT Web application by
right-clicking on the project and selecting
Debug as ->
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.
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.
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.
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:
After this, you should be able to run the project. Any changes in the source code will be automatically detected, and debugging is possible.
When creating GWT run configurations, it is recommended to increase the amount of memory given to the process. You can do this by entering a higher -Xmx value in the VM parameters field, for example "-Xmx768m".
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.
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 extensible. 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 browser. In essence, Geomajas provides a set of powerful building blocks, from which the most advanced GIS applications can easily be built. Key features include:
Clearly defined API
Integrated client-server architecture
Advanced geometry and attribute editing with validation
Custom attribute definitions including object relations
Advanced querying capabilities (searching, filters, style, ...)
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 "
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:
Pieter De Graef
Jan De Moerloose
Joachim Van der Auwera