Workspace 2.0

Table of Contents

The Pre-requisites

• Eclipse for Java Developers 3.7 (Indigo). You might need to add -vm option to eclipse.ini file to point to a JDK e.g -vm C:\dev\java\jdk1.6.0_17\bin\javaw.exe see eclipse.ini wiki page.

NOTE: The "Eclipse for JavaEE" download package does not include the M2E Maven Integration for Eclipse as the Eclipse "for Java" distribution does (in Indigo at least) - so you would have to install M2E manually from http://www.eclipse.org/m2e/ with other packages.

The How-to-use-it? New Workspace Quick Start Guide

These screencasts walk through the quick start process:

1. setup
2. features

Also ~andrewx991's YouTube Channel has a series of very nice & useful screencasts how to set-up a development environment for Mifos!

Here are step-by-step instructions on how to use the new Mifos Workspace 2.0:

1. clone the mifos head repository, as per Mifos Version Control Guide
2. On the very first use of the new workspace (only), you'll need to do an mvn install in the (new) mifos-reporting-libs Maven module, either via mvn CLI in the reporting-libs directory or in mifos-report-libs project in Eclipse launch the mvn install launch configuration, to get the BIRT JARs which are not available on Maven central into your local Maven repo.
3. If you have any existing projects, switch to an entirely new, clean workspace using File -> Switch Workspace.
4. in your Eclipse IDE, menu File → Import... → Maven, Existing Maven Projects
   1. Select root directory, Browse to where your git tree is
   2. Select All projects - there should be (at the time of writing this) about 16 of them (correctly set-up Eclipse .project & .classpath for all of them are in Git)
   3. do NOT check Copy projects into workspace (it's off/unchecked by default already)
5. optional: In order to separate this set of projects from other projects in the workspace, it is best to use Eclipse working sets. Do this if you didn't Switch to a brand-new Workspace (above).
   1. in the Eclipse Package Explorer view, click that little downwards face (options) arrow icon
      1. change the Top Level Elements from Projects to Working Sets
      2. use Configure Working Sets to add a New... one named e.g. "Mifos", and Add → the mifos-* projects to its Working set content
   2. or, drag & drop the 16 or so mifos-* projects into/under the Working Set (unless during the creating of the working set already)
   3. or, it's possible to already do this directly during the Import > Existing Projects into Workspace wizard
6. optional: connect eGit by marking all projects, right-clicking, Team > Share Project, Git, highlight/mark/check all the projects lines (they'll all have "Repository" column to '../.git', that's correct), Finish.
7. if there is anything in red, do an F5 refresh of all the mifos-* projects
8. if there are any "this or that JAR not found" issues in red, try right-click Maven > Update Dependencies (must have M2Eclipse installed)
   1. NEVER use right-click Maven > Update Project Configuration (revert and go back to the one in Git if you do so by mistake) - this would break the workspace, see Workspace 2.0 Eclipse Maven Settings
9. make sure there are no red build errors on all mifos-* projects anymore
10. start-up the Mifos web application via the e.g. Mifos START 8080.launch Eclipse launch configuration in the mifos-server project by right-clicking Debug As... (Starting directly as debug makes hot code replacement work)
11. Mifos web application is now available at e.g. http://localhost:8080/mifos/ (make sure you don't by mistake use or copy/paste http://0.0.0.0:8080/mifos, as printed in the start-up logs INFO org.eclipse.jetty.util.log WebApp@25468780 at http://0.0.0.0:8080/mifos and INFO org.eclipse.jetty.util.log Started SocketConnector@0.0.0.0:8080)

No mvn CLI build step is (normally) needed to get the Workspace 2.0 to build, and run the web application, in the IDE (contrary to the "old" workspace).

No Project > Clean > Clean (all) projects action is (normally) needed to get the Workspace 2.0 to build, and run the web application. A simply refresh (F5) of the mifos-* projects may however be needed e.g. after a CLI (non-eGit) git checkout... branch switch, to trigger an as-needed Eclipse incremental rebuild (unless you have Window > Preferences, General > Workspace, [X] Refresh automatically enabled).

PS: The order of projects within an Eclipse working set can unfortunately not be manually sorted in Eclipse (it would be nice if this could reflect the layering/build order); the only way would be appropriate e.g. numeric project name prefixes (but the existing standard convention of using artifactId may be better). - You can however move the Working Sets themselves up & down (Mifos vs. other sets of projects you have in your workspace).

Pro Tip: instant reloading of message bundles

Developers: set i18.messages.cacheSeconds=1 in your Local Properties File for instant reloading of i18n messages! See MIFOS-4557    for details.

Coding Standards for Java Source Code Formatting

In order to be able to use Source Format to apply the Mifos Coding Standards, the following step must be done, only once per new workspace:

Got to Window (or Eclipse on Mac OS X), Preferences..., Java > Code Style > Formatter, Import... the eclipse-formatter-mifos-profile.xml file found at the Mifos root directory, and make sure that Active Profile is "Mifos".

In the Workspace 2.0 this is now a "Workspace Setting", and no longer settings specific to a Project; so Project Properties > Java Code Style > Formatter must NOT have "project specific settings" enabled, but use workspace settings (which is the case in the mifos projects configuration as found in Git).

Developer Setup has further (non-Workspace 2.0 related) Eclipse Workspace Preferences which must be set.

The How-its-done? Mifos Workspace 2.0 Technical set-up details

MIFOS-4099    sub-tasks has some information which may be of "historical interest" re. how it all came about.

Servlet 3.0 - src/main/resources/META-INF/resources & META-INF/resources inside JARs in WEB-INF/lib of a WAR

TBD

Lightweight Maven-oriented fully classpath-centric Jetty-based embedded server

TBD

Jetty, and Jetty versions

Jetty is very easy to embedd, and is very well-suited for the approach of having the entire webapp in the classpath, without a physical WAR directory layout.

Version 7 of Jetty is used instead of a Jetty v8. Jetty v7 turns out to actually support (what we need of) Servlet 3.0 already, is stable, and ready as container for deployments. Jetty v8 (the next version of Jetty, which will officially support the Servlet 3.0 API) isn’t yet available as GA at the time of writing this. It should be simple to switch the workspace embedded Jetty to v8 later.

Due to MIFOS-4768   , min. Jetty v7.3.0 must be used to deploy a mifos.war; previous versions (7.2.0 and 7.2.2) cause soe ClassCircularityError in BIRT.

Note that we are not actually using the Servlet 3.0 API - only the META-INF/resources feature. Compiling against a Servlet 3.0 JAR and using that API will only be possible with Jetty 8.

WAR

Tomcat 7.0 & other containers

Nothing in Mifos is specific to Jetty, it’s all Servlet 3.0 standard-based. While for reasons of using the same servlet container in development, acceptance tests and production the plan would be to shift everything to Jetty, the Mifos WAR should still be able to be deployed into any Servlet 3.0-compliant container, e.g. Tomcat v7 (but only version 7, because Tomcat v6 didn’t do Servlet 3.0 yet).

New Maven modules

mifos-war (war/) vs. mifos-webapp (mifos-application?) (application/)

TBD, incl. assembly

mifos-reporting (reporting/) - BIRT

The new mifos-reporting (reporting/) module contains all things BIRT Reporting related. Because the BIRT JARs are not available on a public Maven repository, but we want to have a fully Maven-based everything-is-on-the-classpath via M2E and "normal" Maven-based build, the new mifos-reporting-libs (reporting-libs/) module installs the (some) BIRT JARs into your local repository.

BTW, did you know that Mifos has been using OSGi for quite a while already? BIRT actually internally uses OSGi, and via some classloader tricks in a WAR starts up an embedded OSGi container. That's what all the stuff in mifos-reporting/src/main/resources/META-INF/resources/WEB-INF/platform is for; the many *.jar under mifos-reporting/src/main/resources/META-INF/resources/WEB-INF/platform/plugins are not on the Maven-based classpath - BIRT finds and sets-up all that via the servlet context when it starts up.

MIFOS-4429        has blurb that may be of interest if you want the full background.

Maven & Eclipse (M2E)

Please see Workspace 2.0 Eclipse Maven Settings sub-page for details on the Maven & Eclipse integration specific points of the Mifos new Workspace 2.0.

The Why?

TBD

"Classpath honesty A" - Minimal Classpath

In the old workspace, because all dependencies of all modules were on the classpath of the one and only Ecilpse project, it was possible (in Eclipse) to create wrong dependencies, which would only get caught during the CLI Maven build. In the New Workspace, all projects have their exact Maven pom.xml defined dependencies on their classpath.

This is INVALUABLE if we want to do refactorings between modules for further modularity (e.g. reduce the application module) !

"Classpath honesty B" - Complete Classpath

In the old workspace, the full Mifos application running in WTP actually had MORE libraries on it's classpath than in both the Eclipse-based workspace and during the CLI Maven build - the BIRT JARs were copied "manually" (by a resource copy in the application/pom.xml) into WEB-INF/lib - but were never part of the Maven dependencies.

In theory, those libraries could have led to conflicts with the real Maven dependency imported library (suppose e.g. Mifos wanted to also use Axis, which BIRT also uses).

In the new workspace, the BIRT JARs are normal Maven dependencies (those that will end up in WEB-INF/lib at least; the BIRT OSGi part explained in the mifos-reporting module section above which brings along further dependencies is not; and that's correct because those end up on a different Classloader, not seen by Mifos).

The Future / Next Steps?

java -jar mifos.war

An "Executable WAR" allowing to start Mifos, e.g. for test servers or demos, simply via java -jar mifos.war, will be possible based on the work done here; see MIFOS-4919.

Modularity

Further modularity work could be started based on this project, including:

• splitting acceptance tests into the respective functional modules?
• menu playability - e.g. the reporting UI (menu) could move from the mifos-webapp (mifos-application?) into mifos-reporting? Somehow (org.mifos.framework.components.mifosmenu).
• inverting dependencies; application shouldn’t depend on questionaire/cashflow/savings anymore? New core module? Those should be new modules depending only on api - droppable into WEB-INF/lib? New war would “package” them - we could have several WAR packges - optional modules...
• splitting DB SQL into the respective functional modules (harder) ??