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.
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 two options. Once in the geomajas-gwt-simple directory, you can run the application in development mode using
mvn gwt:run
Due to classpath problems and the gwt-maven-plugin which does not properly handle excluded dependencies (the "provided" scope), this can fail on some systems.
Alternatively you can run the actual war using
mvn jetty:run-war
It can be advisable to run "mvn clean" between "gwt:run" and "jetty:run-war" or the classpath problem from the previous footnote may appear again.
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.
The Geomajas project has a very strong API contract. To assure the project adheres to this contract, we have the following requirements;
No API classes or interfaces may be removed.
No API classes or interfaces may be renamed.
No API classes or interfaces may have their package name modified.
No API methods may be removed.
No API methods may have their signature changed.
No methods may be added to classes annotated using
"@
".UserImplemented
Each class on which a "@Api" annotation is added should have a "@since" javadoc comment.
Each method on which a "@Api" annotation is added should have a "@since" javadoc comment.
Each public method which is added in a class which is annotated with "@Api(allMethods = true)", should have a "@since" javadoc comment.
The checkstyle configuration which is used for the project (which is defined in the geomajas-parent parent) tries to check the API contract. This required a api.txt file in src/main/resources which contains the API for the previous release version. The API for the compiled version is put in target/api.txt.
Note that apart from the class and method signatures, the behaviour
should also remain constant (especially when documented or tested). Just
keep a method and throwing NotImplementedException
cannot be
considered "maintaining a stable API".
Version have a major.minor.patch structure.
New committers need to sign an agreement which hands over copyright to Geosparc. Policies are needed for assigning commit rights (see below).
All SVN commits should include the JIRA issue number at the start of the commit message, and a short description of the work done. The JIRA issue number allows linking the commits with the issues (as can be seen in JIRA), the short message allows persons to know what is happening without referring to JIRA. The only times JIRA issue number are not needed is for making "obvious" changes like fixing typos.
Commits should be grouped by issue as much as possible/sensible (better two commits than one commit for fixing two issues, better one commit of five files than five commits of one file (for one issue)).
Development of the "latest-and-greatest" version happens in "trunk".
Continued development on earlier versions (when not "latest-and-greatest") occur in branches with the future version number as name.
When a release is cut, a tag with the release version as name is created. The release should be built from the tagged files.
After each commit, the system should still compile and all test cases should still succeed. There is a continuous integration engine (Hudson) which verifies this and send messages to the commit mailing list on failures.
Note that details about coding style and naming are on the coding style page.
When inserting debug statements, parameterized messages should
be used to prevent the need/usefulness of
isDebugEnabled()
.
private final Logger log = LoggerFactory.getLogger( ContainingClassName.class );
log level | default on | use |
---|---|---|
ERROR | yes | major problems, should always be visible in logs and are likely to require action from a person (to fix the condition or assure it does not happen again). Indicates that something is seriously wrong. |
WARN | yes | warning about potential problems. Should always be visible in logs and a person will probably need to assess whether this is harmless or should be treated as an error. |
INFO | yes | important information. You can assume this level is on in production, so it should be carefully considered whether this level is appropriate. In general only used to indicate service status (started, stopped). |
DEBUG | no | logging information which is detailed enough to know what is happening in the system, without flooding the logs. |
TRACE | no | very detailed logging, probably only making sense to the developer of the code. |
Table 1.1. logging levels
Unit testing: At least each class implementing the public API should have a unit test, testing all methods. For testing JUnit is used.
Capturing a JIRA bug report in a reproducible manner.
The test will automatically be run when running "mvn
install
".
*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.
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
Recommendations
/* * 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.
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.
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 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); } }
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 }
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 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.
<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-2010 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>
Example 4.1. Plug-in declaration in geomajasContext.xml
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>
Example 4.2. geomajasWebContext.xml for ResourceController
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.
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.
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):
mvn archetype:generate -DarchetypeCatalog=http://apps.geomajas.org/nexus/content/groups/released/
Example 4.3. Create project using GWT Maven archetype
Alternatively, you can use the very latest (snapshot) archetype using the following command.
mvn archetype:generate -DarchetypeCatalog=http://apps.geomajas.org/nexus/content/groups/latest/
Example 4.4. Create project using GWT Maven archetype
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.
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:
The more crowded an issue is, the more likely is it that some problems may get lost over time.
Different problems are likely to be handled by different people. The more problems you put into the issue, the more difficult is this issue to handle for all involved parties.
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.
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:
Tortoise SVN: an excellent SVN client for Windows (http://tortoisesvn.tigris.org/)
Subversive: Eclipse plug-in, can be found on the following Eclipse update site ( http://download.eclipse.org/releases/galileo > Collaboration Tools)
Subclipse: Eclipse plug-in, can be found on the following Eclipse update site ( http://subclipse.tigris.org/update_1.6.x)
IDEA SVN plug-in (part of the default IDEA installation)
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 multimodule maven projects:
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.
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 setup in IntelliJ IDEA is quite straightforward and does not require running a separate maven command. Make sure you use the maven import wizard to open your project, it can be activated from the File menu "Open project" and selectthe root pom.xml file.
Developing with the GWT face will require you to install the latest version of IntelliJ IDEA (9.0) as this is the only version that supports GWT 2.0. The IDE will recognize the GWT projects and assign the correct facet but as always you will have to make your own run configuration (which is fortunately trivial).
Depending on the actual IDEA version, 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 and debug the project. Note that this setting is needed for each of the GWT modules you want to be able to run.
If you are working with another IDE or not using an IDE, it is always possible to run the example projects directly from maven. For the Dojo face (geomajas-dojo-simple and geomajas-dojo-example-war) the maven command is as follows:
geomajas-dojo-simple>
mvn jetty:run
This command will start up the Jetty servlet engine, after which you can connect to the process for debugging.
In a GWT project, you should run the following goal:
geomajas-gwt-simple>
mvn gwt:debug
This will start up GWT development mode, debugging should also be possible here.
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:
Upload zip files to sourceforge download area
JIRA: Assure the next version exists, mark the current version as released agreeing to move open issue to the next version.
For unstable release: install gwt-example for online trial
For stable release: install all demo application for online trial
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”
When used in this Agreement the following words and or expressions shall have the meaning as stated hereunder unless the context expressly requires otherwise:
“Contributor” means 1/ any individual and/or legal entity that voluntarily submits (a) Contribution(s) to the Geomajas Project or 2/ any individual legally representing his/her Company.
“Contribution” means any original work, including any modification and/or addition to the existing work that is submitted for introduction in, or documentation of, any of the products owned or managed by Geosparc, where such work originates from a Contributor. A Contribution may be submitted in any form of electronic, verbal and/or written communication or documentation, including without limitation, communication on electronic mailing lists, source code control systems and issue tracking systems that are managed by or on behalf of Geosparc for the purpose of discussion and improving the results of the Geomajas Project.
For the benefit of Geosparc, the Contributor hereby:
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;
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);
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.
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.
Contributor hereby represents and warrants that:
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.
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.
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;
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);
no claim or dispute has been threatened or filed in connection with the ownership, use or distribution of the Contribution(s); and
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.
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.
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.
EXCEPT FOR THE EXPRESS WARRANTIES DETAILED IN ARTICLE 2, THE CONTRIBUTION(S) ARE PROVIDED “AS IS” AND NEITHER CONTRIBUTOR NOR THE Geosparc MAKES ANY WARRANTIES OF ANY KIND TO THE OTHER PARTY, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION OF ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
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.
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.
4.3.The Agreement is governed by the laws of Belgium, without reference to its conflict of law principles.
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 ;