ModuleInformation and the ModuleUtil

ModuleInformation is meant to answer some of the short-comings of the java.lang.Package implementation. Package depends on the information contained in the jar file, whereas ModuleInformation allows you to package multiple components in one jar but still keep separate information for each one.

ModuleInformation Basics

You can specify and retrieve ModuleInformation just by including a module information XML file in your jar. Then, ModuleUtil will load the XML file and then return an initialized ModuleInformation object containing the module information contained in the XML file.

For instance, say you have a "foobar" component or module. You just need to put the following in the root of your source tree:

module-foobar.xml:
<module id="foobar">
    <name>Foobar</name>
    <description><![CDATA[This is the Foobar component]]></description>
    <version>1.1.0</version>
</module>

There are a set of standard properties looked for in a module file, and the ModuleInformation supports them as first-level fields. Any special fields you want can be retrieved via getProperty().

Retrieving ModuleInformation Programmatically

You can retrieve the information for any module via the BasicModuleInformation class. The following will give you the ModuleInformation for the "foobar" component:

ModuleInformation info = BasicModuleInformation.getModuleInformation("foobar");

The class will look for "module-foobar.xml" in the classpath and parse the information from the file.

Best Practices

It is recommended that if you plan to provide information for your component or module programmatically, that you use a singleton that hides the work of placing the call. This is done in the rsh-utils class:

com/rshtech/util/Module.java:
package com.rshtech.util;

public class Module {
    
    public static ModuleInformation getInformation() {
        if (singleton == null) {
            initSingleton();
        }

        return singleton;
    }

    private Module() {
        // do nothing
    }

    private static synchronized void initSingleton() {
        if (singleton == null) {
            ModuleInformation instance = 
                BasicModuleInformation.getModuleInformation("rsh-utils");

            // set singleton to initialized instance
            singleton = instance;
        }
    }

    private static ModuleInformation singleton;
}

Code can retrieve information about the current rsh-utils by querying com.rshtech.util.Module.getInformation(). It is only initialized once.

Working With a Build System (like Ant)

You can make your module information dynamic by doing the following:

module-foobar.xml:
<module id="foobar">
    <name>Foobar</name>
    <description><![CDATA[This is the Foobar component]]></description>
    <version>@foobar.version@</version>
</module>

Then, when building the module, be sure to copy the module-foobar.xml file using a filter. Set the property "foobar.version" to your current setting and then copy the file using a filter that replaces "foobar.version" with the contents of "${foobar.version}". Something like the following would work:

in your ant build.xml:
<copy file="src/module-foobar.xml" tofile="build/module-foobar.xml">
    <filterset>
        <filter token="foobar.version" value="${foobar.version}"/>
    </filterset>
</copy>

This will replace the token "@foobar.version@" with the value of ${foobar.version} in the new file "build/module-foobar.xml".

Craftsman Natively Supports ModuleInformation

ModuleInformation was made out of our experience with building and maintaining component-based software. Craftsman is the build-system built and maintained by RSH to meet the needs of RSH projects. We highly recommend you look into using it. If you find using ModuleInformation interesting, you will find Craftsman even more interesting.

To use the ModuleInformation with Craftsman, just create your module-yourname.xml file in the source of your module. The name must match whatever you declare the name to be in Craftsman. Craftsman will automatically set the "yourname.version" and "yourname.build" for you when it builds your module. See the Craftsman Manual for more information on configuring Craftsman.