How to create a Maven project

This does not take into account the current module structure with dhis-services

This tutorial explains how to set up a development project using Maven. Refer to the various resources under Development environment and tools > Maven for more information.

We begin by describing what Maven is and what it can do for you. We then proceed to describe a basic Maven project structure. Finally we give a rundown of the most useful Maven commands, with special focus on their usage in DHIS 2.

Step X: Determine where to place your project

In the DHIS 2 Subversion repository, there are two directories you might want to consider.

incubator/- Projects that are meant to one day become a part of DHIS 2. This is probably where you want to start
sandbox/ - Projects for testing and playing with code. Code in this directory is usually not merged into DHIS 2 later.

Later, when your project is somewhat finished, it may be moved into the trunk/ or the the trunk/local/ directories. These directories are reserved for completed projects that are deemed to be good enough be part of a release. Once they are moved, they are usually maintained in these directories.

Step X: Create your project directory

A Maven project is simply any directory which contains a POM-file and a specific directory structure. When creating a project inside DHIS 2, you should name it according to the following convention:

For non-web projects: dhis-modulename
For example: dhis-populator

For web projects: dhis-web-modulename
For example: dhis-web-datamart

In some cases, you are making a specific implementation of a part of the API, then the name should be suffixed with the implementation type.
For example, if you are making a Hibernate implementation of something, the project should be called

dhis-modulename-hibernate

Step X: Create a Maven directory structure

The project directory should contain the following directories:

src/
|-main/
| |-java/
| |-resources/
|-test
| |-java/
| |-resources/

In Linux use the command mkdir -p src/{main,test}/{java,resources} to create all these directories in one go.

If your project is a web project, it should also contain the following directories:

src/
|-main/
| |-webapp/
| | |-dhis-web-modulename/
| | | |-javascript/ (optional)
| | | |-style/ (optional)
| | |-WEB-INF
| | | |-web.xml

The reason for the dhis-web-modulename directory is because of the Web Portal later on.

dhis-web-modulename/ should contain your Velocity templates
javascript/ should contain your javascript (*.js) files.
style/ should contain your CSS (.css) files.
WEB-INF/ need only contain a web.xml file.

Define web.xml

The web.xml file describes your web application to a servlet container, i.e. Jetty or Tomcat.

Use the following template

To be added

Step x: Make a project descriptor (POM) file

The POM file describes your module and any dependencies it needs. Use the following two templates to as a basis, and replace whatever is applicable:

Template for non-web projects

To be added

Template for web projects

<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  
  <parent>
    <groupId>org.hisp.dhis</groupId>
    <artifactId>dhis-web</artifactId>
    <version>2.0-M8-SNAPSHOT</version>
  </parent>
  
  <artifactId>dhis-web-modulename</artifactId>
  <packaging>war</packaging>
  <name>DHIS Module Name</name>
  
  <build>
    <finalName>dhis-web-dataentry</finalName>
  </build>
  
  <dependencies>
    <! -- Your dependencies go here -->
  </dependencies>
</project>

Replace those elements which are applicable. Choose a descriptive name. The project's artifactId and finalName should be the same as the name of the project directory, i.e. dhis-modulename or dhis-web-modulename.

Maven projects can inherit configuration from other projects. This is defined through the parent element. If your project is a web project, you probably want it to inherit dhis-web. This will give you access to common functionality and relevant dependencies from that project.
The version element of the parent declaration should be the latest version of the parent.

Determine your dependencies

Which projects should your project use or depend on? In many cases you want to use other DHIS 2 modules, i.e. the Core module or the DataProvider module. You can also define dependencies to external libraries, such as commons-collections, xstream, webwork, and so on.

In your POM file, depdencies are defined inside the dependencies element. Use the following template:

<dependency>
      <groupId></groupId>
      <artifactId></artifactId>
      <version></version>
    </dependency>

When you inherit from a parent, this parent may already define a set of dependencies as part of it's dependency management. Look for the dependencyManagement element in the parent project's POM file. In these cases, you don't have to define a version element in your dependency, because this will be taken from the dependency management of the parent.

Use the following template:

<dependency>
      <groupId></groupId>
      <artifactId></artifactId>
    </dependency>

Define your package structure

You need to decide which packages to use. The convention is to use org.hisp.dhis.modulename as a base package. You should put these packages into your src/main/java/ directory. This is done automatically in Eclipse by creating a new class under the java/ dir, and defining a package name for the class.

Some conventions for package names:

For Hibernate implementations: org.hisp.dhis.modulename.hibernate
For WebWork actions: org.hisp.dhis.modulename.action

This text will assume you've chosen org.hisp.dhis.modulename as a package name.

Step x: Add Spring beans in your application

Create the following directory and file:

src/
|-main/
| |-resources/
| | |-META-INF/
| | | | |-dhis/
| | | | | |-beans.xml

Use the following template for defining your beans.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

  <! -- Your beans go here -->

</beans>

Each bean should have an id and a class. Furthermore, it can have a series of properties. Each property refers to a property of the class being instantiated. A property is any object variable with a public set method. I.e., if you want to initialize a class Message with the message "Hello world", you'd do this:

<bean id="messageBean"
        class="org.hisp.dhis.message.Message">
      <property name="message"
          value="Hello world"/>
    </bean>

In DHIS 2 you most often want to map up more complex beans from your classes.

Mapping Action classes

Step x: Add internationalization (i18n) to your project

i18n files should be placed in the following directory:

src/
|-main/
| |-resources/
| | |-org
| | | |-hisp
| | | | |-dhis
| | | | | |-modulename

In that directory there must be one file called i18n_module_properties.properties. This file defines the basic i18n-keys and the default fallback text if translations are not available.

Additionally, you can add language specific files on the form i18n_module_lang_COUNTRY.properties. For example:

UK English: i18n_module_en_GB.properties
Vietnamese: i18n_module_vi_VN.properties
Hindi (India): i18n_module_hi_IN.properties
Norwegian: i18n_module_no_NO.properties

Each file contains a set of keys and translations. The keys and their translations are separated by '='. In keys, you should replace spaces with underscore '_', for example no_organisationunits_selected.

Example:

To be added

And a translation file:

To be added

Step x: Enable you project in the DHIS 2 build cycle

Step x: Enable your web module in the DHIS Web Portal

Why use Maven?

Maven is a project management tool created by the Apache Foundation. It's used to build (i.e compile and prepare) software projects. This can be a complex task as a project may make use of several external libraries and because you need to manage the classpath of the project. It is common to create a JAR-file of your project, which requires that you put stuff in the right place. You can do all this manually, of course, but using a build tool will greatly simplify the process. Maven is very similar to an older application, Ant.

These are some of the things Maven can do for you:

Manage your build cycle
Manage your dependencies
Separate source code from compiled code
Automate the running of tests
Generate reports from the build process

Dependencies and dependency management

Your project can make use of lots of external libraries of code. In this case you'll often have to include JARs of these libraries in your project. In other words, you project depends on other projects. Maven calls these external libraries or projects dependencies and gives you a clean and easy way of managing them.

Doing this manually means finding the the relevant libraries, downloading the JAR files, putting the files in the right place in your code, and finally building the code. If you want to update to a new version of the library, you'll have to repeat the process and put the new JAR file into your project.

Maven does this automatically. You specify the name and the version of a dependency, and Maven download this from a central repository of JAR-files.

Maven project structure

A Maven project is any directory which conforms to a particular structure and contains a special file called pom.xml. POM stands for Project Object Model. This is an XML file in Maven's own format. More on that later.

Directory structure

When making a Maven project, you should create a directory wich has the same name as your project. For example, when creating a project called Bicycle, you should create a directory called "bicycle". Inside this directory you'll need several directories which will contain different parts of your project.

The following is an overview of the directories you'll need

src/
- main/
  - java/
  - resources/
  - (webapp/)
- test/
  - java/
  - resources/

Tip: In Linux use mkdir -p src/{main,test}/{java,resources} to create all these directories in one go.

The src/ directory is the root directory for your source code. No compiled code or JAR files should go into this directory.

The src/ directory contains two directories main/ and test/. The first directory will contain the source code of your project, while test/ will contain the source code for your test cases.

Both src/main/ and src/test have two subdirectories, java/ and resources/. The java/ directory will contain all your .java files. resources/ is a somewhat special directory which may contain configuration files, resource files, mappings and the like.

When you build your project, Maven will go through all these directories, pull out the various files, compile Java files, and merge them into a JAR file for your project. Compiled code will be put into the target/ directory. You should never change anything in this directory manually.

Why this separation? By making your source code and compiled code separate, it's easier to work with source code management systems like Subversion and CVS. The binary files will often change with each compile, and all these changes shoulnd't be stored in a code repository.