wicketstuff-annotation

Introduction

The wicketstuff-annotation library is used to mount your pages declaratively via Java annotations instead of programatically via mount() calls in your WebApplication.init() method.

Quick Overview

A typical wicket application might have several pages mounted like the following:

public class MyWicketApplication extends WebApplication
{
    @Override
    protected void init()
    {
        mountBookmarkablePage("terms", Terms.class);
        mount(new MixedParamUrlCodingStrategy("dogs", Dogs.class,
                                              new String[] {"sport", "show"}));
    }
}

With wicketstuff-annotation, you annotate each page like this:

@MountPath(path = "terms")
public class Terms extends WebPage { ... }

@MountPath(path = "terms")
@MountMixedParam(parameterNames={"sport", "show"})
public class Dogs extends WebPage { ... }

And use the AnnotatedMountScanner in your init method like this:

public class MyWicketApplication extends WebApplication
{
    @Override
    protected void init()
    {
        new AnnotatedMountScanner().scanPackage("com.acme.wicket.pages").mount(this);
    }
}

Why

This library was created because of the desire for the following capabilities:

• The ability to encapsulate how a page is mounted with the code for the page itself
• Remove the need to edit the WebApplication class each time a new page is added.

Java annotations and class-path scanning are a good way to achieve these goals.

Note: Not all developers like the use of annotations and not all Wicket applications may benefit from this library. Our goal is to offer a nice alternative way to address the need to mount pages in wicket in order to create nice URLs.

How it Works

The AnnotatedMountScanner does all the work. It uses another wicketstuff-annotation class, MatchingResources to scan the class path looking for classes annotated with @MountPath. See the MatchingResources section for details on this class.

The entire class path is not necessarily scanned. You can limit what packages to look in. In the example above, only classes under com.acme.wicket.pages are searched. The class path scanning is very efficient by itself and limiting the search only makes it faster.

The @MountPath annotation specifies the primary and alternate paths that the page should be mounted on. The primary path is the one chosen when Wicket maps a page to a path. The primary and alternate paths are used when Wicket maps paths back to pages.

The next step is to determine which URL encoding strategy to use. Unless one is explicity specified, the default used is BookmarkablePageRequestTargetUrlCodingStrategy. In the example above, the Terms page uses the default.

You can explicitly define one by using one of the strategy-specific annotations. In the example above, the Dogs page uses the @MountMixedParam annotation which is associated with the MixedParamUrlCodingStrategy strategy. There is an annotation for each page-specific strategy that comes with Wicket (see next section).

Strategy Annotations

The following table lists the strategy-specific annotation in wicketstuff-annotation and the corresponding strategy class:

You can define your own annotation. The Javadoc explains this in more detail. The best way to implement your own is to follow the example of an existing annotation.

MatchingResources

Matching is done via Spring's PathMatchingResourcePatternResolver class. This means that wicketstuff-annotation has a dependency on Spring. When we build, we use spring-core 2.5.2, but this class has been part of Spring since 1.0.2, so MatchingReources should work with almost any version of Spring.

The MatchingResources class is useful for finding any resources on the path. It was adapted from Donohoe Digital's core architecture and contributed as part of this library. Technically, it does not depend on wicket, so it could at some point be moved into another package.

The wicketstuff-annotation project uses the getAnnotatedMatches() method to find classes with the @MountPath annotation. Note that Spring does not load the class to determine this information. Instead, it uses a meta-data reader to determine this (which is faster than going through class loading).

Maven

To get wicketstuff-annotation via maven, you need to specify the wicketstuff repository:

<repositories>
  <repository>
    <id>wicket-snaps</id>
    <url>http://wicketstuff.org/maven/repository</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
    <releases>
      <enabled>true</enabled>
    </releases>
  </repository>
</repositories>

And include this dependency:

<dependency>
  <groupId>org.wicketstuff</groupId>
  <artifactId>wicketstuff-annotation</artifactId>
  <version>1.0</version>
</dependency>

Direct Download

You can download directly from the wicketstuff repository

• wicketstuff-annotation.jar
• source code
• javadoc

Source Code

You can browse the source or get the source using subversion:

$ svn co http://wicket-stuff.svn.sourceforge.net/svnroot/wicket-stuff/trunk/wicketstuff-annotation

Javadoc

Browse wicketstuff-annotation javadoc hosted courtesy of DD Poker and Donohoe Digital LLC

Dependencies

• jdk 1.5 or higher (because we use annotations and generics)
• spring-core 2.5.2 (what we tested with, but earlier versions of spring should work)
• wicket 1.3.3 (haven't tested with 1.4 pre-release yet, but should work)

License

Just like Wicket itself, the wicketstuff-annotation library is licensed under Apache 2.0.

Projects Using wicketstuff-annotation

DD Poker Online Games Portal

Author

Doug Donohoe of Donohoe Digital LLC is the author of wicketstuff-annotation. He can be reached at doug (at) donohoe (dot) info.