Geomajas Community Documentation

Geomajas contributor guide

Geomajas Developers and Geosparc

v1.7.1


1. Developers information
1.1. maven compilation, targets, profiles, variables
1.1.1. GWT build
1.1.2. dojo build
1.1.3. Running the example applications
1.2. Documentation
1.3. API contract
1.4. Versioning
1.5. subversion, commits
1.6. Coding
1.6.1. Logging
1.6.2. Unit testing
1.6.3. Exception handling
1.6.4. Refactoring
1.6.5. File encoding
1.6.6. Other
2. Coding quality and style
2.1. Class, method and variable names
2.1.1. Comment
2.1.2. Claim your code
2.1.3. Code layout
3. Spring usage in Geomajas
3.1. Spring dependency injection
3.1.1. Bean naming convention
3.1.2. Initialising the applicationContext
4. Face or plug-in
4.1. Plug-in structure
4.1.1. Plug-in application context
4.1.2. Plug-in web context
4.1.3. Plug-in pom
4.1.4. Plug-in modules
4.2. Plug-in creation
4.3. Plug-in state
4.3.1. Plug-in graduation
4.3.2. Plug-in retirement
5. JIRA conventions
5.1. Basic issue tracker rules
5.1.1. One problem one issue
5.1.2. Provide a meaningful summary
5.1.3. Provide a clear description
5.2. Filling out the JIRA form
6. Setting up your development environment
6.1. Prerequisites
6.1.1. Maven
6.1.2. Subversion
6.1.3. GWT
6.1.4. Build procedure
6.2. Eclipse
6.3. IDEA
6.4. Maven
7. How to release Geomajas
A. Geomajas Contributor License Agreement
A.1. Definitions
A.2. Granted Rights - Representations
A.3. Warranties
A.4. Miscellaneous
B. Maven repository

When doing an initial compilation of Geomajas, you may need to start compilation from the "build-tools" and then the "backend" directories. Only when these are compiled, compilation from the project root will succeed.

cd build-tools
mvn install
cd backend
mvn install
cd ..
mvn install

The source contains one main pom which allows building of the Geomajas framework and each of the sample applications in one go.

You can also choose to build them individually.

There are a couple of profiles defined which should help during development:

  • -DskipShrink: do not use shrinking when building or using the dojo face. When not specified, a shrinked version of the javascript files is used. The files are compressed and combined for faster loading and better caching.

  • -DskipDocs: do not build the documentation module. Can speed up the build a little.

  • -Dfull-build: from the root project, this enables inclusion of the build tools and documentation in the build. This is actually enabled by default (to desable use -Dhudson"),

  • -Dhudson: profile for running the selenium integration tests on the hudson continuous integration server. As long as running the tests on the ci server proves problematic, this will disable these tests.

The general documentation is split in three books.

  • developers guide: guide for developer who want to use Geomajas in their application.

  • contributors guide: guide for people who want to contribute to the project or want to know more about the functioning of the project (this one).

  • end user guide: documentation for end users of applications built using Geomajas.

Apart from that, each face and each plug-in has their own documentation.

All documentation is written in docbook format to allow both PDF and HTML output formats. The sources can be found in the "documentation" directory of the project.

For editing the docbook files, we recommend using XMLMind. The personal version is free and can (at the time of writing) be used for editing open source documentation.

The docbook files are currently formatted using XMLMind. When using another tool for editing, please keep the current formatting to assure diffs remain usable.

The documentation includes a lot of examples which are excerpts from the source of the example applications. This prevents copy-paste mistakes. The build process for the documentation automatically updates these excepts. The directories which have to be scanned for excepts are specified in the pom. When this includes code which is not in the current versioned entity (the root directory for the face or plug-in), then the source needs to be obtained from a dependency and unpacked. Excerpts can be annotated using annotations like

<!-- @extract-start AllowAllSecurity, Allow full access to everybody -->
<bean name="security.securityInfo" class="org.geomajas.security.SecurityInfo">
    <property name="loopAllServices" value="false"/>
</bean>
<!-- @extract-end -->

for XML or

// @extract-start filename, title
for (String line : lines) {
    // do something
}
// @extract-end

for java files. The start annotation includes the filename which should be used (all files are placed in the "listing" directory) and optionally a title for the example.

Note that details about coding style and naming are on the coding style page.

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

  • Advantages of unit testing:
    • Capturing a JIRA bug report in a reproducible manner.

    • Allowing you to specify exactly the behaviour you want, before you start coding.
  • How unit testing should be done:
    • If you are testing src/main/java/org/geomajas/ToBeTestedClass.java, create a class src/test/java/org/geomajas/ToBeTestedClassTest.java. Actual test methods have a name starting with "test". The class itself should extend jnit.framework.TestCase.
    • The test will automatically be run when running "mvn install".

  • Integration tests should also be provided. These can also be used for testing the user interface (thanks to selenium).

As a general note, the coding style and naming conventions should be adhered to. Some parts are even checked by the checkstyle maven plug-in. However, deviations are always allowed when this enhances code readability.

Formatters are available for the style as described here (see bottom of document). You can be liberal on applying this on new code, but be prudent when applying these to the existing code base. Code style changes make revision changes a lot more difficult and should thus be limited. If there is a need to reformat existing code, then this should be done in a separate commit.

Rules

  • Use meaningful names. Especially class and method names should explain their purpose.
  • For class, method and (non-static) variable names, use camelCase to separate the words, not underscores. For abbreviations, capitalize he first letter, lower case for the others.
  • Class names start with a capital, for example "CommandDispatcher".
  • Method and (non-static) variable names start lower case, for example "getEmptyCommandResponse".
  • All static variables should have capitalized names with words separated by underscores.
  • Package names are all lower case and should be singular.
  • Use get/set/isXxx.
  • Abbreviations and acronyms should not be uppercase when used as name (for example, use "exportHtml()").
  • All names should be written in English.
  • The terms get/set must be used where an attribute is accessed directly.
  • "is" prefix should be used for boolean variables and methods. In some cases, when this is more readable, "has", "can" or "should" can also be used as prefix.
  • Complement names must be used for complement entities. These include get/set, add/remove, create/destroy, start/stop, insert/delete, increment/decrement, old/new, begin/end, first/last, up/down, min/max, next/previous, old/new, open/close, show/hide, suspend/resume, etc.
  • Exception classes should be suffixed with Exception.

Recommendations

  • Usually class names are nouns and method names are verbs.
  • Generic variables should have the same name as their type.
  • Variables with a large scope should have long names, variables with a small scope can have short names. Scratch variables used for temporary storage or indices are best kept short. A programmer reading such variables should be able to assume that its value is not used outside a few lines of code. Common scratch variables for integers are i, j, k, m, n and for characters c and d.
  • The name of the object is implicit, and should be avoided in a method name. For example, use "line.getLength()" instead of "line.getLineLength()". The latter might seem natural in the class declaration, but proves superfluous in use, as shown in the example.
  • The term compute can be used in methods where something is computed.
  • The term find can be used in methods where something is looked up.
  • The term initialize can be used where an object or a concept is established.
  • Plural form should be used on names representing a collection of objects.
  • Negated boolean variable names must be avoided.
  • Default interface implementations can be prefixed by Default. However, if it is not expected that there will even be another implementation, it can be a lot more natural to suffix with "Impl" instead.
  • Singleton classes should return their sole instance through method getInstance, should have a private constructor and be declared final.
  • Functions (methods returning an object) should be named after what they return and procedures (void methods) after what they do.
  • Data transfer objects sometimes exist in two flavors, one which contains the Geomajas geometry dto's and one which contains JTS geometry objects. In that case, the variant with the geometry dto's should use the natural name, and the variant with JTS geometry objects should have a class name which has the "JG" suffix (JG stands for Jts Geometry).
Each file should have the correct copyright notice at the start of the file.
/*
 * This file is part of Geomajas, a component framework for building
 * rich Internet applications (RIA) with sophisticated capabilities for the
 * display, analysis and management of geographic information.
 * It is a building block that allows developers to add maps
 * and other geographic data capabilities to their web applications.
 *
 * Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * 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.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

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.

  • The copyright message should be at the top of the file. However, for js files, it is allowed to have the "dojo.provide" line above the copyright as this helps for debugging.
  • Each class and interface should have class comments indicating the purpose of the class.
  • Public methods should be commented if the meaning is not entirely clear from method and parameter names (is it ever?). When the method overrides or implements a method, then repeating the javadoc is not needed.
  • Comments in the code are recommended when they explain a block of code or when they explain why things are done in a certain way. Repeating the code in human readable wording is wasteful.
  • Use "@todo" comments to indicate shortcuts or hacks which should be fixed. Better still is just to do it right and not have the shortcut.
  • All comments should be written in English.
  • Comments should be indented relative to their position in the code.
  • Javadoc comments should be active, not descriptive (for exampe on method "getXxx()" the comment could be "Get xxx").

  • All classes and interfaces need javadoc class comments.

  • All classes and interfaces in the geomajas-api module need full javadoc comments on all methods.

  • All classes, interfaces and methods which have a "@Api" annotation needs a "@since" javadoc comment to indicate the version in which the class or method was added. This is also the case for methods which are added in classes with "@Api(allMethods = true)" annotation.

See the example below

/*
 * This file is part of Geomajas, a component framework for building
 * rich Internet applications (RIA) with sophisticated capabilities for the
 * display, analysis and management of geographic information.
 * It is a building block that allows developers to add maps
 * and other geographic data capabilities to their web applications.
 *
 * Copyright 2008-2010 Geosparc, http://www.geosparc.com, Belgium
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * 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.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

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);
    }
}
  • The code is written with the right margin at 120 characters and lines should not be longer than that if possible.
  • Tabs should be used for all indents. We assume a tab is four spaces for determining line length.
  • When lines are split because they are too long, a double indentation should be used.
  • Opening braces on the same line as the declaration/for/if..., so not aligned with the closing brace.
  • No spaces inside brackets.
  • Spaces around operators.
  • No wildcards allowed on import statements.
  • Always a space before braces.
  • Always use braces (and thus multiple lines) for if, while, do-while.
  • Array specifiers must be attached to the type not the variable.
  • Class variables should never be declared public.
  • Logical units within a block should be separated by one blank line.

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.

To assure the spring dependency injection is used, you should obtain beans through either injection (possibly autowiring) or the application context. When you directly instantiate classes which require spring dependency injection, you are likely to encounter NullPointerException or other problems.

@Component
public class MyClass {

    @Autowired
    private ApplicationContainer applicationContainer;

    public void myMethod() {
        Command command = applicationContext.getBean("controller.general.LogCommand", Command.class);
        .....

We recommend using the annotations when possible.

You cannot assume that (auto) wired services are initialized while the application context is being built. If you need to do some initialization of the bean state, this should be removed from the setters which are called while building the context, and moved to a post construct method.

@PostConstruct
private postConstruct() {
    // dome some stuff here
}

For servlets, you can use the GeomajasContextListener in the web.xml file.

<!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:/mypackage/shapeinmem/*.xml</param-value>
    </context-param>

    <listener>
         <listener-class>org.geomajas.dojo.server.servlet.GeomajasContextListener</listener-class>
    </listener>
    .....

The "contextConfigLocation" context-param allows you to specify additional application context definition files. These will be included after the built-in Geomajas file and the configuration which is contributed by the available plug-ins. You can include several files by separating them using whitespace. Each location can include the protocol/location used to find the file. When no protocol is specified, the file is searched on the class path. Ant-style wild cards can be used. The following are examples of allowed patterns:

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

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

When the GeomajasContextListener is used, the application context can be obtained in the servlet using

public void init(ServletConfig config) throws ServletException {
    ApplicationContext applicationContext = ApplicationContextUtil.getApplicationContext(config);
    .....

When using another way to define the application context, you have to make sure to include "org/geomajas/spring/geomajasContext.xml" (classpath resource, from the geomajas-impl module), and all the "META-INF/geomajasContext.xml" (classpath resource, configuration for the plug-ins).

Geomajas is an extensible frameworks which can be extended by including additional plug-ins on the class path when the application is started.

Some of the possible extensions include

  • adding security services.

  • providing specific rendering pipeline which modify the default rendering.

  • additional services which may be used (also by by other plug-ins), for example printing support.

  • a different face (in principle a face is just another plug-in, the term "face" is used when the plug-in produces data or makes data available to the outside world).

  • access to a kind of data store (these are referred to as "layer" plug-ins, they consume data).

Some conventions are in use to make plug-ins easily accessible and auto-register, and to make plug-ins good citizens of the Geomajas project.

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.


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:


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

The following sections need to be filled in:

  • description

  • scm

  • organization

  • mailinglists

  • licenses

  • issueManagement

  • ciManagement

  • developers

  • repositories

  • pluginRepositories

The build should also include the following settings

  • properties should contain "<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>".

  • the following compiler build plug-in declaration should be used:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
            <encoding>utf8</encoding>
            <source>1.5</source>
            <target>1.5</target>
        </configuration>
    </plugin>
  • The checkstyle plug-in should be activated, using the latest Geomajas style.

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-checkstyle-plugin</artifactId>
        <version>2.5-DF</version>
        <configuration>
            <configLocation>config/geomajas-checkstyle.xml</configLocation>
        </configuration>
        <executions>
            <execution>
                <phase>verify</phase>
                <goals>
                    <goal>check</goal>
                </goals>
            </execution>
        </executions>
        <dependencies>
            <dependency>
                <groupId>org.geomajas</groupId>
                <artifactId>geomajas-checkstyle</artifactId>
                <version>1.0.4</version>
            </dependency>
        </dependencies>
    </plugin>
    
  • A source jar should be produced.

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <version>2.1.2</version>
        <executions>
            <execution>
                <goals>
                    <goal>jar</goal>
                </goals>
                <configuration>
                    <includePom>true</includePom>
                </configuration>
            </execution>
        </executions>
    </plugin>
  • The jar should include indexes.

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
            <archive>
                <manifest>
                    <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
                </manifest>
                <manifestEntries>
                    <geomajas-version>${project.version}</geomajas-version>
                    <license>AGPLv3</license>
                    <more-info>http://www.geomajas.org/ and http://www.geosparc.com/</more-info>
                </manifestEntries>
                <compress>true</compress>
                <index>true</index>
            </archive>
        </configuration>
    </plugin>

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

To add a plug-in to the Geomajas project, you should write a proposal which is sent to the Geomajas developers mailing list (majas-dev). It will be discussed and once some kind of consensus seems to be reached, you can initiate a vote to allow creation of the plug-in. The vote should contain the following details

  • plug-in name

  • plug-in lead

  • general description

  • technical description

If the persons developing the plug-in don't have commit rights yet, they can get a directory in the sandbox (a part of our version control system) where they can prove their skills until they get full commit rights.

When the vote is accepted and commit rights are in place, the plug-in can be moved to trunk and a jira module and continuous integration can be set up. The module should also be added to the aggregate.sh file (which assures all documentation can be found in one place), and it should be added in the geomajas-dep pom (until the first release, it should be commented in that file).

To start the actual coding, we have provided a plug-in archetype which can be used using the following command line (to use the latest release):


Alternatively, you can use the very latest (snapshot) archetype using the following command.


You first have to select the archetype you want to build (geomajas-plugin-archetype). Then it will ask you the "groupId", "artifactId", version and base package. Once you confirmed the settings, the project will be created in a sub-directory with a name equalling the "artifactId" you choose.

A Geomajas plug-in has a "state" which indicates the maturity.

  • incubating : work-in-progress plug-in which has not reached graduation criteria yet.

  • graduated : the plug-in is considered stable, development is active and there is sufficient documentation to be usable and testing to prove it works.

  • retired : t he plug-in is no longer maintained. It can be deprecated or development just stopped for some reason. Both graduated and incubation plug-ins can become retired, so this does not give an indication of quality.

All plug-ins start at in the incubating state.

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:

  • A plug-in requires a maintainer. This is the contact-person for the plug-in. He should watch the mailing lists and be available for user questions.

  • All code should oblige to the programming rules as laid out in the Geomajas contributor guide (code style, javadoc, check-style, author tags, ...).

  • A check must be made to assure all dependencies of the plug-in have their licenses respected. Examples of issues to consider are compatibility of the license (with the AGPL license for the module) and possible copyright/license display requirements. All the relevant information needs to be supplied in the META-INF/geomajasContext.xml file for the plug-in.

  • If the plug-in is a face, the copyright information for all plug-ins needs to be included in the user interface (for example in an "about" box).

  • There must be enough documentation for users to easily start using the plug-in without having to ask the basic questions and the documentation needs to be in the expected location and format (to allow inclusion in project documentation).

  • There must be enough tests available to prove code stability.

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.

In order to create a new issue, you need to log in to the JIRA issue tracker.

When creating a new issue, the first thing you will be asked, is to select the project and issue type:

  • Project: the project you wish to report an issue for. (usually Geomajas)

  • Issue Type: the type of issue you want to report. Is it a bug, task or simply a question? Please be correct in this.

Then a new form appears with new fields to fill in. The summary and description have been discussed earlier. As for the other fields:

  • Priority: how urgent is the issue? This value can always be changed by the Geomajas committers if they feel that the priority does not match the issue's impact.

  • Due date: not used

  • Components: What component do you think the issue relates to? Not necessary to fill this in.

  • Affects version: In what version of Geomajas did you encounter the issue?

  • Assignee: Assign the issue to someone you believe is best suited to fix the issue.

  • The rest is not used.

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.

Eclipse project configurations can be generated using the maven Eclipse plug-in. This requires you to run the following command:

geomajas-trunk> mvn eclipse: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.

If you will be working with the GWT face, you may want to make use of the GWT Eclipse plug-in of Google. Detailed instructions can be found on the following site: http://code.google.com/eclipse/docs/download.html. We have experienced a problem with the project dependencies in Eclipse, which can be solved by running the gwt:eclipse goal of the GWT maven plug-in. This goal should be run the GWT project directory: geomajas-gwt-simple or geomajas-gwt-example (currently in development).

geomajas-gwt-simple> mvn gwt:eclipse

If you run this goal it will install the dependent libraries in the lib folder of the GWT war layout. Unfortunately, however, GWT does not allow Eclipse to automatically deploy in this folder.

After importing and building the GWT projects, make sure you convert them to GWT projects in the project properties dialog:


Check the "Use Google Web Toolkit" checkbox. The GWT SDK can be configured by clicking on the " Configure SDKs..." link. After configuration, you should now be able to run the project as a GWT Web application.

The Geomajas project consists of many pieces which each have their own release cycle. The most important parts are the back-end, faces and plug-ins. The example programs, documentation and and build tools also have individual release cycles.

This chapter tries to explain how to release any of these modules. The procedure is similar for all modules, but there are some specific checks to be done which only apply for certain parts.

As the releases are done to the Sonatype's nexus repository for open source projects (which is synced to Maven Central), the following references are a required read:

The basic procedure is very easy, for the part you want to release, execute the following two commands (using the next version as parameter, this will make you type less). These steps should be done in a clean location, it is best to do a fresh checkout.

  • mvn -DdevelopmentVersion=1.8.0-SNAPSHOT release:prepare

  • mvn release:perform

Before doing the release, you should update the version which is mentioned in the master.xml file (this version is displayed on the front page of the manual and is not automatically updated). After the release, this should be updated to the new development version.

At the end of the build, the src/main/resources/api.txt needs to be updated with the file which is put in target during the build (though the header at the top should remain, with the version updated.

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

Remember to comment the snapshot repository in all poms.

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.

When releasing the backend core, there may be a problem building the javadocs. The solution can be to do a local build of the backend using the next release version before doing the actual release.

When releasing the GWT face, make sure the dependency versions are correct in geomajas-gwt-archetype/src/main/resources/archetype-resources/pom.xml.

Close the staging repository (which makes the artifacts available for testing). When staging several parts, it is recommended to close each separately. This allows more fine-grained promotion and/or dropping of artifacts.

When staging is done and the repository closed, start a vote to allow users to test the new artifact.

When the vote failed, drop the repository. Development just continue and the version number is skipped. The release date in JIRA is actually the staging date.

When the vote was successful, promote the staged artifacts and announce the release, for the back-end, this requires the following steps:

  1. Upload zip files to sourceforge download area

  2. JIRA: Assure the next version exists, mark the current version as released agreeing to move open issue to the next version.

  3. For unstable release: install gwt-example for online trial

  4. For stable release: install all demo application for online trial

  5. Announce:

    • Build announcement message using the following template:

      title: Geomajas 1.5.0 technology preview/release candidate/stable released

      The Geomajas project is proud to release Geomajas 1.5.0, a technology preview showcasing the progress we are making towards our next stable build.

      The major advances in this version include (indicate major contributors when appropriate)

      • modularization of the system

      • introduction of a GWT face

      For the full list of changes, see http://jira.geomajas.org/jira/secure/ReleaseNote.jspa?version=10131&styleName=Html&projectId=10000&Create=Create

      Documentation for this release can be found at http://files.geomajas.org/maven/1.5.0/geomajas/userguide.html .

      Download links can be found at http://geomajas.org/release_1.5.0 .

      For the next release we plan to include the following features

      • absorb CO2 from the air to reduce global warming

      • remove need for system to be powered

      Please note that this is an unstable release, all the new features since the previous stable release may still change and we some new bugs may have been introduced.

      If you want to help us, join the discussions on the developer list, list bugs in jira and make feature requests in our fora. See http://www.geomajas.org/gis-development .

      Geomajas is the extensible open source web mapping framework, enabling integrated GIS solutions for businesses and government.

      Feel free to change wording and add useful content.

    • 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).

    • For a stable release, update the documentation page.

    • For a stable release, update Geomajas wikipedia page.

    • Send announcement to majas-dev (plain text).

    • Publish on general forum.

    • Create news item (without the "Geomajas is..." footer.

    • Send mail to jan.pote@geosparc.com to assure Geosparc is informed of the release.

In order for N.V. Geosparc (hereinafter “Geosparc”), a company under Belgian Law having its registered office at Gaston Crommenlaan 10, box 101, 9050, Gent, Belgium which is registered at the commercial register in Ghent, n° 0808.353.458, to have a clear understanding on the intellectual property rights associated with the Geomajas software library (hereinafter “Geomajas Project”) and to clearly determine the responsibilities and obligations associated with the Contributions (as defined hereinafter), Geosparc must receive a signed Geomajas Contributor License Agreement of the Contributor (as defined hereinafter) indicating that the Contributor agrees with the terms and conditions as defined hereunder. This Geomajas Contributor License Agreement (hereinafter “the Agreement”) intends to protect the Contributor as well as Geosparc.

Contributor hereby accepts and agrees to the following terms and conditions with regard to past, current and future Contributions submitted by Contributor to Geosparc, and has accepted the policy “Geomajas Contributions Policy”

  1. For the benefit of Geosparc, the Contributor hereby:

    1. irrevocably assigns, transfers and conveys to Geosparc all right, title and interest in and to the Contribution(s).  Such assignment includes copyrights (to the extent permitted by applicable mandatory law) and all other intellectual property rights other than patents and patent applications (“Patent”), together with all causes of actions accrued in favour for infringement thereof, recognized by any jurisdiction (“Proprietary Rights”).  Without limitation of the foregoing, Geosparc shall be entitled to determine in its sole discretion whether or not to use the Contribution(s) and to use, sell, distribute, license, re-produce, re-use, modify, update, edit or otherwise make available the Contribution(s) as it sees fit, in any manner currently known or in the future discovered and for any and all purposes;

    2. grants (to the extent that under applicable mandatory law, Proprietary Rights cannot be assigned, transferred or conveyed) to Geosparc and to the recipients of the software incorporating the Contribution(s) an irrevocable, worldwide, non-exclusive, fully paid-up and royalty-free copyright license to reproduce, modify, prepare derivative works of, (publicly) display, perform, sub license and distribute the Contribution(s);

    3. grants to Geosparc and to recipients of software distributed by Geosparc a worldwide, non-exclusive, fully paid-up, royalty-free, irrevocable (except as stated in this Agreement) Patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Contribution(s), where such license applies only to the Patent claims licensable by Contributor that are necessarily infringed by the Contributor’s Contribution(s) alone or by combination of such Contribution(s) with other work of Geosparc.  Contributor furthermore agrees to immediately notify Geosparc of any patents that Contributor knows or comes to know are likely infringed by the Contribution(s) and/or are not licensable by the Contributor. If any entity institutes patent litigation against the Contributor or any other entity (including a cross-claim or counterclaim in a lawsuit) alleging that Contributor’s Contribution(s) or the Geomajas Project work to which the Contributor has contributed constitutes direct or contributory patent infringement, then any Patent licenses granted under this Agreement for that Contribution or Geomajas Project work shall immediately terminate as of the date such litigation is filed.

  2. Upon the assignment of the Proprietary Rights and the grant of the license as set forth in this article 2, Geosparc hereby grants a non-exclusive, worldwide, fully-paid up, royalty-free license to make, use reproduce, distribute, modify and prepare derivative works based on the Contribution(s) of Contributor.

  3. Contributor hereby represents and warrants that:

    1. In the case that the Contributor is an individual who works in his/her own name the Contributor guarantees that he/she is legally entitled to assign the Proprietary Rights and to grant the above license.

    2. In the case that the Contributor is an employee the Contributor guarantees that he/she can legally represent the Company and is entitled to assign the Proprietary Rights and to grant the above license.

    3. In the case the Contributor is a Company and the Contributor’s employee(s) or consultant(s) have rights to intellectual property the Contributor warrants that its employee(s) has waived such rights;

    4. each Contribution is the original creation of the Contributor.  Contributor represents that each submission of a contribution includes complete details of any third-party license or other restrictions of which you are aware and which are associated with any part of the Contribution(s);

    5. no claim or dispute has been threatened or filed in connection with the ownership, use or distribution of the Contribution(s); and

    6. the execution of this Agreement does not constitute a breach under any other agreement to which Contributor and/or its employer is a party, does not require the consent, approval or waiver from or notice to any third party and does not violate any law or regulation.

    Contributor shall immediately inform Geosparc of any facts and/or circumstances of which Contributor becomes aware that would make the representations and warranties inaccurate or untrue in any respect.

    Contributor further agrees that Contributor shall at no time hereafter dispute, contest or aid or assist third party in disputing and/or contesting, either directly or indirectly, the right, title and interest in any and all Contributions of Geosparc as detailed in this Agreement.

  4. In case that under applicable mandatory law the Contributor retains the moral rights or other inalienable rights to the Contributions, the Contributor agrees not to exercise such rights without the prior written permission of Geosparc.

  5. In order to ensure that Geosparc will be able to acquire, use and protect its Proprietary Rights as detailed in this article 2, Contributor will (i) sign any documents to assist Geosparc in the documentation, perfection and enforcement of its rights, and (ii) provide Geosparc with support and reasonable access to information for applying, securing, protecting, perfecting and enforcing its rights.

  1. This Agreement shall enter into force upon execution of this document by Contributor.  This Agreement may be terminated by a party if the other party commits a breach of this Agreement provided that if the breach is capable of remedy termination shall not occur if the breach shall not have been remedied within 90 days of such other party having been given notice in writing specifying the breach and requiring it to be remedied.  The termination of this Agreement shall however remain in full force and effect with respect to any Contribution submitted prior to the termination date of the Agreement.

  2. This Agreement contains the entire agreement between the parties and supersedes all prior or contemporaneous agreements or understanding, whether written or oral, relating to its subject matter.  If any provision of this Agreement shall be deemed invalid or unenforceable, the validity and enforceability of the remaining provisions of this Agreement shall not be affected and such provision shall be deemed modified only to the extent necessary to make such provision consistent with applicable law.

  3. 4.3.The Agreement is governed by the laws of Belgium, without reference to its conflict of law principles.

  4. Geosparc shall have the right to assign its rights and obligations hereunder to any successor or assignee of its business or assets to which this Agreement relates, whether by merger, establishment of a legal entity, acquisition, operation of law or otherwise without the prior written consent of the Contributor.

Please execute (2) original copies of the above document and send this to the following recipient:

Address of recipient

Geosparc

Gaston Crommenlaan 10/101

BE-9050 Ghent

BELGIUM

The Contributor:

Name:

Title (if applicable in case of legal entity):

Full name of legal entity and address registered office (if applicable):

Date:

Signature:

The Company:

Name:

Title (if applicable in case of legal entity):

Full name of legal entity and address registered office (if applicable):

Date:

Signature:

N.V. Geosparc – Register N° BE 0808.353.458

The project use the nexus repository manager to store all Geomajas jars and all dependencies.

The following configuration can be used in your maven profile :

<repositories>
    <repository>
        <id>Geomajas</id>
        <name>Geomajas repository</name>
        <url>http://maven.geomajas.org/</url>
    </repository>

    <!-- uncomment if you want to use Geomajas snapshots, comment for faster builds  -->
    <repository>
        <id>Geomajas snapshots</id>
        <name>Geomajas repository</name>
        <url>http://maven.geomajas.org/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

If you do not need access to the snapshot releases, then it is recommended to remove that repository from your pom (it will make your compilation a little faster).

The Geomajas build has quite a few dependencies which are gathered from several repositories.

Our nexus instance functions as a proxy for the following repositories ;

  • maven central: http://repo1.maven.org/maven2/
  • java.net repo: http://download.java.net/maven/2/
  • jts4gwt: http://jts4gwt.sourceforge.net/maven/repository/
  • OSGeo: http://download.osgeo.org/webdav/geotools/
  • refractions: http://lists.refractions.net/m2
  • smartgwt: http://www.smartclient.com/maven2
  • spring milestones: http://repository.springsource.com/maven/bundles/milestone
  • spring releases: http://repository.springsource.com/maven/bundles/release
  • selenium: http://nexus.openqa.org/content/repositories/releases
  • selenium snapshots: http://nexus.openqa.org/content/repositories/snapshots
  • hibernate-spatial: http://www.hibernatespatial.org/repository
  • JBoss (a.o hibernate): https://repository.jboss.org/nexus/content/groups/public/