Source Patch

Prettifying XML files for web browsers

2011-10-25T20:42:00.001-07:00

I am a big user of public XML formatters, such as http://www.xmlformatter.net/ as part of my regular work, largely because I need to understand some glob of an XML returned without any formatting by a server presumably tuned for maximum performance.

More recently, I was faced with the need to produce those nice XML representation within automatically generated documentation, specially now that version 0.9.0 of the excellent Lunatech Jaxdoclets library (http://www.lunatech-labs.com/open-source/jax-doclets) can also include external HTML contents in the final jaxdoc output of a JAX-RS implementation.

So what I needed was a formatter that could be embedded into our build structure, or even incorporated into a live server to create a private XML formatter service where we did not have to worry about obfuscating XML contents before sending them out to the extranet (e.g. IP addresses, passwords, someone’s address, etc) .

Since our build is based on Ant and our live server based on Tomcat, it made sense to settle into using XSLT. This link (http://www.dpawson.co.uk/xsl/sect2/pretty.html) is a good start, but I really wanted output in HTML with all the niceties of CSS styles, etc.

For now, the transformation is listed below. I am not terribly happy with the solution for namespaces and the “pad” template would need a serious performance optimization if used in mainline processing (not my case) , probably by a sub-string function call using a long chunk of whitespaces as parameters since XSLT does not have generic for loops.

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fn="http://www.w3.org/2005/xpath-functions"
xmlns:xs="http://www.w3.org/2001/XMLSchema" >

    <xsl:output method="html" />
    <xsl:strip-space elements="*" />
    
    <!--  
       - Root match
      -->
    <xsl:template match="/">
        <html>
            <head>
                <title>HTML version of XML resource</title>
                <link rel="stylesheet" type="text/css" href="frs-jaxdoc.css" />
            </head>
            <body>
                <xsl:apply-templates>
                    <xsl:with-param name="indent" select="0" />
                </xsl:apply-templates>
            </body>
        </html>
    </xsl:template>


    <!--  
      - Processes XML elements 
      -
      - param indent              indentation count
      - param ancestorsNamespaces concatenation of all namespace URIs from all parents, which is 
      -                           used to determine if a namespace has already been declared in
      -                           a parent XML element.
      -->
    <xsl:template match="node()[name()]">

        <xsl:param name="indent" select="0" />
        <xsl:param name="ancestorsNamespaces" select="''" />

        <xsl:variable name="hasChildren" select="count(child::node()) > 0"/>
        <xsl:variable name="hasTextNode" select="count(child::text()) > 0"/>

        <!--  Format opening of XML element -->
        <xsl:if test="$indent > 0"><br/>
        </xsl:if>
        <xsl:call-template name="pad">
            <xsl:with-param name="indent" select="$indent * 2" />
        </xsl:call-template>
        <span class="xmlElement">&lt;<xsl:value-of select="name()" /></span>
        
        <!-- Add namespaces to XML element -->
        <xsl:variable name="selfNamespaces">
            <xsl:for-each select="namespace::node()">
                <xsl:value-of select="." />
            </xsl:for-each>
        </xsl:variable>
        <xsl:variable name="hasAttributes" select="count(@*) > 0" />
        <xsl:for-each select="namespace::node()">
            <xsl:if test="contains($ancestorsNamespaces, .) = false()">
                <xsl:if test="position() = 1">&#160;</xsl:if>
                <xsl:if test="position() > 1">
                    <br/>
                    <xsl:call-template name="pad">
                        <xsl:with-param name="indent" select="($indent+1) * 2" />
                    </xsl:call-template>
                </xsl:if>
                <span class="xmlNamespacePrefix">xmlns:<xsl:value-of select="name()" /></span>=<span class="xmlNamespaceUri">"<xsl:value-of select="." />"</span>
                <xsl:if test="position()=last() and $hasAttributes">
                    <br/>
                    <xsl:call-template name="pad">
                        <xsl:with-param name="indent" select="($indent+1) * 2" />
                    </xsl:call-template>
                </xsl:if>
            </xsl:if>
        </xsl:for-each>
        
        <!-- Add attributes to XML element -->
        <xsl:apply-templates select="@*" />
        
        <!-- Close opening XML element tag, with special handling for element without children node -->
        <span class="xmlElement"><xsl:if test="$hasChildren = false()">/</xsl:if>&gt;</span>

        <!-- Add children to XML element -->
        <xsl:apply-templates select="node()">
            <xsl:with-param name="indent" select="$indent + 1" />
            <xsl:with-param name="ancestorsNamespaces" select="concat($ancestorsNamespaces,$selfNamespaces)" />
        </xsl:apply-templates>

        <!--  Close XML element, but only if not already closed with XML element abbreviation -->
        <xsl:if test="$hasChildren = true()">
            <xsl:if test="$hasTextNode = false()">
                <br/>
                <xsl:call-template name="pad">
                    <xsl:with-param name="indent" select="$indent * 2" />
                </xsl:call-template>
            </xsl:if>
            <span class="xmlElement">&lt;/<xsl:value-of select="name()" />&gt;</span>
        </xsl:if>

    </xsl:template>


    <!--  
      - XML text 
      -->
    <xsl:template match="text()">
        <xsl:variable name="nodeValue" select="." />
        <xsl:if test="string-length($nodeValue) > 0">
            <span class="xmlText"><xsl:copy-of select="$nodeValue" /></span>
        </xsl:if>
    </xsl:template>


    <!-- 
      - XML attributes 
      -->
    <xsl:template match="@*">
    <xsl:if test="position() > 0">&#160;</xsl:if>
     <span class="xmlAttr"> <xsl:value-of select="name()" /> </span>=<span class="xmlAttrValue">"<xsl:value-of select="." />"</span>
    </xsl:template>


    <!--  
      - Padding for HTML output, used for indentation purposes
      -->
    <xsl:template name="pad">
        <xsl:param name="indent" select="0" />

        <xsl:if test="$indent > 0">
            &#160;
            <xsl:call-template name="pad">
                <xsl:with-param name="indent" select="$indent - 1" />
            </xsl:call-template>
        </xsl:if>
    </xsl:template>

</xsl:stylesheet>

And this is the companion CSS file:

.xmlElement {
	color: #990099;
}

.xmlAttr {
	color: #660066;
}
.xmlAttrValue {
	color: #0000CC
}

.xmlNamespacePrefix {
	color: #666600;
}

.xmlNamespaceUri {
	color: #000099
}

xmlText {
}

BODY {
	font-size: 10pt;
	font-family: "Courier New"
}

The style names for classes are not that verbose, but I thought I would make it more legible for this entry.

Burning up

2010-11-17T14:33:00.001-08:00

I am growing increasingly fond of the Agile development method. It really has a transformational effect on how the teams operate and relate to their work.

Now working on a team of 26 people in four scrums spread across four geographies and four timezones, we have stepped up our reliance on Rational Team Concert dashboards to keep track of how each team is progressing. Each scrum team still has daily standup meetings and scrum of scrum meetings with the product owner, scrum masters, and stakeholders. Though the emphasis during the scrum of scrums is on the reporting from each scrum master, we have started to appreciate and use “burnup” charts as the backdrop for these meetings.

Disclaimer: I am an IBM employee with access to an internally hosted instance of Rational Team Concert. For small teams of up to 10 people, and with some functional restrictions, RTC is freely available at http://jazz.net.

There is ample literature on why “burnup” charts are superior to “burndown” charts, but RTC combines project tracking and team information to provide significantly enhanced visibility on project progress. I produced a couple of heavily data-altered versions of our actual “burnup” charts as examples.

RTC Burnup Data Series

“Total Capacity” indicates how much work the team can execute on a given period. It is always a flat, straight, line. RTC uses information provided by each team member on their availability in terms of hours per day, vacation, and holidays.
“Planned Work” indicates how much work is actually planned for a given period. For any sane project, it should be under the “ Total Capacity” line at all times, otherwise low-priority work should be moved from that period immediately. In the example chart above, this can be observed on 11/16.
“Expected Complete” indicates how much work should be completed over time so that all planned work is completed at the end of the given period. Always a straight line starting from 0 hours and ending at the total amount of planned work hours.
“Completed Work” indicates how much work the team is logging in the system against the tasks assigned to each individual. In very simple terms, "completed work should be at or above the “Expected Complete” line, indicating the team is on schedule or ahead of schedule. In the example chart above, it is possible to see the team recovering from a slow start and exceeding expectations after 11/10.
“Linear Complete” is a liner regression of data points in the “Completed Work” series. It projects how much work will be done at the end of the given period. This line should be at or above the “Expected Complete” line, otherwise remediation is required, such as moving distracting low-priority work from that period of time. In the example chart above, that line is slightly above the “Expected Complete” line, a good sign, indicating all work being completed one or two days ahead of schedule (where it crosses above the “Planned work” line) .
“Capacity Burnup” indicates how much capacity the team is “burning” during a given period. It goes up whether the team is working or not, because the time available to work in that period is reduced every minute. Ideally you want the “Completed Work” line to be at or above the “Capacity Burnup” line, indicating that team is burning up its capacity on actually planned work. In the above example chart, notice how the first half of the period has less completed work than the capacity being spent, a clear indication that people are being diverted from the planned work.

A non-ideal example

The first example was somewhat benign in that execution would have been well planned and completed ahead of time. Now lets look at another hypothetical example, with some planning and execution challenges:

The first warning sign is a number of data points *above* the “ Total Capacity” line, specially the “ Planned Work” line. In a real project, this chart would be telling the project owner to move content outside the given period right at the beginning. Notice how the “Planned Work” line does go down on 11/3, only to steadily climb up again. RTC does have an “Estimated vs Actual Work” chart that can clarify whether that increase in “Planned Work” is the result of new work being added to the period or the result of planned work taking longer than planned. I like to have both side by side in the same dashboard.

The second warning sign is the “Completed Work” line being significantly above the “Capacity Burnup” chart line, an indication that the team worked a fair amount of overtime during the period. Though the “Linear Complete” projection is slightly above the “Expected Complete” work, the actual data points for “Completed Work” show the team running out of steam towards the last days of the interval (complete work goes from above expected to below expected around 11/10) .

In summary

A quick glance at a “burnup” chart, assuming somewhat accurate reporting by the team, will immediately point at any action required by the scrum master and product owner. This is the cheat-sheet I share with others reading these charts, which takes a lot of the guess work about how teams are doing.

The “Capacity Burnup” line should always be at the top of all other lines or content must be moved out of the period in question.
The “Linear Complete” and “Completed Work” lines must be on top of or above the “Expected Complete” line, otherwise they indicate the team will overrun its time budget.
The “Linear Complete” line must be somewhat matched to the “Capacity Burnup” line. If it is significantly below that line, it indicates the team is working on something else other than planned content (e.g. spending 2 days reimaging failed hardware) ; if it is significantly above the capacity burnup, the team is working overtime and may run out of steam at the end of the period.
Steady, rather than abrupt, increases in the “Planned Work” line typically indicate the team taking longer on tasks than originally planned.
Abrupt, rather than steady, changes in the “Planned Work” line typically indicate work items being moved in and out of the time period. The product owner should always be aware of the causes for those changes.

STAX automation: Converting a property file into a Python dict() object

2010-06-25T05:32:00.001-07:00

Coming back to test automation, where I reiterate my fondness of the STAX/STAF framework.

Trying to read the contents of a properties file containing “key=value” pairs, I found this article on how to write the entire thing in Python (the underlying scripting language for STAX scripts) : http://code.activestate.com/recipes/496795-a-python-replacement-for-javautilproperties/. A few minutes trying to visualize how to embed it into a STAX “script” construct, I realized I did not have the same constraints of not being able to use Java and could write the far more simple construct:

---

    <function-prolog>
        Returns a Python dict object representing the keys found inside a properties file.
    </function-prolog>

    <function-map-args>
        <function-required-arg name="properties_file">
            Properties file to be read.
        </function-required-arg>
    </function-map-args>

    <sequence>
        <script>
            from java.util import Properties
            from java.lang import String
            from java.io import File
            from java.io import FileInputStream
            from java.io import IOException

            env_exception = None
            props = Properties()
            try:
                fis = None
                try:
                    file = File(properties_file)
                    fis = FileInputStream(file)
                    props.load(fis)
                    props_dict = {}
                    prop_names = props.propertyNames();
                    for i in range(props.size()):
                        prop_name = prop_names.nextElement()
                        prop_value = props.getProperty(prop_name)
                        props_dict.setdefault(prop_name, prop_value)

                except IOException, e:
                    env_exception = e.getMessage()
            finally:
                if fis != None:
                    fis.close()
        </script>

        <if expr="env_exception != None">
            <sequence>
                <script>
                    err_msg = 'Attempt to load properties file %s resulted in exception %s' % (properties_file, env_exception)
                </script>
                <message log="STAXLogMessage">err_msg</message>
                <throw exception="'STAXException'">err_msg</throw>
            </sequence>
            <else>
                <message log="STAXLogMessage">
                    'Environment [%s] is %s' % (properties_file, props_dict)
                </message>
            </else>
        </if>

<return>props_dict</return>

</sequence>
</function>

Handling process launches in STAF / STAX

2010-04-08T14:03:00.001-07:00

I have been a big fan of STAF test automation framework for many years. STAF is open-source and runs on all mainstream platforms (including IBM System z and Mac) . Its key strengths are distributing and coordinating tasks across multiple machines.

Launching processes in distributed machines is really well-implemented as a STAF service and also receives special treatment in the companion STAX execution engine. Process management is always a thorny discipline, dealing with process output, error codes, deciding whether or not to wait until they are done, and many other concerns.

I compiled a personal list of STAF/STAX options in launching new processes that always trick newcomers to the tool.

Waiting for a process launched through STAF

Running a command on any given machine running the STAF process is as simple as executing “staf <machine> PROCESS START <command>”.

What often derails people are the default launch settings, which instructs STAF to launch the process **asynchronously* and moving on, often breaking follow on commands that depend on the results of the first. If you must wait until the process completes its execution, you need to use the “WAIT” flag.

The next relevant flag is “SAMECONSOLE”, which prevents STAX from launching a new console (default behavior on Windows) . For most runs of unattended commands, SAMECONSOLE is your option of choice.

The last important flags are the ones indicating that you want STAF to collect the command results, namely RETURNSTDERR and RETURNSTDOUT, as follows:

Results from asynchronous launches

If you really must run a command asynchronously, you need to store the command handle returned by STAF and query its results later on.

Inside STAX

Launching the same process using the STAX engine requires more effort, which is understandable since STAX is a more sophisticated execution engine with support for programmatic constructs.

One of the most important observations about the <process> call inside STAX is that it always wait for command invocation and it does not have the concept of consoles. In other words, STAX <process> element always uses the equivalent of “WAIT SAMECONSOLE” in the STAF PROCESS parameters.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd"> 

  <stax>      <defaultcall function="test" /> 
     <function name="test" scope="local"> 
        <sequence> 
 
            <process name="'test.dir'">   
                <location>'local'</location>     
                <command mode="'shell'">'dir \\tmp'</command>     
                <console use="'same'" />  
                <returnstdout />  
                <returnstderr />  
            </process> 
              <message>     
                "Result code: %i " % STAXResult[0][0]     
            </message> 
   
            <message>     
                "Result data: %s " % STAXResult[0][1]     
            </message> 
   
        </sequence>    
    </function>     
</stax>

While observing the results in the Job monitor, we will see:

In conclusion

As usual, the excellent user guides shipped with both STAF and STAX are the most comprehensive material for learning about the intricacies of launching remote processes and manipulating their results. I just missed a short guide like the one above showing the STAF / STAX equivalence side-by-side.

Ant targets with different classpaths

2010-03-02T12:47:00.001-08:00

I recently ran into a problem where an Ant task could not find a given Java class. There are a number of solutions listed in the Ant FAQ page, all passing through adding the corresponding JAR files to the Ant lib directory or the the classpath before invoking Ant.

It turns out the particular task from the Ant target I imported was invoking an XSL transformation containing function defined in an external class, like this:

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xalan2="http://xml.apache.org/xalan"
 xmlns:fixquote="com.package.ExternalXsltFunction"
...

The original ExternalTask task was defined in A.jar, but com.package.ExternalXsltFunction was defined in external.jar. Since com.package.ExternalXsltFunction is dynamically loaded only when the internal XSL transformation is invoked, Ant simply ignores and discards its containing JAR file while trying to load ExternalTask.

<taskdef name="externaltask" classname="com.package.ExternalTask">
    <classpath>
        <pathelement name=”A.jar”/>
        <pathelement name=”external.jar”/>    <—Makes no difference, ExternalXsltFunction  is not loaded when ExternalTask is loaded.
    <classpath/>
</taskdef>

The solution was to create an extension of the venerable “antcall” task, adding a “classpath” element to it. This new task, let’s call it “antcallwithclassloader”, sets the classpath to the thread of execution, invokes the target, then resets the thread classpath back to its original value, like this (all comments stripped out):

 
package com.myproject.ant; 
import org.apache.tools.ant.AntClassLoader;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.taskdefs.CallTarget;
import org.apache.tools.ant.types.Path;
import org.apache.tools.ant.types.Reference; 
 
public class CallTargetWithClasspath extends CallTarget { 
 
    private Path classpath; 
    private Reference classpathRef; 
 
    @Override
    public void execute() throws BuildException {
        Path resolvedClassPath = null;
        if (classpathRef != null) {
            resolvedClassPath = (Path)classpathRef.getReferencedObject();
        } else {
            resolvedClassPath = classpath;
        }
        AntClassLoader acl = new AntClassLoader(getProject(), resolvedClassPath);
        acl.setThreadContextLoader();
        super.execute();
        acl.resetThreadContextLoader();
    } 
 
    public Path getClasspath() { return classpath; } 
    public void setClasspath(Path targetClasspath) { this.classpath = targetClasspath; } 
    public Path createClasspath() {
        classpath = new Path(getProject());
        return classpath;
    } 
    public Reference getClasspathRef() { return classpathRef; } 
    public void setClasspathRef(Reference classpathRef) { this.classpathRef = classpathRef; } 
}

With this task, now added to a “myanttools.jar” file, I could successfully refactor my Ant script so that the problematic task was moved to its own target and was invoked with its required classpath, like this:

    <taskdef name="my.antcall" classname="com.myproject.ant.CallTargetWithClasspath" >
           <classpath>
               <pathelement location="myanttools.jar"/>
         </classpath>
    </taskdef>

    <target name="wrapper.target" depends="init">
        <my.antcall target="refactored.target">
            <classpath>
                <pathelement path=”external.jar”/>   <—- Adds B.jar to the classpath before invoking target
            </classpath>
        </my.antcall>
    </target>

    <target name="refactored.target">
       <!—- The caller set external.jar in the classpath –>
       <!-- and ExternalXsltFunction is visible to the classloader -–>



        <externaltask …/>
   </target>

Optimizing Atom feed parsing with Apache Abdera

2010-01-14T18:44:00.001-08:00

I chose Apache Abdera as my Atom processor of choice for a number of small projects. Skipping the processing of unwanted XML elements inside an Atom feed is the most basic optimization for these applications.

For one of these applications, a statistics aggregator of sorts, there was no need to look into the summary and raw contents of each entry. Enter the Apache Abdera built-in filter support, through which one can instruct the parser to only accept or ignore certain entry elements.

The samples in the Abdera wiki didn’t quite match the public Javadocs, so I ended up writing my own version of what the wiki described as a black list filter:

Abdera abdera = new Abdera();
Parser abderaParser = abdera.getParser();
ParserOptions defaultParserOptions = abderaParser.getDefaultParserOptions();
FavoriteParseFilter fpf = new FavoriteParseFilter();
defaultParserOptions.setParseFilter(fpf);
abderaParser.setDefaultParserOptions(defaultParserOptions);

where FavoriteParseFilter is defined like this:

public class FavoriteParseFilter implements org.apache.abdera.filter.ParseFilter{
    private static final QName CONTENT_QNAME =
        new QName("http://www.w3.org/2005/Atom", "content");
    private static final QName SUMMARY_QNAME =
       new QName("http://www.w3.org/2005/Atom", "summary");
    /*
    * (non-Javadoc)
    *
    * @see org.apache.abdera.filter.ParseFilter#acceptable(javax.xml.namespace.QName)
    */
  public boolean acceptable(QName n) {
      boolean result = !(n.equals(CONTENT_QNAME) ||
                         n.equals(SUMMARY_QNAME));
     return result;
   }

Results may vary, but I observed a gain of at least 25% in overall throughput using a simple application fetching a remote feed with entries about 2Kb in size.

Polygonal menus?

2010-01-11T06:58:00.001-08:00

Jury is still out on the efficiency of these kinds of contextual menus instead of regular tabular format.

For now, they are filed under the uncoveted “because we could” folder in my brain.

Mastering Mock Objects - Advanced Unit Testing for Java

2009-09-29T18:34:00.001-07:00

A collection of notes on the use of JMockit and JMock in Java unit testing.

Mastering Mock Objects - Advanced Unit Testing for Java

View more presentations from Denilson Nastacio.

Tips for dealing with DB2 database samples in your product

2009-09-09T12:42:00.000-07:00

In trying to ship a sample of the ITM (IBM Tivoli Monitor) database utilized by our product, we stumbled upon the cross-platform restrictions of the backup/restore commands for DB2, which state:

The supported platforms for DB2 backup and restore operations can be grouped into one of three families:

Big-endian Linux^® and UNIX^®

Little-endian Linux and UNIX

Windows^®

After hours of fiddling with DB2 manuals and succeeding partially in moving the data from an DB2 in AIX 64 bits to a Windows 32 bits, I eventually stumbled upon this great developerWorks article, fittingly titled: Using DB2 utilities to clone databases across different platforms.

Essentially it uses a combination of the “db2move” and “db2look” commands, like this

Exporting the data

To export the contents of the database, change to the directory where the exported directory where the files should be written and run:

db2move WAREHOUS export -sn ITMUSER
db2look -d WAREHOUS -e -a -o db2look.sql

where WAREHOUS is the name of the database I was exporting and ITMUSER the schema for it.

Importing the data

Copy over the files to the target machine and change to the directory where the exported files are. Then run the command:

db2 “create db WAREHOUS”
db2 –tvf db2look.sql
db2move WAREHOUS import

where WAREHOUS is the name of the database you are importing.

You can use a different database name, but you need to edit the first line of the db2look.sql file to match the name.

Unit testing tools, a minimalist toolset.

2009-09-03T12:25:00.000-07:00

After wading through the sea of unit testing tools out there, here is a minimalist (and so far, sufficient) set of open-source tools for testing server-side centric Java code.

----

JUnit 4.x

That is almost a given, full integration with Eclipse and Ant, standard in the industry, etc, etc. JUnit 4.1 is the last release where I did some thorough investigation of any new function, though the just released JUnit 4.7 (Aug/4th) has some function I would like to explore.

----

DDTUnit (http://ddtunit.sourceforge.net/)

This is the best alternative for data-driven testing, where the test code is small but has to use different data inputs.

Side comment:This presentation cross-compares DDTUnit with other data-driven approaches:

Data-Driven Unit Testing for Java

View more presentations from Denilson Nastacio.

Tip: The syntax for the test XML data can be a chore, but this Eclipse snippet (with instructions) can help:
http://sourcepatch.blogspot.com/2009/08/ddtunit-and-eclipse-snippets.html

----

JMock (http://www.jmock.org/)

This library allows you to pre-program objects in the JUnit testcase with the "right" responses to exercise the target code.

----

JMockit (https://jmockit.dev.java.net/)

This library is used to replace Java calls ordinarily not under your control with code under your control.

For instance, you can intercept a call to DriverManager.getConnection and return your own implementation of java.sql.Connection.

Tip 1: This library requires you to add -java.agent=build_dir/libraries/test/jmockit/jmockit.jar to the unit execution path.
Tip 2: Avoid it if you can, it makes tests slower and harder to follow. If you have another entry point to pass a JMock object, such as setter method, do it.

Links I have bookmarked about unit testing recently: http://delicious.com/nastacio/unit-testing

DDTUnit and Eclipse Snippets

2009-08-31T12:20:00.001-07:00

One of the tedious aspects of using the excellent DDTUnit library is the creation of the Java class for the test case and the XML data sets. There is no nice Eclipse wizard to do that for you, but today I started to create a set of Eclipse snippets for it. My productivity went to the ditch for the first three hours, but it should pay off sometime between today and tomorrow.

I just select some complicated block of DDTUnit source code or XML on Eclipse, right-click it and choose "Add to snippets". I then replace some hard-coded values, such as the name of an input object, with a variable and save it.

Later, when I need a similar snippet, I just position the cursor where I need the new source code or XML, double-click the snippet from the toolbar, fill out any variables associated with the template (usually one or two) and goodbye round-trips to the DDTUnit reference guide.

The snippets library master: http://drop.io/dnastacio/asset/ddtunit-eclipse-snippets-xml

Code comments are for newbies

2009-08-31T08:26:00.001-07:00

I am sure you have seen or participated in a debate about how much or how little comments one should put in his own code.

Now look at this pearl I found while writing a presentation about the excellent JMock library.

Just think of the possibilities in terms of team communication: “Jim, can you unlock ThatClassThatFixesThatBugWeDiscussedLastThursday.java?”

Distributed Java code inspection

2009-07-30T18:53:00.001-07:00

As a requirement of our current project, we wanted to establish a minimum criteria of code quality ahead of formal code inspections. No point in wasting valuable brain capacity at spotting simple problems such as using “==” instead of “equals” and so on.

Static code analysis is a good starting point, though it can be a bit intransigent about false-positives, where the developer had good cause to write code in a way that the rule developer could not have anticipated.

Being that our main development tool is Eclipse, this was the one criteria that made me give up on the excellent FindBugs, in that there was no way to mark up the source code to tell FindBugs to ignore the problem in future scans.

Enter the Eclipse built-in code analysis, which not only allows scanning source code, but also has a simple way of marking false-positives inside the source code using a Java comment, so that further scans will not flag the problem again.

Sharing a rule base

The first step in sharing a rule base is to create one, which can be done from the “Run –> Analysis…” menu.

Set the “Scope” to “Analyze selected projects”, without actually checking any project box. This will allow you to right-click any project and then run the analysis only on the selected project.

Under “Rules”, pick the ones you consider the most important. It took me a couple of scans on pre-existing code to weed out the faulty ones (there are a few) and the overly conservative ones. Once I was satisfied, I clicked on the “Export…” button to save it to a file I could share with my colleagues.

Importing a rule base

Starting from the “Run –> Analysis…” menu again, click on the “New launch configuration” button, give it a name. Again, set the “Scope” to “Analyze selected projects”, without actually checking any project box.

In the “Rules” tab, click on the “Import…” button and select the “.dat” file exported in the previous step, which is stored in a location shared with the entire team.

Scanning the code

Right-click a Java project and select “Analysis –> [Name of your launch configuration]”. In a few seconds, the results will be displayed in the “Analysis Results” view.

Right-clicking any of the individual results shows a menu with options for a “Quick Fix” (available for some rules) or the selection of “Ignore Result”. The latter option will add a Java comment next to the flagged line of code, instructing the analyzer to not flag the problem in future scans.

AspectJ for Java logging: suppressing System.out debugging calls - part 7

2009-05-18T06:00:00.000-07:00

We have all been there, adding a few System.out calls here and there to our Java code during development to help debug something that defies (bad) logic.

It seems all too common to, ahem, leave some of those calls behind, which introduces several problems in a product. Don't we love to see the occasional "WE ARE HERE!!" graffiti in the server console, or a 50MB trace file that cannot be opened by any text editor?

One way to prevent this problem is to continuously demand that developers pay attention to it, either deleting the offending statements or converting them to a Logger.log call. That approach also has drawbacks in that mistakes are, well, mistakes. A complementary approach to pleading with developers is to intercept the requests to System.out and System.err and route the "println" commands to a trace call.

Here are the changes to the Logging serviceability aspect. I still want to find a way to use the name of method calling System.out.println in the trace calls, but for now, here are the interesting bits:

...

public aspect Logging pertypewithin((my..*) && !Exception+){

	/**
	 * Trace handler for each type.
	 */
	private static Logger trace = Logger.getLogger("my.project" ) ;

	private static TracePrintStream sysoutTrace = null;

         ...

	/**
	 * After the initialization of all classes in this project.
	 */
	after(): dcofpClassInitializer() {
		String classname = thisJoinPointStaticPart.getSourceLocation()
				.getWithinType().getName();
		classname = LoggingUtil.normalizeClassName(classname);
		trace = Logger.getLogger(classname);
		sysoutTrace = new TracePrintStream(trace, "System.out", System.out);
	}

         ...

	/**
	 * Replace calls to SystemOut with trace calls
	 */
	PrintStream around(): dcofpSystemOutPrintln() {
		return sysoutTrace;
	}

         ...

	/**
	 * Inner class used to convert System.out.println calls to trace calls.
	 */
	public class TracePrintStream extends PrintStream {
...
		public void println(String str) {
			trace.logp(Level.FINER, trace.getName(), method, str);
		}
...
        }
}

Generated Java-XML bindings and external builders in Eclipse

2009-05-12T18:37:00.001-07:00

Our project is using the Apache XMLBeans tool to bind XML schemas to Java code.

One possibility to deal with the bindings is to generate them on a local machine and check in the generated code. The drawback is that people maintaining the code need to deal with all sorts of file operations for things as simple as a namespace change. The Java bindings wiggles at the will of its source XSD file, so that checking it in is not far from checking in a generated JAR or WAR file.

The other possibility is to generate the code during build time, using the xmlbean ant task, which would be sort of annoying for developers using the Eclipse environment. Whenever the project was imported anew from the source control system, they would have to first invoke the generation target and then refresh their workspace.

It turns out Eclipse has a great solution for this, in the form of a project builder.

I created a new builder, which invoked the correct ant target every time a developer used "clean" or "build".

That was it for the easy part. The next trick was to make the Ant target as efficient as possible, since it would be impractical for developers to wait several seconds for the "xmlbean" task completion every time they did something as simple as updating an unrelated Java source file.

That is when the Ant conditional targets come in handy. It was only a matter of setting a property if the files had never been generated or if the source XSD file was updated after they had been generated.

<property name="xmlbean.javac.optimize" value="on" />
<property name="xmlbean.verbose" value="false" />
<property name="xmlbean.quiet" value="true" />
<property name="design.info.schema" value="${dir.schema}/DesignInfo.xsd" />
...
<condition property="xmlbean.designinfo.updated">
    <or>
        <not>
            <available file="${dir.build.xml.classes}" />
        </not>
        <uptodate targetfile="${design.info.schema}">
               <srcfiles dir="${dir.build.xml.classes}" />
        </uptodate>
    </or>
</condition>
 
<target name="genxmlbeans.designinfo" if="xmlbean.designinfo.updated">
    <xmlbean schema="${design.info.schema}" 
             classgendir="${dir.build.xml.classes}" 
             classpathref="class.path" 
             failonerror="true" 
             optimize="${xmlbean.javac.optimize}" 
             verbose="${xmlbean.verbose}" 
             quiet="${xmlbean.quiet}" />
</target>

DDTUnit snippet to represent a HashMap containing complex objects

2009-05-04T07:17:00.000-07:00

As a big fan of DDTUnit for Java unit testing, this gets me every time. I often need a java.util.HashMap object with complex values. Here it is for posterity (and later lookup) :

    <obj id="masterResults" type="java.util.HashMap" 
         hint="map" keytype="string" valuetype="com.company.project.LogFileResult">
        <item>
        <key type="java.lang.String">
            data/com.com.company.project.custom/config/Lotus/Domino/nl/example.log
            </key>
            <value type="com.company.project.LogFileResult" hint="call"
                   method="constructor">
            </value>
        </item>
    </obj>

The Java code to retrieve it inside the DDTUnit fixture:

    HashMap masterResults = (HashMap) getObject("masterResults");

"Improving interface design" presentation

2009-04-29T21:11:00.001-07:00

By the way of a colleague, a thought inspiring presentation on the creation of user interfaces.

This one quote stuck with me above everything else:

"I've been amazed at how often those outside the discipline of design assume that what designers do is decoration. Good design is problem solving."

| View | Upload your own

AspectJ for Java logging: Serviceability without the clutter - part 6

2009-04-10T07:03:00.000-07:00

Just realized I was missing the join point for constructors in the code. I also noticed the "getArgs" method in the "thisJoinPoint" object, which simplified the "methodError" point cut.

See the changes in red and the whole "Logging.aj" aspect as it stands today:

package my.project.aspects;

import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Aspect for Java logging throughout the code base.
 */
public aspect Logging pertypewithin(my..* && !Exception+) {

    private static Logger trace = Logger.getLogger("trace.my.project");

    /*
     * Pointcuts
     */
    
  
    /**
     * Initialization of all classes in the project.
     */
    pointcut classInitializer() :
    	staticinitialization(my.project..*) &&
        !within(Logging);

    /**
     * Execution body for all methods.
     */
    pointcut method():
        (
          execution(my.project..*.new(..)) ||
          execution(* my.project..*.*(..))
        )

  && !within(my.project.D.*) 
        && !within(Logging);

    /**
     * Exception handling blocks inside all methods.
     */
    pointcut methodError():
        handler(handler(Throwable+) &&
        !handler(InterruptedException+) &&
        within(my.project..*.*) &&
        !within(my.project.D.*) &&
        !within(Logging);

    /*
     * Join points
     */

    /**
     * After the initialization for all classes in this project.
     */
    after(): classInitializer() {
    	String classname = thisJoinPointStaticPart.getSourceLocation().getWithinType().getName();
    	trace = Logger.getLogger("trace." + classname);
    }
    
    /**
     * Entry trace statements for all methods.
     */
    before(): method() {
        if (trace.isLoggable(Level.FINER)) {
            trace.entering(
                    thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
                    thisJoinPointStaticPart.getSignature().toString(), 
                    thisJoinPoint.getArgs());
        }
    }

    /**
     * Exit trace statements for all methods.
     */
    after() returning (Object result): method() {
        if (trace.isLoggable(Level.FINER)) {
            trace.exiting(
                    thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(), 
                    thisJoinPointStaticPart.getSignature().toString(),
                    result);
        }
    }

    /**
     * Exception handling blocks inside all methods.
     */
    before(): methodError() {
        if (trace.isLoggable(Level.FINER)) {
            Object target = thisJoinPoint.getArgs()[0];
            trace.logp(Level.SEVERE, 
                    thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(), 
                    thisJoinPointStaticPart.getSignature().toLongString(), 
                    "Caught exception: " + target.getClass().toString(), 
                    (Throwable)target);
        }
    }
  
}

AspectJ for Java Logging: Individual tracing control per Java package - Part 5

2009-04-07T07:10:00.001-07:00

In "AspectJ for Java logging: Serviceability without the clutter - part 2" I had some difficulty in assigning a different trace handler for each class, which severely limited the application of the "Logging" aspect on larger programs. After all, it does not make sense to enable verbose trace on method entry/exit for all modules when debugging a single module.

A few minutes ago, some more reading solved the problem: one can use the "pertypewithin" aspect declaration, like this:

public aspect Logging pertypewithin(my.project..* && !Exception+){

    /**
     * Trace handler for each type.
     */
    private static Logger trace = null;

    /**
     * Initialization of all classes in the project.
     */
    pointcut projectClassInitializer() :
        staticinitialization(my.project..*) &&
        !within(Logging);

    /**
     * After the initialization of all classes in this project.
     */
    after(): projectClassInitializer() {
    	String classname = thisJoinPointStaticPart.getSourceLocation().getWithinType().getName();
    	trace = Logger.getLogger("trace." + classname);
    }
    
    ...

}

Now, the pointcut "projectClassInitializer" will pick out the static declaration of all Java classes within the project. Exceptions declared in the project are left out, as I do not see usefulness in instrumenting such basic classes, but that is a matter of preference.

The "after" advice will guarantee that the "trace" handler is initialized at the end of the static initialization for each class, using a handle named "trace.<classname>".

With this arrangement, it is now possible to configure different tracing levels within the logging.properties file for your java application, setting a different level for an entire package or for a single class, like this:

handlers = java.util.logging.ConsoleHandler
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

trace.my.level = INFO
trace.com.ibm.project.module1.level = INFO
trace.com.ibm.project.module2.level = FINEST
trace.com.ibm.project.module2.ClassA.level = FINER
...

-----

AspectJ for Java logging: Serviceability without the clutter - Instrumenting a 3rd party library - part 4

2009-04-03T06:00:00.000-07:00

Another common serviceability problem while assembling libraries from multiple sources is that sometimes a reused library may use a difference serviceability framework, or even worse, not have any serviceability at all.

In the previous entries I covered techniques to instrument your own source code and source code from a different contributor. Now it is time to cover a technique to cover 3rd party libraries.

With AspectJ, this is a simple task accomplished with the AspectJ compiler: ajc. The compiler parameters are covered in the ajc page of the AspectJ developer's guide, but I suspect the majority of the people building Java code will resort to an Ant script. AspectJ has an Ant task called iajc, from where you can execute the same commands.

----

Compiling your aspects

The first step is, of course, to compile the serviceability aspects covered in the previous entries.

<iajc destdir="${dir.build.classes}" classpathref="class.path" deprecation="${javac.deprecation}">
    <sourceroots>
        <pathelement location="${dir.src}"/>
        <pathelement location="${aspects.path}"/>
    </sourceroots>
</iajc>

where "dir.src" is the directory where the project source code is located and "aspects.path" is the source directory where the aspects are located

----

Instrumenting a 3rd party library

The Ant taks has to be slightly modified to reflect a JAR file as the type of input and output, like this:

<iajc outJar="${dir.build.lib}/3rdparty.jar" classpathref="class.path" deprecation="${javac.deprecation}">
  <injars>
        <pathelement location="${3rdparth.installdir}/libs/3rdparty.jar"/>
    </injars>
    <sourceroots>
        <pathelement location="${aspects.path}"/>
    </sourceroots>
</iajc>

----

And you are done! If both the JSR-47 and the Log4J aspects are in place, not only your new "3rdparty.jar" file will be instrumented with serviceability trace statements, it will also replace all extraneous Log4J calls with calls to their equivalent in JSR-47.

That is a very good result, considering that the resulting application assembled from multiple sources and libraries will benefit from these desirable serviceability traits:

Consistent tracing, with trace entries for all the method entry and exit points and for all catch blocks

Consistent trace control, with a single JSR-47 logging.properties file for all components

Consistent output, with all modules directing their tracing output to the same file.

AspectJ Development Tools - Inline aspect visualization inside Eclipse

2009-03-30T13:22:00.001-07:00

As I wrote about using AspectJ for serviceability instrumentation, I thought I would also spend some time publishing a couple of screenshots of a great addition to your Eclipse environment.

It is called AspectJ Development Tools, or AJDT, for short. AJDT adds a perspective and a handful of views that make it easy to visualize how the aspects are cross-cutting your code base.

Installation

Your first step is to visit the AJDT web site, go to the "Downloads" page and determine the right level of AJDT for your Eclipse environment. For those using any of the Rational Software Development v7.0 siblings, such as Rational Software Architect, you are looking into the 3.2 version.

The installation of the plugin follows the standard Eclipse "Help->Software Updates->Find and Install..." sequence, where you will be able to register the Eclipse update side for AJDT.

Converting a Java project into an AspectJ project

You will need to convert Java projects into AspectJ projects before you can use Eclipse to apply aspects to your Java code. The "conversion" is fairly benign and reversible, adding a couple of facets to the ".project" file.

An "AspectJ" sub-menu will be displayed whenever you right-click any Java project, with a single and unmistakable option named "Convert to AspectJ Project". After the conversion, other options become available, including the action to undo the conversion.

Aspect visualization embedded into Java code

The AJDT extensions will show markers to the left of Java source code,with the icons indicating the type of join point, such as "around", "before" and "after". Note that you can also display the "Cross References" view of the advices being applied to a particular point in the code.

Click on the thumbnail to see a larger image

Simultaneous Aspect visualization for multiple files

Using the Aspect Visualization perspective, you can have a broader view into how the aspects are crosscutting your projects.
Note how the screen is logically divided in three parts, with the package selection on the left, a graphical representation of the advices for each class in the middle section, and a selector for the aspects you want to browse.

What I like the best is that all screen elements are fully navigable, with double-clicks to the classes or advices in the graphical display taking you to their respective location in the Java source code.

Click on the thumbnail to see a larger image

AspectJ for Java logging: Serviceability without the clutter ("around" we go) - part 3

2009-03-16T06:28:00.000-07:00

Whenever I reuse someone else's code at the source level, I often discover that it uses some different logging toolkit than what I am using.
Log4J seems to take the prize because a lot of developers used it before JSR-47 came out, and some **still** use Log4J in defiance of JSR-47's release.
JRAS, from older versions of WebSphere, also comes to mind.

At any rate, combining two different log toolkits produces some undesirable results, mostly (1) two different configuration steps and (2) two different file outputs. You can add a new handler to Log4J to redirect its calls to solve problem "2", but "1" is still there rearing its ugly head.

AspectJ allows one to replace calls to a given method with different calls. You got it, how about an Aspect that replaces all Log4J calls with JSR-47 calls?

The alternative? Ripping through every single method in the second code-base to replace Log4J calls with JSR-47 calls, but it is very likely that the original code owner will not support your forked code-base. Yes, I don't like it either, and that is why I wrote this other aspect for a recent project.

There are ways of applying this technique to an existing JAR file if you are reusing libraries instead of source code. Theme for the next posting.

----

package my.project;

import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Aspect used to wrap Log4J to ensure consistent logging throughout the entire project.
 * 
 * @author Denilson Nastacio
 */
public aspect Log4J {

    private static final Logger trace = Logger.getLogger("trace.my.project");

    /*
     * Pointcuts
     */

    /**
     * Pointcut for all log4j calls within the target module
     */
    pointcut log4jCalls():
        target(org.apache.commons.logging.Log) &&
        within(my.someone.else.code*.*);

    /**
     * Pointcuts for isInfoEnabled calls.
     */
    pointcut log4jIsInfoEnabled(): 
    	log4jCalls() &&
        call(boolean isInfoEnabled());

    /**
     * Pointcuts for isTraceEnabled calls.
     */
    pointcut log4jIsTraceEnabled():
    	log4jCalls() &&
        call(boolean isTraceEnabled());

    /**
     * Pointcuts for isDebugEnabled calls.
     */
    pointcut log4jIsDebugEnabled():
    	log4jCalls() &&
        call(boolean isDebugEnabled());

    /**
     * Pointcuts for isWarnEnabled calls.
     */
    pointcut log4jIsWarnEnabled():
    	log4jCalls() &&
        call(boolean isWarnEnabled());

    /**
     * Pointcuts for isErrorEnabled calls.
     */
    pointcut log4jIsErrorEnabled():
    	log4jCalls() &&
        call(boolean isErrorEnabled());

    /**
     * Pointcuts for isFatalEnabled calls.
     */
    pointcut log4jIsFatalEnabled():
    	log4jCalls() &&
        call(boolean isFatalEnabled());

    /**
     * Pointcuts for info calls.
     */
    pointcut log4jInfo(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void info(Object));
    pointcut log4jInfoEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void info(Object,Throwable));

    /**
     * Pointcuts for trace calls.
     */
    pointcut log4jTrace(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void trace(Object));
    pointcut log4jTraceEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void trace(Object,Throwable));

    /**
     * Pointcuts for debug calls.
     */
    pointcut log4jDebug(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void debug(Object));
    pointcut log4jDebugEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void debug(Object,Throwable));

    /**
     * Pointcuts for warn calls.
     */
    pointcut log4jWarn(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void warn(Object));
    pointcut log4jWarnEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void warn(Object,Throwable));

    /**
     * Pointcuts for error calls.
     */
    pointcut log4jError(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void error(Object));
    pointcut log4jErrorEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void error(Object,Throwable));

    /**
     * Pointcuts for fatal calls.
     */
    pointcut log4jFatal(Object o):
    	log4jCalls() &&
        args(o) &&
        call(void fatal(Object));
    pointcut log4jFatalEx(Object o, Throwable ex):
    	log4jCalls() &&
        args(o,ex) &&
        call(void fatal(Object,Throwable));

    /*
     * Join points
     */

    /**
     * Replace calls to Log.isInfoEnabled
     */
    boolean around(): log4jIsInfoEnabled() {
        if (trace.isLoggable(Level.INFO)) {
        	return true;
        } else {
        	return false;
        }
    }

    /**
     * Replace calls to Log.isTraceEnabled
     */
    boolean around(): log4jIsTraceEnabled() {
        if (trace.isLoggable(Level.FINER)) {
        	return true;
        } else {
        	return false;
        }
    }

    /**
     * Replace calls to Log.isDebugEnabled
     */
    boolean around(): log4jIsDebugEnabled() {
        if (trace.isLoggable(Level.FINEST)) {
        	return true;
        } else {
        	return false;
        }
    }

    /**
     * Replace calls to Log.isWarnEnabled
     */
    boolean around(): log4jIsWarnEnabled() {
        if (trace.isLoggable(Level.WARNING)) {
        	return true;
        } else {
        	return false;
        }
    }

    /**
     * Replace calls to Log.isErrorEnabled
     */
    boolean around(): log4jIsErrorEnabled() || log4jIsFatalEnabled() {
        if (trace.isLoggable(Level.SEVERE)) {
        	return true;
        } else {
        	return false;
        }
    }

    /**
     * Replace calls to Log.info
     */
    void around(Object o): log4jInfo(o) {
        if ("".equals(o) == false) {
        	trace.logp(Level.INFO, 
        			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
        			thisJoinPointStaticPart.getSourceLocation().toString(),
        			o.toString());
        }
    }
    void around(Object o, Throwable ex): log4jInfoEx(o, ex) {
        trace.logp(Level.INFO, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString(), ex);
    }

    /**
     * Replace calls to Log.trace
     */
    void around(Object o): log4jTrace(o) {
        trace.logp(Level.FINER, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString());
    }
    void around(Object o, Throwable ex): log4jTraceEx(o, ex) {
        trace.logp(Level.FINER, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString(), ex);
    }

    /**
     * Replace calls to Log.debug
     */
    void around(Object o): log4jDebug(o) {
    	trace.logp(Level.FINEST, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString());
    }
    void around(Object o, Throwable ex): log4jDebugEx(o, ex) {
    	trace.logp(Level.FINEST, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString(), ex);
    }
    
    /**
     * Replace calls to Log.warn
     */
    void around(Object o): log4jWarn(o) {
    	trace.logp(Level.WARNING, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString());
    }
    void around(Object o, Throwable ex): log4jWarnEx(o, ex) {
    	trace.logp(Level.WARNING, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString(), ex);
    }
    
    /**
     * Replace calls to Log.error and Log.fatal
     */
    void around(Object o): log4jError(o) || 
                            log4jFatal (o) {
    	trace.logp(Level.SEVERE, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString());
    }
    void around(Object o, Throwable ex): log4jErrorEx(o, ex) || 
                                          log4jFatalEx(o,ex) {
    	trace.logp(Level.SEVERE, 
    			thisJoinPointStaticPart.getSourceLocation().getWithinType().getName(),
    			thisJoinPointStaticPart.getSourceLocation().toString(),
    			o.toString(), ex);
    }
    
}

AspectJ for Java logging: Serviceability without the clutter - part 2

2009-03-13T05:05:00.001-07:00

In the previous entry about an Aspect for Java logging, I forgot to add a higher-level picture of the end-results.

Let's say your Java project has 4 major packages:

my.otherproject.A
my.project.B
my.project.B.parsers
my.project.C

With the Java logging aspect added to the code base, you can invoke your program with the standard Java logging option:

java -Djava.util.logging.config.file=<logging.properties> application.class

where <logging.properties> is a standard Java logging configuration file.

You can read more about the structure of this file in the Java Logging Overview, but here is an example of what I use:

# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
# By default we only configure a ConsoleHandler, which will only
# show messages at the INFO and above levels.
handlers = java.util.logging.ConsoleHandler

# To also add the FileHandler, use the following line instead.
#handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

# Default global logging level.
# This specifies which kinds of events are logged across all loggers.  
# For any given facility this global level can be overriden by a facility 
# specific level.
# Note that the ConsoleHandler also has a separate level
# setting to limit messages printed to the console.
trace.my.level = INFO
trace.my.project.level = FINER

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = project%u.%g.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 5
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level = FINEST
java.util.logging.FileHandler.append  = false

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

-----

Since the Java logging handles are hierarchical, the declaration of "trace.my.level = INFO" sets the default to all packages, whereas the declaration "trace.my.project.level = FINER" entry sets a different tracing level for your instrumented classes under the "my.project" Java package.

Dealing with verbose classes

One can tweak the "method" join point to exclude verbose classes from the tracing aspect, along the lines of:

    pointcut method():

        execution(* my.project..*.*(..)) &&

        !within(my.project.D.*) &&

        !within(Logging) && 

  
        !within(excluded.class.1) && 

  
        !within(excluded.class.2) &&

!within(excluded.class.n);

Dealing with methods inside loops

This point is a bit more complicated and I'll get to it in a different post.

Dealing with timestamps in BIRT reports

2009-03-10T12:01:00.001-07:00

While trying to match date/time fields between a BIRT (Business Intelligence and Reporting Tools) report design file and a web service, I did not stumble upon any good tips on the BIRT Eclipse website, but eventually found this entry on the BIRT Exchange website: Convert String Date to Date Object in BIRT.

The example was not a perfect match for what I needed but threw me close enough to the solution.

The web service returns a long value corresponding to the time using the Java/C convention for milliseconds since Jan/1/1970 0:00:00 GMT”. Inside the BIRT data-set though, I could not find the “Timestamp” field available for other kinds of data-sources, such as the XML data-source. Returning a string representing the date and time is never a good strategy since it discards the time zone information.

The solution was to create a computed field with “Date Time” type, then use this expression derived from the article to convert the milliseconds value retrieved from the web service (originally named “Date”):

df = new Packages.java.util.Date();
df.setTime(row["Date"]);
df

The next step was to indicate the correct type for the new computed parameter “DateTime” in my chart:

AspectJ for Java logging: Serviceability without the clutter - part 1

2009-03-03T19:17:00.001-08:00

I have grown fond of AspectJ in the past years, probably at the same rate I have grown tired of writing or referencing the same cross-cutting snippets of code all over the code-base of a project.

In the way of background, AspectJ is a Java extension for "Aspect Oriented Programming" (PDF download), or AOP for short.

You can read the entire background in the previous link, but in a nutshell, AOP allows you to abstract common code snippets (advices, in AspectJ lingo) that are executed on common points of the code-base (join points.)

As a concrete example, I'll reference an Aspect that I have been perfecting on my last three projects: adding debugging trace statements to the entry/exit of all methods in a project.

I won't lie to you, it is not a trivial technique and the average Java programmer who eventually inherits your code base will hate your guts.

Setup your environment

Using the Eclipse environment and the AJDT (AspectJ Development Tools) is almost mandatory when dealing with aspects in Java. If you already have one of the Rational Software Development Platform siblings installed on your machine, such as Rational Software Architect, you are in good shape too, just pay attention to their underlying Eclipse version in order to select the right level of AJDT.

Since this is not an Eclipse primer, I assume you know how to deal with installation of plugins from update sites.

Trace statements

If you want somewhat decent traceability, you should look into three types of statements:

Method entry:

    if (trace.isLoggable(Level.FINER)) {         trace.entering(<CLASS_NAME>, <METHOD_NAME>, <args> ) ;     }

Method exit:

    if (trace.isLoggable(Level.FINER)) {         trace.exiting(<CLASS_NAME>, <METHOD_NAME>, <args> ) ;     }

Exception handling:

    catch (<EXCEPTION_CLASS> e) {         trace.logp(Level.SEVERE,<CLASS_NAME>, <METHOD_NAME>,                    "Caught exception: " + e.getClass().toString(),                    e);     }

The Logging aspect

This is also not a primer on AspectJ, so that I assume you know that aspects go inside an "Aspect" file sitting inside any regular folder corresponding to a Java package. Here is what I have for trace.

package my.project.aspects;

import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Aspect for Java logging throughout the code base.
 */
public aspect Logging {

    private static Logger trace = Logger.getLogger("trace.my.project");

    /*
     * Pointcuts
     */
    
  
    /**
     * Execution body for all methods.
     */
    pointcut method():
        execution(* my.project..*.*(..)) && 
        !within(my.project.D.*) &&
        !within(Logging);

    /**
     * Exception handling blocks inside all methods.
     */
    pointcut methodError(Throwable t):
        args(t) &&
        handler(Throwable+) &&
        within(my.project..*.*) &&
        !within(my.project.D.*) &&
        !within(Logging);

    /*
     * Join points
     */

    /**
     * Entry trace statements for all methods.
     */
    before(): method() {
        if (trace.isLoggable(Level.FINER)) {
            trace.entering(
                    thisJoinPointStaticPart.getSignature().getDeclaringTypeName(), 
                    thisJoinPointStaticPart.getSignature().toString(), 
                    thisJoinPoint.getArgs());
        }
    }

    /**
     * Exit trace statements for all methods.
     */
    after() returning (Object result): method() {
        if (trace.isLoggable(Level.FINER)) {
            trace.exiting(
                    thisJoinPointStaticPart.getSignature().getDeclaringTypeName(), 
                    thisJoinPointStaticPart.getSignature().toString(),
                    result);
        }
    }

    /**
     * Exception handling blocks inside all methods.
     */
    before(Throwable t): methodError(t) {
        if (trace.isLoggable(Level.SEVERE)) {
            trace.logp(Level.SEVERE, 
                    thisJoinPointStaticPart.getSignature().getDeclaringTypeName(), 
                    thisJoinPointStaticPart.getSignature().toLongString(), 
                    "Caught exception: " + t.getClass().toString(), 
                    t);
        }
    }
  
}

Advanced reading

In the way of advanced reading, one can browse through developerWorks excellent AOP@Work series.

I particularly like "Next Steps with Aspects" and "AOP Myths and Realities".