Skip to content
This repository was archived by the owner on Jan 16, 2024. It is now read-only.

Developers Guide

Jump to bottom
dyazbek-intersect edited this page Sep 26, 2012 · 13 revisions

This document gives an overview of the system for future developers including those who may wish to reuse the application and/or contribute changes.

Setting Up Your Local Environment

Set up for Java and Eclipse

Install Oracle JDK 1.6 on your target platform.

Install Ant on your target platform.

ExSite9 makes heavy use of Eclipse Rich Client Platform (RCP) distributed with Eclipse Indigo (v3.7.2). Install the 'Eclipse Classic' bundle of Eclipse Indigo - as this bundle includes features required to build RCP functionality: http://www.eclipse.org/downloads/packages/eclipse-classic-372/indigosr2

Setup an environment variable named ECLIPSE_HOME to point to the root of your Eclipse installation. This is required for the ExSite9 build scripts.

To build cross-platform releases of ExSite9, the Eclipse Deltapack must also be installed for Eclipse Indigo v3.7.2 from http://download.eclipse.org/eclipse/downloads/drops/R-3.7.2-201202080800/

Open Eclipse and 'Import Existing Projects' and point at the root of your exsite9 source tree. Import the following projects:

  • 3rdParty - Provides a place to keep JARs used by exsite9.
  • exsite9 - Contains the eclipse RCP plug-in that is exsite9.
  • exsite9 Libraries - Contains links to JARs in 3rdParty used by the exsite9 plugin. This was necessary because Eclipse RCP does not like to mix JARs into a plugin.
  • pde-build - Contains build scripts capable of building exsite9 cross-platforms.

Setup symlinks in your Eclipse directory for files required while running/debugging ExSite9.

cd $ECLIPSE_HOME
ln -s <exsite9 home>/exsite9/rootfiles/schemas .
cd $ECLISPE_HOME/configuration
ln -s <exsite9 home>/exsite9/rootfiles/configuration/log4j.xml .
ln -s <exsite9 home>/exsite9/rootfiles/configuration/ExSite9MetadataSchema.rng .
ln -s <exsite9 home>/exsite9/rootfiles/configuration/fieldsOfResearch.sql .

Launch ExSite9 in RUN or DEBUG modes by setting up a 'Eclipse Application' run configuration pointing to the product: au.org.intersect.exsite9.product

Key Components

  • Eclipse RCP is used to provide a cross-platform UI development kit which builds ontop of the SWT UI toolkit.
  • rcptoolbox is used to provide field validation in Eclipse RCP wizards.
  • HSQLDB is used as the database.
  • EclipseLink is used to provide ORM via JPA.
  • Google Guava provides many useful utility classes.
  • Jing is used to validate XML against RelaxNG formatted XML Schemas
  • Apache Commons Compress is used to build ZIP files since the standard JDK zip utilities do not support extremely large zip files.
  • Apache Commons IO is used to read/write files.
  • Apache Commons lang provides many useful utility classes.
  • Apache Commons logging provides logging capability to EclipseLink.
  • Apache Log4j provides logging capability to ExSite9.
  • JUnit provides unit test capabilities.
  • Mockito provides capabilities to mock interfaces/classes in unit tests.
  • Cobertura provides code coverage metrics.

Build ExSite9

Developer Build

The developer build compiles code, runs unit tests and produces unit test & coverage reports but does not build the cross-platform ExSite9 Eclipse RCP Application.

cd <exsite9 home>/exsite9
ant -f dev-build.xml

Reports can be found in <exsite9 home>/exsite9/build

Official Build

The official build builds dependent modules, compiles code and builds the cross-platform ExSite9 Eclipse RCP applications. A number of steps are involved:

First, build the "libraries" module

cd <exsite9 home>/exsite9_libraries
ant

Next, build the "exsite9" plugin module

cd <exsite9 home>/exsite9
ant -f pde-build.jar

Next, build the cross-platform ExSite9 RCP applications

cd <exsite9 home>/pde-build
ant

Output is built to <exsite9 home>/pde-build/build/I.Exsite9

Navigating The Code

<exsite9 home>/exsite9 contains all the ExSite9 application code. Java packages have been named to advertise their contents.

ExSite9 employs standard Eclipse RCP framework practices in order to operate. plugin.xml holds the whole application together.

  • UI components and menu items are bound to Commands which are triggered when a user wants to do something.
  • Commands have Handlers which are executed in response to a user triggering a command. The package au.org.intersect.exsite9.commands.handlers contains all the handlers.
  • Handlers may employ Wizards which are used to get input from the user. The package au.org.intersect.exsite9.wizard contains all the wizard UI definitions.
  • Once data has been obtained and an action is to be performed, the command handler will use a Service to perform the action. The package au.org.intersect.exsite9.service contains Services and their interfaces.
  • Services employ Data Access Objects (DAOs) to manipulate the database. The package au.org.intersect.exsite9.dao contains DAOs.
  • Data Access Objects use the JPA Entity Manager to read/write the database.
  • The package au.org.intersect.exsite9.domain contains all ExSite9 domain object/jpa entity classes.
  • The UI Views are contained in the package au.org.intersect.exsite9.view
  • The package au.org.intersect.exsite9.xml contains classes responsible for reading/writing XML.
  • The package au.org.intersect.exsite9.zip contains classes for building ZIP files.

Guide For Contributing

We welcome any contributions to the code base. Please send us a pull request with your changes. Any changes should have accompanying tests, and the full test suite should be passing.

Clone this wiki locally