Craftsman Configuration Examples

This page contains some examples of how to configure various projects or modules with Craftsman. It does not contain any detailed explanations, as those are in the more detailed pages.

Basic Java Configurations

Basic Java Module

A basic Java module is any library which will just be included or used as-is by another project or module. It is not EJB based nor does it have any special packaging to support executable jars.

    <!-- Libraries common to all modules -->
    <library id="junit" name="junit" externaldir="../lib/junit" testlib="true"/>
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar">
            <dependency moduleid="foobar-friend" dir="../foobar-friend"/>
            <library name="rsh-commons"/>
            <library name="log4j" externaldir="../lib/log4j"/>
            <library refid="junit"/>
        </module>
    </craftsmandef>

This shows several things that are useful in defining your typical module:

1. A library reference (junit), which can be used in several modules without having to be redeclared/redefined.
2. A dependency on another module in the project. Say you have foobar and foobar-friend, both in the superfoo folder. You can make one dependent on the other this way without having to copy jars around.
3. A normal library (rsh-utils) that lives in foobar/lib/rsh-utils.
4. A normal library that lives outside the module directory (log4j).
5. A library that is only for building test cases (junit).

Multiple Java Modules

You are not limited to one module. As a matter of fact, you can have as many as you want:

    <!-- Libraries common to all modules -->
    <library id="rsh-commons" name="rsh-commons" externaldir="../lib/rsh-commons"/>
    <library id="log4j" name="log4j" externaldir="../lib/log4j"/>
    <library id="junit" name="junit" externaldir="../lib/junit" testlib="true"/>
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar">
            <library refid="rsh-commons"/>
            <library refid="log4j"/>
            <library refid="junit"/>
        </module>
        <module moduleid="skoobar">
            <dependency moduleid="foobar"/>
            <library refid="rsh-commons"/>
            <library refid="log4j"/>
            <library refid="junit"/>
        </module>
    </craftsmandef>

This defines both the module "foobar" and the module "skoobar". Because of the dependency in skoobar to foobar, any time you call build on skoobar, it will trigger a build on foobar (if foobar has not been built already).

Multiple java modules allows you to build your project or application in small, easy-to-maintain components. The hardest part of making compentized applictions are the build and runtime library dependencies--and as you can see, Craftsman takes care of that for you!

Specialized Java Modules

Standard java library modules are not the only supported module types. As a matter of fact, Craftsman supports 5 additional types, including J2EE modules. When you mark a module as being of a specialized type, it enables additional build processes to help you support that module's specialized needs. For instance, when you mark a module as being "j2ee-ejb", Craftsman takes care of creating Class-Path entries in the final jar and allowing you to use Xdoclet to generate interfaces.

Below are some examples of the more specialized java modules.

Java Application Module (java-app)

A Java application module is a module that creates a stand-alone Java application (that is, one that has a main method and usually requires external libraries to load and execute).

    <!-- Libraries common to all modules -->
    ...
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar-app">
            <capability name="java-app">
                <option name="bundle-name" value="my-aoplication"/>
                <option name="main-class" value="my.application.Someclass"/>
                <option name="package-exclude-library" value="some-lib"/>
            </capability>
            ...
        </module>
        ...
    </craftsmandef>

This will create a module that produces an executable jar. The final jar will be my-application.jar and it will execute the class "my.application.Someclass" when you call "java -jar my-application.jar". There are many more options available. See the capability documentation for more details.

J2EE EJB Module (j2ee-ejb)

A Java application module is a module that creates a stand-alone Java application (that is, one that has a main method and usually requires external libraries to load and execute).

    <!-- Libraries common to all modules -->
    ...
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar-ejb">
            <capability name="j2ee-ejb">
                <option name="ejb-spec" value="2.1"/>
                <option name="target-server" value="jboss"/>
                <option name="target-server" value="weblogic"/>
                <option name="package-exclude-library" value="j2ee"/>
                <option name="package-exclude-library" value="jta"/>
            </capability>
            ...
        </module>
        ...
    </craftsmandef>

This will create a jar that can be included in an EAR and deployed on a J2EE application server. The generated jar will use EJB spec 2.1 and will create deployment files for jboss and weblogic in addition to the generic 2.1 based file. In addition, the libraries j2ee and jta that are needed to compile the EJB module will not be included in the final jar's Class-Path entry. This allows you to use simplified jars to build a given EJB module and then rely on jars available at runtime to execute the module.

For instance, you can use the reference J2EE and JTA implementation jars to get your app to compile and then use the standard JBoss or Weblogic jars to satisfy the J2EE and JTA dependencies at runtime.

See the capability documentation for more options and details.

J2EE Web Application Module (j2ee-webapp)

A Java application module is a module that creates a stand-alone Java application (that is, one that has a main method and usually requires external libraries to load and execute).

    <!-- Libraries common to all modules -->
    ...
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar-ejb">
            <capability name="j2ee-ejb">
                <option name="ejb-spec" value="2.1"/>
                <option name="target-server" value="jboss"/>
                <option name="target-server" value="weblogic"/>
                <option name="package-exclude-library" value="j2ee"/>
                <option name="package-exclude-library" value="jta"/>
            </capability>
            ...
        </module>
        ...
    </craftsmandef>

This will create a jar that can be included in an EAR and deployed on a J2EE application server. The generated jar will use EJB spec 2.1 and will create deployment files for jboss and weblogic in addition to the generic 2.1 based file. In addition, the libraries j2ee and jta that are needed to compile the EJB module will not be included in the final jar's Class-Path entry. This allows you to use simplified jars to build a given EJB module and then rely on jars available at runtime to execute the module.

For instance, you can use the reference J2EE and JTA implementation jars to get your app to compile and then use the standard JBoss or Weblogic jars to satisfy the J2EE and JTA dependencies at runtime.

See the capability documentation for more options and details.

J2EE Application Module (j2ee-app)

A Java application module is a module that creates a stand-alone Java application (that is, one that has a main method and usually requires external libraries to load and execute).

    <!-- Libraries common to all modules -->
    ...
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar">
            ...
        </module>
        <module moduleid="foobar-ejb">
            ...
        </module>
        <module moduleid="foobar-web">
            ...
        </module>
        <module moduleid="foobar-app">
            <capability name="j2ee-ejb">
                <option name="app-name" value="foobar"/>
            </capability>
            <dependency moduleid="foobar"/>
            <dependency moduleid="foobar-ejb"/>
            <dependency moduleid="foobar-web"/>
            ...
        </module>
    </craftsmandef>

This will create an EAR named "foobar.ear" that will contain a <module> entry for foobar-ejb and a <module> entry with required Web application entries for foobar-web.

Please note that building J2EE applications from modules via dependencies is considered the one of the Craftsman Best Practices.

See the capability documentation for more options and details.

JWSDP Web Service Module (java-ws)

A Java application module is a module that creates a stand-alone Java application (that is, one that has a main method and usually requires external libraries to load and execute).

    <!-- Libraries common to all modules -->
    ...
    
    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar-ws">
            <capability name="java-ws">
                <option name="wscompile-mode" value="manual-wsdl2java"/>
                <option name="generate-mode" value="server"/>
                <option name="keep-source" value="true"/>
                <option name="ws-source-dest" value="build/wsdlsrc"/>
                <option name="literal-encoding" value="rpc"/>
            </capability>
            ...
        </module>
        ...
    </craftsmandef>

This will create module jar that can contains a JWS that is ready to deploy on a standard Java Web Services platform. It will enable build options for generating server stubs from a WSDL file.

See the capability documentation for more options and details.