JMCS (Java Mariotti Common Software) is a collection of APIs and jar files shared by all JMMC Java GUI applications (SearchCal, ModelFitting, ...). Its goal is to centralize all shared functionalities (e.g menubar handling, about box window, ...) in order to provide our final users with more consistent, feature-reach, desktop-class applications across all 3 main execution platforms that are Linux, Mac OS X and Windows.

Its DOXYGEN documentation is also available for implementation details.

This page lists and describes each JMCS main functionalities:

App : the main class from which JMCS-based applications all derive

This class aim is to handle applications life cycle, normalized in 3 steps : intialization, execution and destruction.

For your application to benefit from JMCS, your main class shall derive from the App class, and thus implement each of its abstract methods : init() and execute() :

• Your init() method shall contain all your application initialization code, like specific command-line option parsing, MVC objects allocation and initialization, GUI setup, ...
• Your exec() method shall contain no code at all in fact, as long as your application GUI fully implement the reflex approach (e.g Observer/Observable and MVC patterns, ...) and has already been initialized in init().
• Furthermore, you can also provide your own finish() method to appropriately handle your application life cycle end.

When instantiated at execution in your main() method, your App-derived class will automatically bring your application to life by:

1. Initializing App internal mecanisms (ApplicationData.xml file parsing, shared logger setup, command line option parsing, shared functionalities setup) when calling super(...).
2. Displaying a Splash screen (for at least 2 seconds), in order to let the end user know which application is about to start.
3. Calling your init() method to fully setup your application GUI.
4. Discarding the Splash screen, in order to let your GUI as the frontmost window.
5. Calling your exec() method at last.

Here is a minimal JMCS-compliant application template

import fr.jmmc.mcs.gui.*;
public class Main extends App {
    public Main(String[] args) {
        super(args);
    }

    protected void init(String[] args) {
        // Add your application initialization code here...
    }

    protected void execute() {
        // Add your application execution code here...
    }

    public static void main(String[] args) {
        new Main(args);
    }
}

Application data : how they are stored and used

All the data concerning your application shall be stored in an XML file (named ApplicationData.xml) in your application package at the same level as your main class. This file will be automatically loaded when your main class is instantiated. It contains information about :

• Your application name and version number
• Your application dependencies
• Your application menubar structure
• Your application change log
• Your application acknowledgement

Here is a minimal ApplicationData.xml template

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.myProgram.com/">
    <program name="MyProgram" version="1.1.02"/>
    <compilation date="11/04/2008" compiler="g++-4.1"/>
    <text>This is a description of MyProgram to be shown in the About box.</text>
    <dependences>
        <package name="Castor" description="A librairie which permits to generate Java classes from XSD schema." link="http://www.castor.org/"/>
    </dependences>
    <menubar>
        <menu label="Plot">
            <menu label="Run" classpath="fr.jmmc.mcs.modjava.Actions" action="mfaction1" accelerator="shift R" description="run the plot"/>
        </menu>
    </menubar>
    <releasenotes>
        <release version="1.0">
            <prerelease version="1.0b1" tag="MPV1_0b1">
                <change>Added Run menu</change>
            </prerelease>
        </release>
    </releasenotes>
    <acknowledgment>
        <![CDATA[This research has made use of the \texttt{MyProgram} service of the Jean-Mariotti Centre\footnote{Available at http://www.jmmc.fr}]]>
    </acknowledgment>
</ApplicationData>

Splash screen : the window automatically shown while applications launch

A splash screen window is automatically during application initialization. It display the JMMC logo, the application name and version number, and the copyright statement.

About box : the window giving application detailled information to end user

An about box window is freely provided and linked to the appropriate menu item. It contains the JMMC logo, the application name and version number, customizable description text, a standard invite to use acknowledgement in end user publication, and a list of your application dependencies if provided.

Menu bar : default handled menu items and how to provide application specific ones

An already populated menu bar is provided, which basic functionalities like:

• A File menu, with the mandatory Quit menu item that automatically queries your finish() method (if implemented) to ensure whether the application shall exit or not.
• An Edit menu, with freely provided Cut, Copy and Paste items.
• An Help menu, with:
  • A User Manual entry, if your application packaged contains the needed documentation format (automatically disabled otherwise).
  • A way for the end user to provide feedback to JMMC using a simple dedicated window.
  • A way for the end user to put your application acknowledgement notice in his clipboard for later pasting in his publication (a default acknowledgment notice is automatically generated in case you didn't provide a specific one).
  • A way for the end user to get access to your application release note if you provided those information in the ApplicationData.xml file.
  • A way for the end user to acces your application FAQ webpage through his computer default Web browser.

All those default menus can of course be extended with your own menu items using :

• ApplicationData.xml to describe your menu items (standard, checkbox, sub-menu, separator, text description, linked Action).
• RegisteredAction : your actions shall derive from this class in order to be automatically linked (using ActionRegistrar in the background, a singleton class dedicated to keeping track of all your application actions linked (or not) to menu items) to your menu items.

Another benefit (apart from getting all the previously described functionalities for 'free') of using our menu bar infrastructure is to transparently handle different hosting platform specificities (e.g Mac OS X).

Preferences : standardized preference file location and version handling

Your preference data handling class shall derive from our Preferences class. You will then get the following benefits:

• Freely provided saveToFile() method, handling automatic serialization of your preferenced values.
• Automatic preference file loading from end user expected (host operating system specific) default location, by just providing the preference filename through getPreferenceFilename() (shall be in the form of "fr.jmmc.YourApplicationName").
• Automatic fallback to default values if no preference file already exists, by mandatory using setDefaultPreferences() to define each of your application default values and keys.
• Automatic preference file versioning handling, by using getPreferencesVersionNumber() : each time you change your preference file structure (preference keys, value units, ...) you change the returned int and provide the corresponding conversion code in your updatePreferencesVersion() method to handle this automatically for the end user (so the user doesn't loose any prior settings while upgrading your application regularly).

The following data types can be used as values : String, Boolean, Int, Float and Color objects. Each preferenced values shall be identified using unique string keys in the form of "abc.def.foo.bar". Preference related to a same preference group (e.g "abc.def.foo.LOW", "abc.def.foo.MEDIUM", "abc.def.foo.HIGH") can be ordered through a specified integer index.

Help : how to harness the shared LATEX-based help browser

Feedback report : how bug and user remarks are routed bak to the JMMC team

Logging facilities : how you should handle execution traces in your application

Here is the code you should add to each of your classes to use standard java logging facilities.

import java.util.logging.*;
public class Complex {
    /** Logger */
    private static final Logger _logger = Logger.getLogger(Complex.class.getName());
    ...
}

Relase notes : how they are automatically generated

Acknowledgement : how to provide a specific one for each application

Application website : where are applications main webpage and FAQ

Status bar : a way to display undergoing processes state to end user

Window centere : a way to center windows on complex end user screen setup

Shared libraries : list of available third party toolkits

-- SylvainLafrasse - 30 Oct 2008