Geomajas contributor guide

For faster compilation during testing (when not using development mode), it can be useful to compile only for the browser used for testing. This will reduce the number of compilation steps by a factor 6. Removing supported languages can further remove compilation steps. Include the following excerpt in your Xxx.gwt.xml file to set your target browser.

<!-- set target browser to compile for, use this to limit to the browser used for testing -->
<!-- where value = "ie6/opera/gecko1_8/safari/gecko" , "gecko1_8" is FireFox 3 -->
<set-property name="user.agent" value="gecko1_8" />

For development using the dojo face, apart from using the "-DskipShrink" setting mentioned higher, you may also want to configure the ResourceController to try to directly read the JavaScript files from disk before looking at the classpath (it also changes the cache headers). This allows a simple refresh in the browser to load the changed versions. You can configure this using a init-param for the dispatcher servlet, like in this example.

<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
        <param-name>files-location</param-name>
        <param-value>/home/me/apps/java/geomajas/geomajas/geomajas-dojo-client/src/main/resources</param-value>
        <description>
            When this is specified, files are searched here first.
            Files which are found at this locations are not cached.
        </description>
    </init-param>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath*:META-INF/geomajasWebContext.xml</param-value>
        <description>Spring Web-MVC specific (additional) context files.</description>
    </init-param>
    <load-on-startup>3</load-on-startup>
</servlet>

Once you have done a "mvn install" on either the entire tree or the "Geomajas" directory, you can use maven to run the example applications.

For the dojo face, you can run the examples using (when in the geomajas-dojo-example directory)

mvn jetty:run

For the gwt face, you have three options. Once in the geomajas-gwt-simple directory, you can run the application in development mode using

mvn gwt:run

You can also use jetty to run the normally built application

mvn jetty:run

Alternatively you can run the actual war using

mvn jetty:run-war

Unit testing: At least each class implementing the public API should have a unit test, testing all methods. For testing JUnit is used.

*Never* throw away exception, either log them or throw them again (possibly wrapped). Do not log and throw, this only clutters log files with duplicate exceptions.

Do not wrap exceptions unnecessarily (so no GeomajasException caused by a GeomajasException) unless you add additional information in the message.

When wrapping an exception, always include the cause.

Changes in the (public) API use a "deprecate, then remove" cycle. It should be marked "deprecated" in at least one minor version before it can be removed in the next major version.

All source files, including .properties files should use UTF-8 encoding.

For the directory structure and file locations, we follow standard maven conventions (see http://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html).

/*
 * This is part of Geomajas, a GIS framework, http://www.geomajas.org/.
 *
 * Copyright 2008-2011 Geosparc nv, http://www.geosparc.com/, Belgium.
 *
 * The program is available in open source according to the GNU Affero
 * General Public License. All contributions in this program are covered
 * by the Geomajas Contributors License Agreement. For full licensing
 * details, see LICENSE.txt in the project root.
 */

Note that the end year (shown here is 2010) should always be the current year. All headers will be updated at the beginning of each year.

Be proud of your code and take responsibility of your changes. When making any kind of significant changes (not for reformatting, fixing typing errors or renaming), add your full name at the bottom of the authors list in the class comments.

See the example below

/*
 * This is part of Geomajas, a GIS framework, http://www.geomajas.org/.
 *
 * Copyright 2008-2011 Geosparc nv, http://www.geosparc.com/, Belgium.
 *
 * The program is available in open source according to the GNU Affero
 * General Public License. All contributions in this program are covered
 * by the Geomajas Contributors License Agreement. For full licensing
 * details, see LICENSE.txt in the project root.
 */

package org.geomajas.bladibla;

/**
 * Short description of the purpose of this class.
 *
 * @author Author's name
 * @author Another Author's name
 */
@Annotation(param1 = "value1", param2 = "value2")
public class Foo implements Serializable {

    int[] x = new int[] {1, 3, 5, 6, 7, 87, 1213, 2};

    /**
     * Do something
     *
     * @param x some data
     * @param y more data
     */
    public void foo(int x, int y) throws Exception {
        for (int i = 0; i < x; i++) {
            y += (y ^ 0x123) << 2;
        }
        do {
            try {
                if (0 < x && x < 10) {
                    while (x != y) {
                        x = f(x * 3 + 5);
                    }
                } else {
                    synchronized (this) {
                        switch (e.getCode()) {
                            //...
                        }
                    }
                }
            }
            catch (MyException e) {}
            finally {
                int[] arr = (int[]) g(y);
                x = y >= 0 ? arr[y] : -1;
            }
        }
        while (true);
    }
}

We have both an eclipse and IntelliJ IDEA formatter which can be used. However, be careful not to change the entire formatting of a class.

Bean names match the (fully qualified name of the) interface they implement if there is only one implementation to be used. When this is not the case, the bean name is the (fully qualified) classname. When the bean name starts with "org.geomajas.", this is cut off. Interfaces which are expected to have several alternate implementations should be annotated with the "@ExpectAlternatives" interface.

There is a "GeomajasBeanNameGenerator" class which tries to automatically determine the bean names, assuring that you don't need to mention this explicitly in the "@Component" annotation. If the first interface which is implemented by the class does not have the "@ExpectAlternatives" annotation, then the fully qualified name of the first interface is used as bean name. For all other beans, and for beans which are in a "command" package and don't have a class name starting with "Default" the fully qualified class name is used. In all cases the bean name has the "org.geomajas." prefix removed is present (using the "GeomajasBeanNameGenerator.simplify()" method.

Note that these rules are built to easily replace instantiation based on class names by instantiating based on bean names. For the same class name, you can often replace the code

Class.forName(className).newInstance();

by

applicationContext.getBean(GeomajasBeanNameGenerator.simplify(className));

For servlets, you should configure the Spring context loader listener in the web.xml file. You should also add the request context listener to assure session scoped beans work and can access the request. This is shown in the code below.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd" >
<web-app>
    <display-name>Geomajas application</display-name>
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            classpath:org/geomajas/spring/geomajasContext.xml
            WEB-INF/applicationContext.xml
        </param-value>
    </context-param>

    <listener>
         <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    <listener>
         <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
    </listener>
    .....

The "contextConfigLocation" context parameter is a space separated list of Spring context files. The root Geomajas context - which is contained in the Geomajas backend - should always be put on top of this list. The root context will load all the predefined back-end services and automatically import plug-in context files of all the available plug-ins on the class path. Below that you may specify additional application context definition files which are needed for your application. You can include several files by separating them using whitespace. Each location can include the protocol/location used to find the file. Ant-style wild cards can be used. If no protocol is specified, the web application context root is searched. The following are examples of allowed patterns:

WEB-INF/applicationContext.xml
WEB-INF/layer*.xml
file:C:/some/path/*-context.xml
classpath:com/mycompany/**/applicationContext.xml
classpath*:conf/appContext.xml

The classpath* pattern is specific in that it will combine all the resources that match this exact pattern in the class path, not just the first one.

The web application context can conveniently be retrieved from the servlet configuration in other servlets:

public void init(ServletConfig config) throws ServletException {
    return WebApplicationContextUtils.getWebApplicationContext(servletContext);
    .....

Each plug-in can have a configuration file in META-INF/geomajasContext.xml which is automatically included in the application context (after the main geomajasContext which comes from the impl module, but before all files which are explicitly added (through web.xml)).

This context file should at least declare the plug-in, the plug-ins and dependent version it depends on, and the copyright and/or license information for all other dependencies. It also has to indicate the API version which is used. This is also version which is used for the back-end (which includes the API) which is used in the pom. Assuming this compiles and that you only used

The dependencies are used to check compatibility of the plug-in with the back-end and required plug-ins. If you only access them using the API, this should assure that everything stays compatible.

<bean class="org.geomajas.global.PluginInfo">
    <property name="version">
        <bean class="org.geomajas.global.PluginVersionInfo">
            <property name="name" value="Plug-in name" />
            <property name="version" value="${project.version}" />
        </bean>
    </property>
    <property name="backendVersion" value="1.7.1" />
    <property name="dependencies">
        <list>
            <bean class="org.geomajas.global.PluginVersionInfo">
                <property name="name" value="Static security" />
                <property name="version" value="1.7.1" />
            </bean>
        </list>
    </property>
    <property name="copyrightInfo">
        <list>
            <bean class="org.geomajas.global.CopyrightInfo">
                <property name="key" value="Geomajas"/>
                <property name="copyright" value="(c) 2008-2011 Geosparc nv"/>
                <property name="licenseName" value="GNU Affero General Public License, Version 3"/>
                <property name="licenseUrl" value="http://www.gnu.org/licenses/agpl-3.0.html"/>
            </bean>
            <bean class="org.geomajas.global.CopyrightInfo">
                <property name="key" value="Apache commons"/>
                <property name="copyright" value=""/>
                <property name="licenseName" value="Apache License, Version 2.0"/>
                <property name="licenseUrl" value="http://www.apache.org/licenses/LICENSE-2.0.html"/>
            </bean>
        </list>
    </property>
</bean>

You can add any other configuration which is necessary in this file, for example configure pipelines, register services.

Note that when adding dependencies, you should run dependency:tree (or similar) to check for sub-dependencies and assure the copyrightInfo list remains complete with copyright and license details for the dependent libraries.

Each plug-in can have a configuration file in META-INF/geomajasWebContext.xml which is automatically included in the web context for the dispatcher servlet. This is used to allow plug-ins to define additional web endpoints without the need to define servlet entries in web.xml.

The DispatcherServlet allows use of Spring MVC for defining your controllers and views. Any definitions which are specific to the web tier, should be put in the web context file. The services which are defined in the application context can also be used.

A typical context will define the package to scan (note that if the package which contains the controllers was already scanned in geomajasContext.xml, you will still need to redeclare the scanning to allow controllers to be picked up). The example context as used for the ResourceController looks like this:

<beans
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">

    <context:component-scan base-package="org.geomajas.servlet"/>

</beans>

The pom needs to be complete to allow proper release of the plug-in.

The following sections need to be filled in:

The build should also include the following settings

Many of these requirements can be met by inheriting from the geomajas-parent project.

All plug-ins consist of at least two modules, possibly more.

Of module contains the documentation for the plug-in in docbook format. A template module is generated when you use the geomajas-plugin-archetype.

The actual work should be done in one or more modules. You need more than one module when there is face specific code in the plug-in.

The process for a plug-in to move state from incubation to graduated, is called graduation. In order for a plug-in to graduate, several criteria need to be met.

The following is a list of plug-in graduation criteria:

Graduation is an all-or-nothing process. A plug-in either meets all criteria, or it does not. The plug-in maintainer can propose to graduate a plug-in on the majas-dev mailing list. When there is community agreement on the proposal, he or she can initiate a PSC vote. A request for graduation can only be vetoed by including the steps which need to be taken to graduate. Once these steps are taken, the plug-in maintainer can again propose to graduate.

Plug-in retirement is also handled by a PSC vote. This will typically happen when a plug-in is deprecated (focus moves to a different plug-in which supersedes the retired one), or when a plug- in maintainer wants to quit without having someone to follow up. However, anyone can propose to retire a module. This will normally be denied if the plug-in maintainer is still actively maintaining the module.

Both incubation and graduated plug-in can become retired. Reactivation of a retired plug-in, is of course possible when a new maintainer can be found. In this case the plug-in becomes an incubation plug-in again (and the maintainer must have signed a CLA).

When you report a problem, please submit one issue per problem. There are various reasons for this, amongst them:

In particular, if you're going to write sentences like "Besides this, I noticed that..." or "There are several problems with....", then please seriously ask yourself whether you should submit multiple issues instead of a single one.

If you don't follow this rule, be prepared for people asking you to split up your issue.

Providing a meaningful summary helps the committers to easily recognize an issue in a list of dozens of others. Since duplicate issues are draining a lot of work from committers, you should always check if the issue you wish to report hasn't already been reported. Of course this works best if the summaries of the existing issues are as descriptive as possible.

You, as the submitter of a problem, know exactly what you were doing when you were hit by the problem. However, most other people probably don't. For instance, they may have a completely different workflow for doing the same things you are doing.

In order to prevent committers to have to ask back how exactly an issue can be reproduced, it is the task of the issue's submitter to be as clear on this as possible - preferably by given a step-by-step description.

Geomajas is uses the Apache Maven project management tool for its build and documentation process. Maven can be downloaded from the Apache project site: http://maven.apache.org 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

Geomajas uses subversion as its version control system. Accessing subversion requires you to at least install a compatible client. There are numerous client solutions available, some as standalone clients and some as IDE plug-ins:

The Geomajas repository can be found at https://svn.geomajas.org/majas. The standard SVN repository layout is followed: trunk, tags and branches. For the latest and greatest code (including GWT face) you should check out the trunk:https://svn.geomajas.org/majas/trunk.

The GWT (Google Web Toolkit) software development kit (SDK) should be downloaded from the Google site: http://code.google.com/webtoolkit/download.html. After downloading you should unzip it in a directory of choice.

Start by recursively checking out the trunk directory to a new local folder with a name of your choice (e.g. geomajas-trunk). You will see that the source code layout follows the recommended hierarchical layout structure for multi module maven projects:

Figure 6.1. Hierarchical project layout

Build the code by running the install command on the pom in the top directory:

geomajas-trunk> mvn install

The install procedure will build all code, run all unit tests and install the artifacts in the repository. Integration tests based on Selenium will also be run.

The following steps are required (see "Getting Started" for more detail)

Eclipse project configurations can be alternatively be generated using the maven Eclipse plug-in. Running eclipse:eclipse fails on trunk because of an issue with maven filtering: http://jira.codehaus.org/browse/MECLIPSE-576. This will be fixed in the upcoming 2.9 release of the plugin, in the meantime you can back up to 2.6:

mvn -P noshrink eclipse:clean org.apache.maven.plugins:maven-eclipse-plugin:2.6:eclipse 

After the command has completed, Eclipse project definitions will have been generated for all subprojects (except the pom projects). These projects can now be imported into Eclipse.

Next you have to make sure that you have a personal SVN profile configured in your maven settings.xml. Concretely, make sure you have a settings.xml file in your maven directory (~/.m2/settings.xml) with the following content:

<settings> 
    <servers> 
        <server> 
            <id>svn.geomajas.org</id> 
            <username>my SVN username</username> 
            <password>my SVN password</password> 
        </server> 
    </servers> 
    <server> 
        <id>sonatype-nexus-snapshots</id> 
        <username>pieterdg</username> 
        <password>my sonatype pasword</password> 
    </server> 
    <server> 
        <id>sonatype-nexus-staging</id> 
        <username>pieterdg</username> 
        <password>my sonatype pasword</password> 
    </server>
</settings> 

The pre-release checks above only need to be done the first time you wish to release a Geomajas artifact. Here we describe the checks that need to be done every time a single artifact is to be released.

These checks are the following:

Commit any changes you have had to make.

The basic procedure is quite easy: we let the maven release plug-in do all the work for us. Essentially, it is a two-step procedure: first prepare the release, then perform the release.

Make sure you start with a fresh checkout from trunk before actually attempting to release anything. Checkout command:

svn checkout https://svn.geomajas.org/majas/trunk <destination folder>

It might be that after the checkout you have to make sure that you have write access to all files and folders within the newly created <destination folder>.

mvn -DdevelopmentVersion=1.8.0-SNAPSHOT release:prepare

mvn release:rollback

mvn release:perform

Now that the release has been placing in the staging area on sonatype, we can work towards finishing the staging procedure. In order to do so, the following steps need to be undertaken:

Start a vote on majas-dev for release of the part. The voting period should be at least two working days and span a weekend. The voting message should read something like "VOTE: release blabla plug-in v1.0.0" (please note capitalization).

The body of the vote needs to include:

When the voting period has ended, count the votes. The vote is successful when there are at lease two +1 binding votes and no -1 binding votes.

Reply to your original vote message on majas-dev, change the title to start with "VOTE SUCCESSFUL" or "VOTE FAILED" (please note capitalization). In the body of the vote, include the full name of all voters and their vote.

When the vote failed, drop the repository. All the references to the release version in trunk need to be rolled to the new snapshot version. The version number is skipped. The release date in JIRA is actually the staging date.

The geomajas-dep pom and aggregate.sh need to be updated for the newly released versions respectively.

Build announcement message, it is recommended this contains the following:

Send announcement to majas-dev (plain text).

Publish on general forum.

Announce on freshmeat.

Create news item on geomajas.org site.

Send mail to jan.pote@geosparc.com to allow sending a press release.

Create download image for this version (278x61 pixels).

Add release on download page (remember to name the page "release_1.5.0" with correct version number).

Update the download block on the Geomajas site.

Update the javadoc links on the documentation page.

Update Geomajas wikipedia page.

The documentation uses the example applications for extracting code which is included in the manual. This is a circular dependency when it includes the part to be released. It may be useful to do a local build using the next release version locally, to allow the release the work for the documentation part. You can do the actual release of the example application at the end.

On gaya, update/var/www/files.geomajas.org/htdocs/archetype-latest.xml. Make sure the version is correct.

On gaya, update/var/www/files.geomajas.org/htdocs/archetype-staging.xml. Make sure the version is correct.

Include the command to try the archetype in the vote message.

It is recommended to start this vote only when all modules which are referenced are already released. In that case, you don't have to mention the staging repository in the vote message.

On gaya, update/var/www/files.geomajas.org/htdocs/archetype-catalog.xml. Make sure the version is correct.

Upload war files to sourceforge download area.

Update the showcase on gaya. Make sure the Google API key is set.