Distro Tools Maven Plugin

This Maven plugin provides support for OpenMRS based distributions. Such=
distributions typically bundle a lot of content (metadata, concepts, forms=
, reports) with their code and this plugin seeks to help developers more ea=
sily manage that content.

Background

A common challenge for distributions (or any module that bundles metadat=
a) is referencing metadata objects, of which a large distribution will have=
many. The OpenMRS API provides several options which have their own streng=
ths and weaknesses:

Database id (all metadata classes)

Pros: succinct...

Cons: not portable between different databases

Name (some metadata classes can be fetched by name, e.=
g. EncounterType, Program etc)

Pros: human readable

Cons: the primary purpose of name is for display in the UI layer so it =
might be changed

UUID (all metadata classes)

Pros: guaranteed to be globally unique and unchanging

Cons: not human readable

Reference term (so far just Concept but s=
oon also Drug)

Pros: can be human readable if descriptive text is used (debatable=
whether this is a good practice)

Cons: not guaranteed unique and small performance hit due to extra=
database table joins

There also may be several places in the distribution where references to=
database objects exist. For example one might reference metadata objects i=
n:

For a large distribution it can be difficult to keep all those reference=
s in consistent and there is no way of knowing at build time whether refere=
nces are correct, e.g. you don't know if a reference term used in an HTML f=
orm is correct until you open that form on a real system.

Solution

This project seeks to provide a new unified way of referencing metadata.=
The general principles are:

There should be one central place for metadata references whic=
h is accessible throughout the distribution

There should be more validation of metadata references at build time

The implementation borrows ideas from the Android SDK w=
hich generates some Java sources based on resource descriptions in XML file=
s. It leverages Maven's resource filtering system to resolve metadata refer=
ences in non-Java files.

The input metadata reference lists have a simple format and should be pl=
aced in api/src/main/distro/metadata. For example the contents of =
a simple concepts.xml might look like:

Which means distribution resource files can reference the concepts as ${metadata.concept.YES} and ${metadata.concept.NO}. At build time those will be replaced with the corresponding concept U=
UIDs. For example if you are using the UI Framework to localize metadata na=
mes then your messages.properties file can now include something l=
ike: