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 class : 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 deriving from App. This file will be automatically loaded when your main class is instantiated. It contains information about :

• Your application name and version number (mandatory).
• Your application release and change log (mandatory).
• Your application menubar structure (optionnal, as standard ones are automatically provided).
• Your application dependencies (optional).
• Your application acknowledgement (optional).

Please note that if your package does not contain this file, a default one will be used instead to ensure degraded execution mode.

Here is a minimal ApplicationData.xml template:

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.jmmc.fr/myprogram"> <!-- URL to the application main webpage -->
    <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> <!-- can be empty -->
    <releasenotes>
        <release version="1.0">
            <prerelease version="1.0b1" tag="MPV1_0b1">
                <change>First release !</change>
            </prerelease>
        </release>
    </releasenotes>
</ApplicationData>

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.

Here is an example of menu items creation :

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.myProgram.com/">
    ...
    <menubar>
        <menu label="File"> <!-- Extending File menu -->
            <menu label="Import" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1" icon="fr/jmmc/test/import.png"/>
            <menu label="Export" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1"/>
        </menu>
        <menu label="Menu 1">
            <menu label="Item 1" classpath="fr.jmmc.mcs.modjava.Actions" action="mfaction1" accelerator="shift T" description="Raccourcis n-1 de Model fitting"/>
            <menu/> <!-- menu separator -->
            <menu label="Item 2" checkbox="true" classpath="fr.jmmc.mcs.modjava.Actions" action="mfaction5"/> <!-- checkbox item -->
        </menu>
        <menu label="Menu 2">
            <menu label="Item 1" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1"/> <!-- sub-menus -->
                <menu label="Item 1.1" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1"/>
                    <menu label="Item 1.1.1" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1"/>
                    <menu label="Item 1.1.2" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1" accelerator="I" checkbox="true"/> <!-- mixing styles -->
                </menu>
                <menu label="SearchCal 12" classpath="fr.jmmc.mcs.modjava.Actions" action="scaction1" accelerator="I"/>
            </menu>
        </menu>
    </menubar>
    ...
</ApplicationData>

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).

Relase notes : how they are automatically generated

Data from ApplicationData.xml are used to automatically generate release notes in HTML and RSS format when your application is deployed.

Here is an example of detailed release and change notes:

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.myProgram.com/">
    ...
    <releasenotes>
        <release version="1.1">
            <prerelease version="1.1b2" tag="MPV1_1b2">
                <change type="BUGFIX" id="foo/14" url="http://mariotti.fr/gnats?cmd=view%20audit-trail&database=JMMC-SW&pr=15">fixed bla menu bug</change>
                <change type="CHANGE"> moved bla menu</change>
            </prerelease>
            <prerelease version="1.1b1" tag="MPV1_1b1">
                <change type="FEATURE">Added bla menu</change>
                <change type="REQUEST">Speeded up algorithm</change>
            </prerelease>
        </release>
        <release version="1.0">
            <prerelease version="1.0b1" tag="MPV1_0b1">
                <change>First release !!!</change>
            </prerelease>
        </release>
    </releasenotes>
    ...
</ApplicationData>

Dependencies : how they are displayed in the About box

Here is an example of detailed dependencies:

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.myProgram.com/">
    ...
   <dependences>
        <package name="AppleJavaExtensions" description="toolkit to provide better user interface on Mac, provided by Apple, Inc." link="http://developer.apple.com/samplecode/AppleJavaExtensions/index.html"/>
        <package name="SAVOT" description="SearchCal uses source code created at the Centre de Donnees astronomiques de Strasbourg, France."/>
   </dependences>
    ...
</ApplicationData>

Acknowledgement : how to provide a specific one for each application

Here is an example of acknowledgement note:

<?xml version="1.0" encoding="UTF-8"?>
<ApplicationData link="http://www.myProgram.com/">
    ...
    <acknowledgment>
        <![CDATA[@INPROCEEDINGS{2008SPIE.7013E..44T,
   author = {{Tallon-Bosc}, I. and {Tallon}, M. and {Thi{\'e}baut}, E. and 
   {B{\'e}chet}, C. and {Mella}, G. and {Lafrasse}, S. and {Chesneau}, O. and 
   {Domiciano de Souza}, A. and {Duvert}, G. and {Mourard}, D. and 
   {Petrov}, R. and {Vannier}, M.},
    title = "{LITpro: a model fitting software for optical interferometry}",
booktitle = {Society of Photo-Optical Instrumentation Engineers (SPIE) Conference Series},
     year = 2008,
   series = {Presented at the Society of Photo-Optical Instrumentation Engineers (SPIE) Conference},
   volume = 7013,
    month = jul,
      doi = {10.1117/12.788871},
   adsurl = {http://cdsads.u-strasbg.fr/abs/2008SPIE.7013E..44T},
  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}]]>
   </acknowledgment>
    ...
</ApplicationData>

Application website : where are applications main webpage and FAQ

Each application in production shall be accessible on the JMMC website (e.g http://www.jmmc.fr/applicationname for the ApplicationName app).

Here is a typical file tree of a deployed application:

/home/users/lafrasse/public_html/SearchCal/
|-- ApplicationRelease.xml
|-- SearchCal.jar
|-- SearchCal.jnlp
|-- SearchCalContrib.jnlp
|-- applicationReleaseToRss.xsl
|-- index.htm
|-- jar
|   |-- Jmcs.jar
|   |-- activation.jar
|   |-- axis-ant.jar
|   |-- axis.jar
|   |-- cds.savot.common.jar
|   |-- cds.savot.model.jar
|   |-- cds.savot.pull.jar
|   |-- cds.savot.sax.jar
|   |-- cds.savot.writer.jar
|   |-- commons-discovery-0.2.jar
|   |-- jaxrpc.jar
|   |-- kxml2-min.jar
|   |-- log4j-1.2.8.jar
|   |-- mail.jar
|   |-- saaj.jar
|   |-- sclgui.jar
|   `-- wsdl4j-1.5.1.jar
|-- releasenotes.htm
|-- releasenotes.rss
`-- setDateOfReleases.xsl

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.

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 values shall be identified using an unique string key, in the form of "abc.def.foo.bar". Values 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.

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

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

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

Status bar : a way to display ongoing process state to end user

You can use StatusBar to discreetly provide the end user with ongoing process status feedback, by simply adding an instance of this class (that extends JPanel) to your main window's bottom.

You can then set its message from anywhere in your application with StatusBar.show("Insert your message here..."); .

Window centerer : a way to center windows on complex screen setup

You can use the WindowCenterer singleton to simply center a given Window on the main screen of an end user complex screen setup (e.g multiple monitor system).

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

End user can easily give us feedback using our dedicated window available form the standard help menu. This facility collects, in addition to the user mail, feedback type and comment, the execution platform description, any exception stack traces, and logged traces if any (this is why it is important that you follow our logging conventions).

All those collected informations are then automatically sent to our web-based feedback system. Our PHP script then formats all the received data, and transmits it to our user support team for further examination. Please note that an automated "Thank you" mail (with a unique feedback ID for later tracking if needed) is also sent back to the contributing end user if he provided his mail address.

Help window : how to harness the shared HTML-based help browser

Shared libraries : list of embedded usable third-party toolkits

-- SylvainLafrasse - 30 Oct 2008