Enhance Module Maven Archetype (Design Page)

Background

OpenMRS is built on an extensible architecture. Anyone can create a Modules to add new functionality. A module is able to add new pages, add database tables, modify data, etc. The problem is that the startup time for developers is sometimes prohibitive. See the Creating Your First Module wiki page for the current process.
We recently switched from using ant to build projects to maven. With maven you can create "wizards" or what they call archetypes. The archetype should ask the developer a few simple questions (eg module name, module id, etc) then create the module folder and file project hierarchy with all the right names.

By the time GSOC starts, there will probably be a very basic maven archetype written. See the TRUNK-1733 ticket for more on that. (TODO: link to wiki page for basic archetype when it is completed)

A great example to look at as far as short startup time is the Atlassian SDK for some of their projects. Its as easy as downloading a zip file from them and running one maven command. This command runs a wizard to walk you through creating the the atlassian plugin + running the atlassian project with that plugin already installed and running.  Note that this SDK is an end goal for all of OpenMRS, not for this archetype project. This archetype will potentially be one piece of the larger SDK goal.

Purpose

The purpose of this is to speed up developer startup time when creating modules. Creating a module is currently a laborious process that includes a lot of file renaming and copy/pasting from other module templates. A maven wizard (archetype) that walked a user through creating the different types of modules to create and naming things correctly would help to at least speed up the initial creation time.

Domain Expert(s) / User(s)

• @Matthew Blanchette (Maven expert)

• @Former user (Deleted) (Original author of basic openmrs module maven archetype)

• @Jeremy Keiper (user with ideas about what should go in the wizard/archetype)

Required/Preferred Skills

• Java

• XML

• Maven

• Velocity

Design

The archetype should not be IDE dependent.  Use the maven command line tools / execution of the wizard/archetype to do the different types of functions.

There is no need for extra OS dependent scripts.  The wiki page about this archetype should tell the user the different options/flags/mavenmodules for how to do the different options.

A utopia would be that someone could simply run "mvn module:module" (or some better maven goal and target name) and the archetype wizard asks them what to name the module, their username, etc, etc, if they want a service, if they want an admin link, etc.  The module id/user name/etc data goes into the config.xml file.  See the current basic archetype for an example of that. The output is a module filestructure with all those things in it.

A bonus would be able to run them separately so that someone could run that on an already-built module to add in a service, eg.

Objectives

The archetype should allow for multiple

1. Wizard/archetype that asks developers for the basic module info:

   1. Module name, module id, module package, module description

   2. See the basicmodule for the barebones filestructure that a module needs.

2. Wizard should ask dev if they want to create a service/serviceimpl/dao/hibernatedao

   1. See the https://github.com/OpenMRS/openmrs-module-example-jsp-and-service for a module that has the service files added (warning: not mavenized)

3. Wizard should ask dev if they want an admin page link and what that link should be named

   1. See the extension point in config.xml: https://github.com/OpenMRS/openmrs-module-htmlformentry/tree/master/omod/src/main/resources/config.xml

   2. And the class that it points to: https://github.com/OpenMRS/openmrs-module-htmlformentry/tree/master/api/src/main/java/org/openmrs/module/formentry/extension/html/FormEntryAdminExt.java

4. Wizard should ask dev if they want to add some example annotation driven mvc pages

   1. See https://github.com/OpenMRS/openmrs-module-example-spring-mvc-annotation for web controllers that are annotated instead of xml-based (warning: not mavenized)

5. Wiki page describing all aspects of the archetype and how a module developer would use it

6. Wiki page describing how to update the maven archetype if/when the module structure changes or a new wizard option is needed.

Extra Credit

1. Turn this archetype into one part of an "OpenMRS Module SDK" (see paragraph in Background section about Atlassian SDK)

   1. Create a downloadable (or git check-out-able) package that allows the user to walk through the archetype/wizard and then jetty:run openmrs

   2. There will need to be a maven archetype or some other function that is able to install the openmrs module into the newly running openmrs automatically

Project Plan

• Creating a basic archetype.

  • Includes bare bone structure of basic module.

  • Asking basic parameters such as, module name, id, package, description.

• Discussion of above basic structure with mentors.

• Further improvement of the archetype.

• Implementation of archetype and including Add-on's such as

  • Service / ServiceImpl

  • DAO / Hibernate DAO

  • Links to admin page

  • Annotation-driven MVC pages

• Documentation

  • Technical documentation

    • How to update the maven archetype if/when the module structure changes or a new option is needed.

  • User documentation

    • Detailed steps in working with archetype wizard on wiki page.

• Implementation of this archetype to Open-Mrs developers, mentors and fellow interns for testing purpose.

• Gathering the suggestions and improvising the project and wiki description.

• Implementation of above features into an "OpenMRS Module SDK"

Timeline

Resources

• Guide to creating archetypes

• http://svn.openmrs.org/openmrs-contrib/maven/archetypes/openmrs-archetype-module/trunk/

• TRUNK-1733

• Atassian SDK