Jomic Developer Guide

$Date: 2011-07-30 06:53:44 +0200 (Sat, 30 Jul 2011) $

Table of Contents

Setting things up
Checking out the Subversion repository
Installing additional build tools and libraries
Setting up the workcopy
Building and running the application
Using Ant
Using the command line
Using Eclipse
Notes on Web Start
Notes on Debian
Design, architecture and implementation
Design considerations
Architecture overview
Representing comics
Working with the code
Porting to additional platforms
Porting to non-Java-1.4 platforms
Coding guidelines
Adding a new language
Introduction to Java localization
Maintaining an existing language
Submitting a language
Working with the documentation
Editing text documents
Editing images and figures
Release checklist

This article describes how you can get started with the Jomic source code in order to contribute to it. In particular, it explains how to setup your development environment.

The jomic-developers mailing list is the preferred place to discuss issues related to development.

To contact me directly, use my SourceForge user page.

The source code is stored in a Subversion (SVN) repository. Subversion is an open source tool for version management of files. There are many tools to access information stored in repositories. This section explains how to do it using the command line client or Eclipse. For more information on Subversion, start at

Jomic is developed using Eclipse, an open source IDE available from The current version as of this writing is 3.2.2, which does not have built-in support for Subversion. Instead, you need a plug-in such as Subclipse. Once setup, perform the following steps to sync the Jomic project from the repository:

  1. Start Eclipse.

  2. Use FileNewOther....

  3. Select the wizard SVNCheckout projects from SVN.

  4. Enable "Create new a repository location". Click "Next".

  5. Set "Url" to "". Click "Next".

  6. Select the folder to be checked out: "trunk/jomic". Click "Finish".

Once the checkout is complete, the project most likely contains compile errors. Refer to the section on building and running the application using eclipse on how to fix them.

The repository already contains almost everything you need to build Jomic, including Java libraries, DTDs, DocBook transformations and so on.

In order to create every target of the build process, you need a couple of tools:

You can omit some of these if for instance you do not want to build the documentation or Windows installer.

After syncing with the repositoy, the easiest way to build the application is using ant, available from All required external JARs are already available in $JOMIC_HOME/lib.

  • To create an initial build, run ant jomic.jar jomic-test.jar jomic-help.jar.

  • To run the application with the (official, utterly boring) standard test comic, use ant run.

  • To get a list what else you can do with ant, use ant -projecthelp .

If you did not obtain the source code using the Eclipse SVN wizard, you first have to import it as a project in Eclipse:

Most likely you will get some compile errors, which will be fixed with the following steps:

To run the test suite from the command line, run ant test. Depending on the speed of your machine, this might take a few minutes to complete. Watch the terminal for test results.

To create a test coverag report, run ant coverage. The report ends up in $JOMIC_HOME/site/coverage/index.html and summarizes which part of the code have not been executed during the tests.

Some background: Jomic's tests use the popular JUnit framework, for details see GUI testing is based on Jemmy, for details see The coverage report is the result of Emma, for details see

To add your own tests, simply extend Junit's TestCase as usual. Take a look at TestTools, it features some methods to easily obtain test data, in particular, comic archives. For GUI tests, extend JomicApplicationTestCase and implement your own runTest(). For a simple example on how to do this, see MenuGoTest.

Speaking in terms of Java packages, Jomic is organized this way:

Jomic uses the popular model-view-controller pattern. The most important players in this respect are ComicModel, ComicView, and JomicFrame. The first two are explained in more detail below, the naming already should make their roles obvious.

JomicFrame is the controller. It listens for commands, which it receives via stock Swing ActionEvents.

Commands can be assigned to menu items, keys, toolbar buttons and so on. A list of possible commands understood by JomicFrame can be found in Commands. Many of these commands change the state of the CommicView, for example the page number or the way it displays the current page.

Internally, comics are represented by a ComicModel. This is a pretty simple class that mostly contains a collection of ComicImage.

ComicImage again is pretty simple and wraps a single image extracted from the comic book archive. It mostly contains methods to query certain properties of the image, such as getWidth(), getHeight(), or hasError(). A particular interesting one is isDoublePage(): it decides if the image contains one or two pages. This is important for properly rendering the comic if the user enabled ViewShow Two Pages.

ComicViewis a JPanel capable of visualizing a ComicModel. It has to deal with three problems:

Mapping page numbers is relatively simple: if the ComicImage.isDoublePage() is false, increase the current page number by one. If it is true, increase the page number by two. Internally, page numbers go from 0 to ComicView.getPageCount() - 1. For the user, page numbers range from 1 to ComicView.getPageCount(). So some care has to be taken to increment page numbers displayed to the user, and decrement page numbers specified by the user. Nevertheless, all this is no rocket science.

Deciding whether to show one or two images is a lot more difficult. ComicSheet helps with that: a sheet holds one or two images using the rules listed below. Figure 1, “Deciding whether to show one or two images” shows examples for applications of these rules.

  1. The first image has it own sheet, because it is the front page (ComicSheet 0).

  2. If ComicImage.isDoublePage() is true, the image has its own sheet (ComicSheet 2 and 5).

  3. If the last image starts at a new sheet, it has its own sheet (ComicSheet 6).

  4. If the first image of a sheet is a single page image, but the next image is a double page image, it has its own sheet because the next image would not fit anymore (ComicSheet 4).

To render the images, Jomic uses a rather ugly approach. While Sun released a powerful library for imaging (JAI), they could not get their act together and include a Swing component with it that actually allows to display such an image. Still, they included the undocumented On the long run, this is no satisfactory solutiuon. One of the JAI examples containes IconJAI, which displays a JAI image in an Icon. A bugfixed and cleaned up version of it can be found in

To make things easier for everyone involved, you should follow the following guidelines. If you don't, life goes on, but probably someone else will have to fix the issues later.

  1. Before submitting a patch or commiting a change, run ant reformat. This reformats the code according to the project formatting style. The result is a formatting conforming to the Sun guidelines, with the exception that lines can be 100 characters long (because the disco era is long past).

  2. From time to time, run ant checkstyle. This creates a report that checks the code for various stylistic issues, and generates a report in $JOMIC_HOME/site/checkstyle-report.html. CheckStyle issue open at the time of the last release are available from

    If you are using Eclipse, you can also perform these checks while typing: simple install the eclipse CheckStyle plugin and import $JOMIC_HOME/settings/checkstyle.xml.

    The checks are based on the default "Sun Checks", with some modifications to make the code easier to maintain and make it harder to shoot yourself in the foot. If you come from a C/C++ background, you might hate it. If you ever coded in Eiffel, there is nothing new here.

  3. Use meaningful names, avoid the need for comments. CheckStyle lets you omit almost all comments with the following exceptions:

    1. All classes must have a comment shortly describing what the class represents (and not what it "does")

    2. All packages must have a package.html. It should contain at least one short sentence summarizing the contents of the package. As a template, use $JOMIC_HOME/xml/package.html.

    3. Document open issues, known bugs/limitations and unclean solutions with todo comments, for example:

      // TODO: use HashMap instead of array

      Do not use the undocumented (but popular) @todo.

      Run ant todo to get a report about all todo comments found in $JOMIC_HOME/site/todo-report.html. Todo comments open at the time of the last release are available from

  4. If you declare new exceptions, make them extend RuntimeException, never use Exception. I mean it.

  5. Use abbrevations only if you save at least 4 letters. "dir" for directory is ok, "src" for source is braindead.

  6. Funtions and loops must have 1 exit only. Use "return" only as last statement of a method. Do not use "break" at all; instead, use for example a "while" loops with state variable to abort it, and give the state variable a meaningful name such as cancelled.

  7. Due performance considerations, all calls to logger.debug() and must be wrapped inside an

    if (logger.isXXXEnabled()) {...};

    logger.warn/error/fatal() won't need this.

  8. Clearly mark non-portable code with

    // TODO: fix portability

    Also consider adding some notes in the section on " Porting to additional platforms".

Some parts of Jomic are localized and ready to be translated to other languages. The implementation uses the usual machanisms provided by Java. This section gives a overview on how to work with them, and how to add support for additonal languages. For more details on Java localization, start with the internationalization thread in the Java Tutorial.

To add another language, perform the following steps:

  1. Download the most current bundle.propertiesfrom:*checkout*/jomic/trunk/jomic/source/net/sf/jomic/tools/

  2. Copy it to bundle_*.properties, where "*" stands for the ISO language code you want to translate to. For example, "de" means German.

  3. Change the English text snipplets right of the "=" to a text that means the same in your language.

The loalized texts are stored in property files which are loaded in Java ResourceBundles during runtime. The default file with the English texts is called, files for other languages are named bundle_*.properties, where "*" stands for a 2-letter language code, and an optional 2-letter country code, separated with an underscore (_). For example, a bundle storing generic German texts would be called A bundle with German texts with taking specialities of Austria into account would be called

You can find theses files in the repository at /jomic/source/net/sf/common/bundle*.properties. You can browse this directory using the Subversion web interface at To download the most current version of a file, click its name and, on the resulting page, on the first link named "download" near the top. In most cases, you will only need the English

The structure of these files is very simple: they consist of lines of the pattern "key = value", where key is the abstract name of the text snipplet under which it will be looked up by Jomic, for example "buttons.cancel". Value is the actual (language dependent) text to use in the user interface, for example, "Cancel" in English or "Abbrechen" in German.

For the above example, the file contains this line:


The file defines the same key, but assigns a different value to it:


The "de" is the ISO-639 language code for German as specified. For other languages, see

If a Java application is running with the locale set to "de", it attempty to resolve any localization keys by looking them up in If it cannot find the key there, is also looks it up in This is nice because you will get something leggible on the screen if a single key is missing from the properties file. This is also a bit confusing because parts of the application will use different languages.

Once you created or updated a bundle*.propertiesfile, you can submit it for inclusion in future releases of Jomic. The preferred way is to use the SourceForge patch tracker:

  1. Open the patch tracker at

  2. Click "Submit new"

  3. In the form, set category to "Localization".

  4. Enter a summary, for example "Japanese Localization"

  5. Enable the checkmark right to the text "Check to Upload and Attach a File"

  6. Click the "Browse" button, and select your file (for example

  7. Enter a description, for exampe "Japanese Localization".

  8. Click the "Submit" button.

Using the tracker makes sure that everybody knows which localizations are currently worked on, and avoids duplicate effort. However, if you really can not figure out the patch tracker, you can also email your file to me.

The documentation is stored in $JOMIC_HOME/site/. Most of it is written in DocBook XML, a set of tags for describing books, articles, and other prose documents, particularly technical documentation. For more information about DocBook, see for example, in particular Using DocBook/XSL, the DocBook source can be transformed into other formats such as XHTML, PDF, or JavaHelp. For details about DocBook/XSL, see

In practice, this is not all that complicated as most of the stuff is already setup to "just work" by using some simple ant rules. The only thing you need to install first ist tidy, a tool to check, fix, and reformat HTML, XHTML, and XML (and thus DocBook) files. It is available from

Now you can edit the source documents, and create the documentation with ant:

  • Edit $JOMIC_HOME/site/user-guide.xml, and run ant user-guide to update the user guide in $JOMIC_HOME/site/user-guide.html

  • Edit $JOMIC_HOME/site/developer-guide.xml, and run ant developer-guide to update the developer guide in $JOMIC_HOME/site/developer-guide.html

  • Edit $JOMIC_HOME/site/index.xml, and run ant site-index to update your local copy of the homepage in $JOMIC_HOME/site/index.html

I'm not aware of any useful and free DocBook editor, so I suggest you use an XML editor, for example JEdit with its XML plugin, available from This at least gives you syntax coloring.

Releasing a new version for Jomic comes down to the following steps: