Developer FAQ

Frequently Asked Question for developers.

If you have a problem that is not described in this FAQ, please send a message to the mailing list dhis-dev@hisp.info (see the mailing lists page for more information).

Installing

How do I add environment variables?

On Windows XP:

• Right click on My Computer and select 'Properties'.
• Select the 'Advanced' tab and click on the 'Environment variables' button int he bottom of the dialog.
• Click on the relevant environment variable or the 'New' button and fill in the relevant values. System variables are available to all users of the system, while user variables are only available to the current user.

Any DOS or Cygwin windows must now be restarted for the changes to take effect.

On Linux/Cygwin

On Mac

• See the Environmental Variables setup guide

Back to the top.

Building the source code

How do I fix OutOfMemoryExceptions?

OutOfMemoryExceptions occur when Java fills up to much of your computer's memory with references to classes, reflections and objects. Java only has access to a part of your computer's memory, not all of it. So even if you have loads of memory, not all of it can be used by Java unless you explicitly assign more to it.

*TODO Need a reference to the exception text, PermGenSpace and so on*

The solution is to add an environment variable called MAVEN_OPTS, which contains the following:

-XX:MaxPermSize=128m -Xmx128m

This will increase the amount of memory available to Java and should eliminate the exception. If not, try increasing the numbers to for example 256. Be aware however, that you cannot and should not assign all available memory to Java.

See more information here:
http://www.hisp.info/archives/dev/msg01660.html

Back to the top

Running

Populator Error

If you get an error message like this when starting Jetty:

[INFO] Jetty server exiting.
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failure

Embedded error: Error creating bean with name 'org.hisp.dhis.populator.PopulatorEngine' defined in URL
[jar:file:/C:/HISP/Ny-source/trunk/dhis-2/dhis-web/dhis-web-portal/target/work/webapp/WEB-INF/lib/dhis-
populator-2.0-M6-SNAPSHOT.jar!/META-INF/dhis/beans.xml]: Initialization of bean failed; nested exception
is org.hisp.dhis.populator.PopulatorEngineException: Failed to use transactions

you are probably using the populator and a database at the same time.

Start by comment out the populator dependency in the pom.xml file in dhis-web. Rebuild dhis-web and dhis-web-portal with 'mvn clean install'.
If you still get the error message try to delete the dhis2 artifacts from the repository and rebuild everything(dhis-2, dhis-web and dhis-web-portal) with 'mvn clean install'.

If you want to use the in-memory database server, HSQLDB, remove or rename the hibernate.properties file in USER_HOME/dhis and restart Jetty.

I get Fatal Errors involving Log4J when running DHIS2

The exception you typically see, cut for brevity:

[INFO] [jetty:run-war]
[INFO] Configuring Jetty from the parameters.
[INFO] Starting Jetty...
[INFO]
----------------------------------------------------------------------------
[ERROR] FATAL ERROR
[INFO]
----------------------------------------------------------------------------
[INFO] null
org/apache/log4j/Category
[INFO]
...
Caused by: java.lang.NoClassDefFoundError: org/apache/log4j/Category
    at java.lang.Class.getDeclaredConstructors0(Native Method)
    at java.lang.Class.privateGetDeclaredConstructors(Class.java:2328)
    at java.lang.Class.getConstructor0(Class.java:2640)
    at java.lang.Class.getConstructor (Class.java:1629)
    at org.apache.commons.logging.impl.LogFactoryImpl.getLogConstructor(
LogFactoryImpl.java:410)

Explanation by Torgeir, from http://www.hisp.info/archives/dev/msg01754.html:
When DHIS 2.0 used commons-logging 1.0.4, we removed all dependencies
to log4j to avoid the conflict between commons-logging 1.0.4 and
log4j. But with this setup, we were unable to filter the log messages,
getting literally thousands of INFO messages printed to the terminal.
Now that we have changed to use commons-logging 1.1 in DHIS 2.0, we
can "re-enable" log4j and create log filters (this has been done).
This means that if commons-logging 1.0.4 would be used by the web
server or come as an indirect dependency from a new module or so, we
get the conflict back.

The easiest way to check if DHIS 2.0 is using commons-logging 1.0.4 is
to build all the modules in the right order (dhis-2, dhis-web,
dhis-web-portal) using the clean option (mvn clean install), and then
check this directory: dhis-web-portal/target/dhis/WEB-INF/lib. If you
find commons-logging 1.0.4 in this directory, then at least one of the
modules have a direct or indirect dependency to commons-logging 1.0.4.

The solutions are:
a) Only use commons-logging 1.1 (or later)
b) Remove all dependencies to log4j (you might have to delete log4j
from your local M2 repository too)

Back to the top

Miscellaneous

How do I get the system quickly filled with data?

To do this, you just need to uncomment the dhis-populator dependency in trunk/dhis-2/dhis-web/pom.xml. The resulting part of the file should then look like this:

<dependencies>
    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-populator</artifactId>
      <version>2.0-M6-SNAPSHOT</version>
    </dependency>
  </dependencies>

Rebuild dhis-web with 'mvn clean install'.

Back to the top

Where is the Subversion configuration file?

The file is named config and can be found here:

Back to the top

How do I upgrade from Webwork 2.1 to 2.2?

DHIS 2 has changed from Webwork 2.1 to Webwork 2.2. All necessary changes has been done in the trunk, but if you have your own branch or module follow these steps to make the changes: Upgrading Branches to use WebWork 2.2.

Back to the top