Applied number theory

Mark Dominus writes great geek stuff in The Universe of Discourse.  Yesterday, based on feedback by Mauro Persano, he wrote about a brilliant solution to finding simple fractions, a topic that he started already earlier.  Clever, simple, and fast!



I wonder if I could apply the same idea in some of the hierarchical storage models I've been thinking about lately...

ApacheCon proposals

ApacheCon US 2006 was the first ApacheCon I attended, and I went there mostly to look around and get a feeling of the event. Encouraged by the good reception of my ad-hoc presentations there, I wanted to step up and propose some real sessions for the next ApacheCon. Thus, my proposals for ApacheCon Europe 2007 are:

• Up to Speed with Java Content Repository API and Jackrabbit
  Joint session with Alexandru Popescu. Targeted for people interested in content management with JCR and Jackrabbit.


• Structure and Implementation of Apache Jackrabbit
  A walktrough of the Jackrabbit internals. Not just for Jackrabbit developers but for anyone who is interested in seeing a reasonably complex codebase explained using various analysis and diagramming methods (like DSM).

I also proposed a half-day tutorial on JCR content management, and we'll probably arrange an informal Jackrabbit BOF during the event.

Excluding the publish date from Maven 2 sites

The Maven 2 site plugin includes by default a "Last Published" note on each HTML page. This is a nice feature for sites that are directly deployed to the server, but a bit troublesome for projects like Jackrabbit that first commit the generated site to version control before publishing it. The "Last Published" note tags all generated pages as modified even if no content changes are made.

To solve this issue I looked at the <publishDate/> configuration option in the site descriptor, but the only documented options for specifying the date location are left, right, navigation-top, navigation-bottom, and bottom. There is no option to simply disable the date being inserted in the document.

Looking at the default page template I however noticed that it's possible to trick the site not to include the publish date by using a dummy location like "none":

<publishDate position="none"/>

Works for me. :-) I also requested documenting this to avoid the hack getting broken in some future Maven version.

Introducing Apache Jackrabbit

The past week at the ApacheCon has been a great opportunity to introduce the Apache Jackrabbit project to the Apache community. I've spoken with a number of people about the project, found areas of possible co-operation, and met with potential Jackrabbit users from various projects and companies. A very successful week.

The Media & Analyst Training tutorial on Tuesday and the Breaking Through the Noise: Visibility for your Open Source Project session on Thursday, both by Sally Khudairi, gave a lot of ideas about better introducing the project to a large audience. The first step in applying those ideas in practice was making the introductory paragraph on the Jackrabbit web site a bit more accessible to first-time visitors. The updated introduction is:

Apache Jackrabbit is a fully conforming implementation of the Content Repository for Java Technology API (JCR). A content repository is a hierarchical content store with support for structured and unstructured content, full text search, versioning, transactions, observation, and more. Typical applications that use content repositories include content management, document management, and records management systems.

I got scheduled for a Feather Cast interview with David Reid. The podcast is available as the Feather Cast Episode 17. I also gave two talks on Jackrabbit, one at the Incubator 15 minute talks (even though Jackrabbit already graduated) on Thursday and one at an ad-hoc press session on Friday. Check out my introductory Apache Jackrabbit slideshow.

Apache logo guidelines

The Apache Jackrabbit website was recently given a nice face-lift, but the customized "Apache Software Foundation" logo image caused some controversy and was considered unacceptable for two reasons. The first complaint was that it doesn't contain the "The" of "The Apache Software Foundation", and second that the feather was not the standard ASF feather.

Both are valid concerns, and while the designer did add the "The", the feather issue is still not resolved. So for now we're back to using the ASF logo image (shown above) we used before. Unfortunately this image is considerably larger, and causes trouble to the new website layout. Instead of putting the site layout back to the drawing board I set out to find out the acceptable alternatives. Is it OK if we just replace the custom feather with a scaled and rotated version of the official feather? What are the branding and logo usage guidelines? What exactly is the official ASF feather?

Unfortunately there are no existing ASF logo guidelines, and in practice the logo usage varies wildly between Apache projects. In fact I couldn't even find out what actually is the official trademarked ASF feather, since the one in the above logo image is quite different from the version (shown right) used in a customized format for example on the "canonical" Apache HTTPD web site.

There's also great variance in the ways different Apache projects display their affiliation with the ASF. The most notable example are the iBatis project, that mentions the foundation only at the very bottom of their front page, and mod_perl, that mentions the foundation but doesn't display any version of the feather logo. The Xerces and Geronimo projects hide the ASF feather into a blue background, and projects like Lenya, SpamAssassin, and TCL customize the ASF feather in various ways in their project logos. This variance is not necessarily bad, in fact it shows a good level of innovation in using the ASF brand :-), but I'm not sure if this wild practice is too good either.

It has been noted on various forums that Apache is a strong brand that really brings value and recognition to individual Apache projects. Thus I think it is in the foundation's interest to guard and strengthen that brand, including the visual identity bound to the Apache feather. The reaction to the custom feather introduced by the Jackrabbit site face-lift is a sign of such a drive, but the effort falls short if there are no guidelines to direct projects and external parties to the correct use of the feather logo.

I think the following are the key questions to answer when creating logo usage guidelines for Apache projects:

• Should an Apache project display the Apache Software Foundation logo?


• If yes, what are the standard logo images to use?


• Is it acceptable to customize the standard logo images?


• If yes, what are the accepted customizations (scaling, rotating, drop shadow, text overlays, background color, background image, etc.)?

There are also unanswered questions on whether and how an Apache project should incorporate the ASF feather into a project logo:

• May an Apache project logo contain the Apache feather?


• If yes, should an Apache project logo contain the Apache feather?


• If yes, what is (are) the standard feather(s) to use?


• Is it acceptable to customize the standard feather(s)?


• If yes, what are the acceptable customizations?

JUnit tests for known issues, part 3

My quest for a way to handle known issues as JUnit tests seemed already finished, when Marcel Reutegger, a committer of the Apache Jackrabbit project and a developer of the Technology Compatibility Kit (TCK) of JSR 170, displayed some serious JUnit-fu by pointing to the TestResult class in JUnit.

It turns out that JUnit creates a TestResult instance for each test being run and uses that instance to store the test results. It is possible to customize the TestResult being used by overriding the TestCase.createResult() method. You can then decide in TestResult.addFailure(Test, AssertionFailedError) and TestResult.addError(Test, Throwable) whether to skip some failure or error reports. This is what we ended up doing in Jackrabbit.

Digging deeper along these lines I found out that you could actually implement similar functionality also directly in a TestCase subclass, thus avoiding the need to override TestCase.createResult(). The best way to do this is to override the TestCase.runBare() method that gets invoked by TestResult to run the actual test sequence. The customized method can check whether to skip the test and just return without doing anything in such cases.

I implemented this solution as a generic JUnit 3.x ExcludableTestCase class, that you are free to copy and use under the Apache License, version 2.0. The class uses system properties named junit.excludes and junit.includes to determine whether a test should be excluded from the test run. Normally all tests are included, but a test can be excluded by including an identifier of the test in the junit.excludes system property. An exclusion can also be cancelled by including a test identifer in the junit.includes system property. Both system properties can contain multiple whitespace-separated identifiers. See the ExcludableTestCase javadocs for more details.

You can use this class by subclassing your test cases from ExcludableTestCase instead of directly from TestCase:

package my.test.package;
public class MyTestCase extends ExcludableTestCase {
    public void testSomething() {
        // your test code
    }
}

You can then exclude the test case with -Djunit.excludes=my.test.package, -Djunit.excludes=MyTestCase, or -Djunit.excludes=testSomething or a combination of these identifiers. If you've for example excluded all tests in my.test.package, you can selectively enable this test class with -Djunit.includes=MyTestCase.

You can also add a custom identifiers to your test cases. For example, if your test case was written for Bugzilla issue #123, you can identify the test in the constructor like this:

    public MyTestCase(String name) {
        super(name);
        addIdentifier("#123");
    }

Then you can exclude tests for this issue with -Djunit.excludes=#123.

Jira tips and tricks

Having just filed a number of Graffito issues in the Jira installation at the ASF, I figured it might be useful if I shared some of the tips and tricks I've learned as a relatively heavy user of Jira. Here comes:

• You can personalize your Dashboard page to show all sorts of custom reports and statistics. I've configured mine to show summary statistics for all the projects I'm involved with and to list all the open issues assigned to me along with some generally useful links.


• When navigating back and forth over a number of related issues, click the "History" link on the top-right corner to access all the recently visited issues.


• You can configure the number of issues listed per page by editing your preferences on your profile page. I've set my preferences to 100 issues per page to avoid having to page back and forth over long issue lists.


• On the same preference editor you can also disable the feature that sends you an email notification of all the actions you've made on the web interface. I usually get those notifications anyhow through the issue mailing lists, so there's no need for duplicates.


• The "Road Map" tab on a project page gives a nice overview of the TODO's for an upcoming release.


• There's a "Subversion commits" tab on the issue pages that lists all commits whose commit message includes the key of the respective issue. There are even links to the ViewVC interface. Very useful! The "All" tab shows you both the issue comments, metadata changes, and Subversion commits on a single time-line.


• When opening an issue from the Issue Navigator, the upper right corner of the issue contains a small box that allows you to "Return to search" or to jump directly to the "Previous" or "Next" issue on the list.


• You can "Configure" the Issue Navigator to customize the set of columns it displays. I've replaced the default "Bugzilla Id" column with the "Components" column.


• You can customize any issue search by clicking "Edit" in the top left corner of the Issue Navigator. You can also save such customized filters for future use.


• You can subscribe the results of any query in your favourite feed aggregator.

There are probably a ton of other nice features that I haven't yet noticed.