Macker Guide

Basic Example

A Simple (and Absurd) Rules File

Here is a very simple Macker rules file:

<?xml version="1.0"?>
<macker>    
    <ruleset name="Simple example">
        <access-rule>
            <deny>
                <from class="**Print*" />
                <to class="java.**" />
            </deny>
        </access-rule>
    </ruleset>
</macker>

The <macker> tag encloses a whole rules file. The <ruleset> groups related rules. An <access-rule> governs which classes may refer to other classes; it can contain <deny> and <allow> rules. The deny rule above says that any class whose name contains "Print" may not reference any of the core Java classes. (It's a rather absurd rule, but illustrative.)

Running the Example

You'll typically run Macker from within Ant, something like this:

<target name="macker" depends="compile">

    <!-- Defines the macker ant task.  You need this once per build file. -->
    <!-- The classpath here tells Ant where to look for the Macker Ant task. -->
    <taskdef name="macker"
        classname="net.innig.macker.ant.MackerAntTask"
        classpathref="build.classpath"/>  
    
    <macker>
        <!-- This classpath tells Macker where to look for its own -->
        <!-- libraries, and the libraries used by the primary classes. -->
        <classpath refid="build.classpath" />

        <!-- Rules come from this file: -->
        <rules dir="${src.dir}" includes="macker.xml" />

        <!-- Macker will apply those rules to these primary classes: -->
        <classes dir="${build.classes.dir}">
            <include name="**/*.class" />
        </classes>
    </macker>
    
</target>

(See the full working Ant targets at doc/example/build-shared.xml. You'll need version 1.5 or newer of Ant; get it from the Ant site.)

If you are on a UNIX system (or at least have a Bourne shell), you can also use macker from the command line:

macker-home/bin/macker -r rulefile.xml SomeJavaClass.class ...

(If somebody would like to write a good .bat file to do the same thing the shell script does, send it to me and I'll include it.)

Macker requires Java 1.3.1 or newer, and the following libraries:

All these libraries are included in the lib/ directory of the Macker distribution. The shell script version picks up the libs automatically, as long as you don't move them or the script. For the Ant task, you'll need to include them in the classpath when you run Macker.

The Example's Output

If we tell Macker to apply the absurd rule above to the following Java class...

public class PrintHelloWorld
    {
    public static void main(String[] args)
        { System.out.println("Hello world, as they say!"); }
    }

...we will get the following response:

Checking ruleset: Simple example ...

Illegal reference
  from PrintHelloWorld
    to java.io.PrintStream

Illegal reference
  from PrintHelloWorld
    to java.lang.Object

Illegal reference
  from PrintHelloWorld
    to java.lang.System

Note that Macker picked up not only HelloWorld's access of java.lang.System, but also two less obvious accesses: HelloWorld implicitly extends java.lang.Object, and also makes use of java.io.PrintStream by calling its println() method. Macker will pick up a number of accesses not immediately apparent to the naked eye.

Note also that Macker did not get mad about any of the references from java.io.PrintStream to other java utilities, even though its name contains "Print", and our rule would apply. Macker only applies rules to the primary classes you specify, not to every class it can find in your classpath. (See the Access Rules section.)

SourceForge Logo        innig