Migrating to Wicket 1.5

Environment

• Wicket 1.5 requires at least Java 5

(RC1) Upgraded to Servlet API 2.5

In order to stay with the times, we have upgraded the minimal requirements for servlet specifications to servlet API 2.5.

(RC1) Maven users are recommended to depend on org.apache.wicket:wicket-core:jar from now on

(RC2) All standard (form) validators now extend Behavior.

This allows them to contribute to the component's markup, e.g. provide client-side validation.

org.apache.wicket:wicket:jar combines the classes from org.apache.wicket:wicket-core:jar, org.apache.wicket:wicket-util:jar and org.apache.wicket:wicket-request:jar. wicket.jar is recommended for users which don't use dependency management tools (like Maven, Ivy, Gradle, ...).
Maven users still can depend on org.apache.wicket:wicket:jar but this way they will not be able to automatically download sources and javadoc for this module.

Upgraded to JUNIT4

We changed the root pom.xml to use junit4 (4.7)

Removed deprecated method, class and interface definitions

In order to keep the code clean, we removed all methods, classes and interfaces which were marked deprecated in Wicket 1.4. Before migrating to Wicket 1.5 you should replace all deprecated invocations.

Removed FormComponent.setPersistence()

WICKET-2213: At the very beginning of Wicket we introduced FormComponent.setPersistence() with the idea to make creating Login panels very easy. Basically Wicket would deal with the Cookie handling for the login details. Now some years later it is evident that this feature is not very useful:

• It basically is used for login panels only
• Even in our examples Password.setPersistence is false which means that "rememberMe" doesn't really work. Only the user name is stored in a Cookie
• Forcing formComponent.getPageRelativePath() as the Cookie name is too restrictive
• You can not combine username and password into a single Cookie and e.g. decrypt it for safety reasons

So we removed that feature and introduced IAuthenticationStrategy. A default implementation has been provided and the examples have been updated. As usual it gets registered with ISecuritySettings.

In case you want to implement your own IAuthenticationStrategy, a utility class org.apache.wicket.util.cookies.CookieUtils has been added.

Removed CompressedPackageResource

Since all modern java and web servers support compression of resources we dropped that feature from wicket. Usually servers not only support that feature but also are more flexible so there's no need for a redundant functionality that does not belong to a web framework but to the server itself.

StringResourceModel constructor argument order change

StringResourceModel has changed some of its constructors and modified the order of the arguments. The constructors with default values might introduce errors because the java compiler matches them, but their semantics have changed.

public StringResourceModel(final String resourceKey, final Component component,
       final IModel<?> model, final Object[] parameters, final String defaultValue)

Became:

public StringResourceModel(final String resourceKey, final Component component,
       final IModel<?> model, final String defaultValue, final Object... parameters)

If you used the 1.4 constructor, the compiler would now match the following (Wicket 1.5) constructor:

public StringResourceModel(final String resourceKey, final Component component,
	final IModel<?> model, final Object... parameters)

Where the Object[] array is matched to the first parameter of the ellipsis and the defaultValue as the second parameter.

Removed IComponentBorder

The interface has been removed since IBehavior can do exactly the same. MarkupComponentBorder has been migrated, which means you can add associated markup to the behavior. Markup which will surround the behavior's component.

Component.getStyle() implementation changed

getStyle() used to return Component.getVariation() + "_" + style. That eventually caused issue such as mentioned in WICKET-2298.

We changed that to getStyle() now returning style only which as a consequence required us to change all resource related APIs to add variation. To migrate your code you might either provide component.getVariation() or null where not relevant.

Removed magic from Border Component

We had several issues with Border such as WICKET-2494 and WICKET-3702 the fact that all over core you could find code such as "if (comp instanceof Border) {}" . That is now all fixed, though at a (low) price. Because the magic is now gone, we think it is even clearer than it was before. The difference is you have to tell Border where to add the child component. Whether it will be added to <wicket:border>..</wicket:border> which is called the "border", or <span wicket:id="myBorder">..</span> which called the "border body". And because the body can be wrapped by a container such as a Form, you need to add (move) the body to the wrapper component via wrapper.add(getBodyContainer()) if needed. By doing so you create a clean component hierarchy with no more magic and ambiguities and transparent resolvers.

border.add() will add to the border, while border.addToBody() is a convenient and explicit alias for border.getBodyContainer().add()

see Border javadoc as well

Component rendering

We used to have different entry points to render a Page, a Component for a web request and a Component for an AJAX request. That is history. Whenever you want to render a component, simply call component.render().

You may recall that Component.render(MarkupStream) already existed and thus in most cases (e.g. IComponentResolvers implementations) you simply need to remove the markupStream parameter.

The markup fragment which is still needed to render a Component is retrieved via Component.getMarkup(). Most components will ask their parent container to find it via MarkupContainer.getMarkup(Component child).

IMarkupFragment is a new concept introduced. A markup fragment is what is says: a fragment of markup taken from a larger resource (file). Please see the javadoc on when it is better to subclass getMarkup() and when getMarkup(Component).

Component.getMarkup() successfully returns a result as soon as it is connected (add) to a parent with an associated markup resource (file). Note that this usually is not in the component constructor, since the component itself will not yet been added to its parent.

You may recall that until now you very carefully had to forward the markup stream to the next suitable position. That has been simplified as well. Every component will use its own markup stream and the parent container is responsible to position it while rendering its child components.

On the same topic: onRender(MarkupStream) has been changed to onRender(); no more MarkupStream. You can get for every component once you called render() via getMarkupStream().

UTF-8 encoded property files

If you are using Java 6 or newer, than Wicket will be configured to use java.util.Properties#load(Reader(in, "utf-8")) for files with "*.utf8.properties" extension.

XML based property files

The file extension for xml based property files is changed from .xml to .properties.xml.
This way it is possible to use pages with XML markup type and xml based property files. Part of WICKET-2035.

TabbedPanel

• ITab.getPanel() now returns WebMarkupContainerWithAssociatedMarkup instead of Panel so it is now possible to create tabs using Fragments or Panels rather then just Panels.
• TabbedPanel.setSelectedTab() is now chainable
• TabbedPanel now takes a List<? extends ITab> rather then List<ITab>

MarkupContainer.isTransparentResolver() removed

We removed MarkupContainer.isTransparentResolver() in favor of the more general IComponentResolver. To mitigate the transition, we provide a TransparentWebMarkupContainer. But please note it does not solve all use cases isTransparentResolver() did.

There are several solutions for you. Your component may implement IComponentResolver itself and resolve the child component. The TransparentWebMarkupContainer implementation may serve as an example.

Noteable difference: different than MarkupContainer.isTransparentResolver() where the component id wasn't needed in the path (transparent), with IComponentResolver it must be included. Imagine you used to have a transparent container such as <body wicket:id="myBody">, where you were able to access a label from the Page just by "myLabel". In 1.5. you must use "myBody:myLabel".

Another solution might be to subclass MarkupContainer.add() like discussed in WICKET-3045.

The main reason why we removed MarkupContainer.isTransparentResolver() has been the magic necessary in Wicket's core and the number of issues/questions, where we identified isTransparentResolver() as the root cause. It all boils down to that with isTransparentResolver() the markup and component hierarchies get out of sync.

IComponentResolver.resolve API has changed

Until now, with IComponentResolver.resolve() it was your responsibility to render the component. You returned true, if the component was found and rendered. That was because we had different means to render the component and wicket itself was not able to judge which one to use. That has changed and thus we were able to change the IComponentResolver.resolve API. With the revised API, you simply return the resolved component and wicket core knows what to do with it. It made Wicket's internal code simpler and hopefully yours as well.

Wicket-IOC changes

InjectorHolder.getInjector().inject(Object object) is replaced with org.apache.wicket.injection.Injector.get().inject(Object object).
This is valid for both Wicket-Spring and Wicket-Guice.

Wicket-Guice's InjectionFlagCachingGuiceComponentInjector is removed. The replacement is GuiceComponentInjector. The caching mechanism that InjectionFlagCachingGuiceComponentInjector provided is moved to org.apache.wicket.injection.Injector so that the caching is re-used for both Wicket-Spring and Wicket-Guice.
Wicket-Guice no more supports method injection. The same could be achieved with field injection. This way it is the same as Wicket-Spring and the involved code is highly reused between the IOC projects.

Visitors

Visitors have been cleaned up. Dependency on magic return values defined in Component#IVisitor have been replaced with a Component#IVisit object that allows the visitor to control the flow of the traversal.

formComponent.visitChildren(Radio.class, new IVisitor<Component>()
{
	public /*[1]*/ Object component(Component component /*[2]*/)
	{
		if (value.equals(component.getDefaultModelObject()))
		{
			addFormComponentValue(formComponent,((Radio<?>)component).getValue());
			return STOP_TRAVERSAL; /*[3]*/
		}
		return CONTINUE_TRAVERSAL_BUT_DONT_GO_DEEPER; /*[4]*/
	}
});

formComponent.visitChildren(Radio.class, new IVisitor<Component, Void>()
{
	public void /*[1]*/ component(final Component component, final IVisit<Void> visit /*[2]*/)
	{
		if (value.equals(component.getDefaultModelObject()))
		{
			addFormComponentValue(formComponent,((Radio<?>)component).getValue());
			visit.stop(); /*[3]*/
		}
		else
		{
			visit.dontGoDeeper(); /*[4]*/
		}
	}
});

[1] The new style visitor no longer returns a value, instead the value can be returned using visit.stop(value)
[2] The new visit object is introduced to control the visitor traversal
[3] Instead of relying on magic return values the traversal is stopped by using the new visit object
[4] Same as [3] but a different method on IVisit is used

Component Initialization - Component#onInitialize

A new callback method was added to Component class - onInitialize(). This method is intended to provide an alternate place to initialize the component in addition to standard constructors. The advantage of using this method over a constructor is that when it is invoked the Page and the markup of the component are both available and so a more complex initialization can take place.

Before this method was introduced the developer had to rely on using onBeforeRender() method with some kind of "has-already-been-called-or-not" check to make sure the initialization code has only been run a single time. onInitialize() has this guarantee baked in - it will only be called once during the lifetime of the component.

Request parameters

To get the current request parameters (for example in Ajax behavior processing) in Apache Wicket 1.4:

    String parameterValue = RequestCycle.get().getRequest().getParameter(parameterName);

In 1.5 you have a better control where the parameter comes from:

   // GET request
   StringValue parameterValue = RequestCycle.get().getRequest().getQueryParameters().getParameterValue(parameterName);

   // POST request
   StringValue parameterValue = RequestCycle.get().getRequest().getPostParameters().getParameterValue(parameterName);

Or if you don't care about the method:

   StringValue parameterValue = RequestCycle.get().getRequest().getRequestParameters().getParameterValue(parameterName);

Switching to/from secured communication over https

In 1.4 a custom IRequestCycleProcessor is needed:

public class MyApplication extends WebApplication
{
 	@Override
 	protected IRequestCycleProcessor newRequestCycleProcessor()
  	{
  		return new HttpsRequestCycleProcessor(new HttpsConfig());
  	}
}

In 1.5 this is re-implemented with the new HttpsMapper:

public class MyApplication extends WebApplication
{
        @Override
 	public void init()
 	{
 		super.init();

 		setRootRequestMapper(new HttpsMapper(getRootRequestMapper(), new HttpsConfig()));
 	}
}

Registering HttpsMapper as a root mapper will check all pages before rendering for annotation @RequireHttps.

HeaderContribution

In 1.4 a custom HeaderContributor needed:

new HeaderContributor(new IHeaderContributor() {

            private static final long serialVersionUID = 1L;

            @Override
            public void renderHead(IHeaderResponse response) {
                 //your logic goes here
            }
        });

This could be substitute with:

new AbstractHeaderContributor() {

            @Override
            public void renderHead(IHeaderResponse response) {
                //your logic goes here
            }
        };

Component implements IHeaderContributor and Behavior has #renderHead(Component, IHeaderResponse)

Prior to 1.5 IHeaderContributor was used as a mixin for components and behaviors that wanted to write to the header, in 1.5 it is no longer necessary to implement the interface directly because Component implements it and Behavior has #renderHead(Component, IHeaderResponse).

Removed HeaderContributor and friends.

HeaderContributor was a convenience that did not add much and actually made things worst by increasing memory footprint in a lot of cases. Instead we can simply override IHeaderContributor#renderHead(IHeaderResponse) and achieve the same functionality in a simpler and consistent fashion.

Wicket 1.4:

public class MyPage extends WebPage {
  public MyPage() {
    add(HeaderContributor.forJavaScript(YuiLib.class, "yahoo-dom-event/yahoo-dom-event.js"));
    add(HeaderContributor.forCss(AbstractCalendar.class, "assets/skins/sam/calendar.css"));
  }
}

Becomes the following in 1.5:

public class MyPage extends WebPage {
  public MyPage() {
  }
  public void renderHead(IHeaderResponse response) {
    response.renderJavascriptReference(new PackageResourceReference(YuiLib.class,
      "yahoo-dom-event/yahoo-dom-event.js"));
    response.renderCSSReference(new PackageResourceReference(AbstractCalendar.class,
      "assets/skins/sam/calendar.css"));
  }
}

Likewise,

public class MyPage extends WebPage {
  public MyPage() {
    WebMarkupContainer c=new WebMarkupContainer();
    c.add(HeaderContributor.forJavaScript(YuiLib.class, "yahoo-dom-event/yahoo-dom-event.js"));
    add(c);
  }
}

becomes

public class MyPage extends WebPage {
  public MyPage() {
    WebMarkupContainer c=new WebMarkupContainer();
    c.add(new Behavior() {
      public void renderHead(Component component, IHeaderResponse response) {
        response.renderJavascriptReference(new PackageResourceReference(YuiLib.class,
          "yahoo-dom-event/yahoo-dom-event.js"));
      }
    });
    add(c);
  }
}

Removed TextTemplateHeaderContributor / StringHeaderContributor

Wicket 1.4:

public class DynamicCssBehavior extends TextTemplateHeaderContributor
    public DynamicCssBehavior() {
        super(new CssTemplate(new MyTextTemplate()), new VariablesModel());
    }
    
    private static class VariablesModel extends AbstractReadOnlyModel<Map<String, Object>> {
        public Map<String, Object> getObject() {
            Map<String, Object> variables = new HashMap<String, Object>();
            variables.put("background", "#ff0000");
            return variables;
        }
    }
}

Wicket 1.5:

public class DynamicCssBehavior extends Behavior {
    private TextTemplate template = CssTemplate(new MyTextTemplate());
    
    public void renderHead(Component component, IHeaderResponse response) {
        Map<String, Object> variables = new HashMap<String, Object>();
        variables.put("background", "#ff0000");
        response.renderString(template.asString(variables));
}

(M4) Resource decoration

With org.apache.wicket.Application.setHeaderResponseDecorator(IHeaderResponseDecorator) it is possible to intercept the contribution of resources. This way you may specify which resources will be contributed to the <head> part of the page and which will be contributed to the end (after </body>). Or you may merge several contributions into a bigger one, i.e. serve them all in one http request. For more information consult with Resource decoration or see the new wicket-example.

RequestCycle

RequestCycle has changed in 1.5-M1 and WebRequestCycle has been removed.

In 1.4 you would have overridden onBeginRequest, onEndRequest, and onRuntimeException, like so:

public MyRequestCycle extends WebRequestCycle {
    @Override
    public void onBeginRequest() {
      //...
    }

    @Override
    public void onEndRequest() {
        //...
    }

   @Override
    public Page onRuntimeException(Page page, RuntimeException e) {
        // ...
    }
}

In 1.5, onRuntimeException is gone (see next section). You can still override onBeginRequest and onEndRequest. However, if you are creating a framework that needs to be able to "plug in" functionality into those callbacks, it is recommended that you no longer create a subclass of RequestCycle that your users must also subclass. This limits them from using two such frameworks. Now there is RequestCycle#IRequestCycleListener that you can plug in, either to the cycle itself or to the application, and you will be notified of all of these method callbacks. For example:

public class SomeWebApplication extends WebApplication
{

	@Override
	protected void init()
	{
		addRequestCycleListener(new IRequestCycleListener()
		{

			public void onException(Exception ex)
			{
				// do something here whene there's an exception
			}

			public void onEndRequest()
			{
				// do something at the end of the request
			}

			public void onBeginRequest()
			{
				// do something at the beginning of the request
			}
		});
	}

	@Override
	public Class<? extends Page> getHomePage()
	{
		return SomePage.class;
	}
}

Note also that instead of overriding org.apache.wicket.Application.newRequestCycle(...), you will now call org.apache.wicket.Application.setRequestCycleProvider(IRequestCycleProvider) in your Application#init method to provide a factory that can return any custom RequestCycle that you do want to create, although with the plugins, the need to create a custom request cycle is much lower now.

Exception handling

In Wicket 1.4 it was needed to extend org.apache.wicket.RequestCycle.onRuntimeException(Page, RuntimeException).
Wicket 1.5 gives even better control, by overriding org.apache.wicket.Application.newExceptionMapper() it is possible to change even the default processing of error pages.

ImageMap removed

ImageMap was deprecated in 1.4.11 and in 1.5 it was replaced with ClientSideImageMap component

getResourceSettings().setAddLastModifiedTimeToResourceReferenceUrl() has been replaced by IResourceCachingStrategy

Wicket 1.5 has a new feature called "resource caching strategy".

There are several implementation of the interface

org.apache.wicket.request.resource.caching.IResourceCachingStrategy

which provide different ways of caching your resources (e.g. CSS, javascript, images). Also it's quite easy to implement your own strategy.

The default caching strategy is

org.apache.wicket.request.resource.caching.FilenameWithTimestampResourceCachingStrategy

See the javadoc of the class for details.

It merges the last modified timestamp of the resource into the base resource name. For a good description of this style of caching see chapter

Use fingerprinting to dynamically enable caching

in

http://code.google.com/intl/de-DE/speed/page-speed/docs/caching.html

You can set your own caching strategy with

getResourceSettings().setCachingStrategy(...)

To disable caching altogether (e.g. for performance comparisons) use

getResourceSettings().setCachingStrategy(getResourceSettings().setCachingStrategy(org.apache.wicket.request.resource.caching.NoOpResourceCachingStrategy.INSTANCE))

Inter-component events

Wicket 1.5 offers a simple, yet flexible, way for component to communicate with each other in a decoupled manner. The two major interfaces that facilitate this are:

/**
 * Objects that can send events
 *
 * @author Igor Vaynberg (ivaynberg)
 */
public interface IEventSource
{
	/**
	 * Sends an event
	 *
	 * @param <T>
	 *            tyep of payload
	 *
	 * @param sink
	 *            object that will receive the event
	 * @param broadcast
	 *            if the object that receives the event needs to broadcast it to others, this is the
	 *            type of broadcast that should be used
	 * @param payload
	 *            event payload
	 */
	<T> void send(IEventSink sink, Broadcast broadcast, T payload);
}

and

/**
 * Objects that can receive events
 *
 * @author Igor Vaynberg (ivaynberg)
 */
public interface IEventSink
{
	/**
	 * Called when an event is sent to this sink
	 *
	 * @param event
	 */
	void onEvent(IEvent<?> event);
}

.

The classes that implement these interfaces, and can thus participate in the event mechanism are: Component, RequestCycle, Session, and Application.

The mechanism allows for different event broadcast methods defined here:

/**
 * Defines the event broadcast type.
 *
 * @author igor
 */
public enum Broadcast {
	/**
	 * Breadth first traversal. Supported sinks in order of traversal:
	 *
	 * <ol>
	 * <li>{@link Application}</li>
	 * <li>{@link Session}</li>
	 * <li>{@link RequestCycle}</li>
	 * <li>{@link Page}</li>
	 * <li>{@link Component}s</li>
	 * </ol>
	 *
	 * Any sink along the path can be specified and traversal will start with the specified sink as
	 * root, eg:
	 *
	 * <ul>
	 * <li>If a component inside the page is specified then only the component and all its children
	 * will receive the event</li>
	 * <li>If Session is specified then the session, the request cycle, the page and all its
	 * components will receive the event</li>
	 * </ul>
	 */
	BREADTH,
	/**
	 * Depth first traversal. Supported sinks in order of traversal:
	 *
	 * <ol>
	 * <li>{@link Component}s</li>
	 * <li>{@link Page}</li>
	 * <li>{@link RequestCycle}</li>
	 * <li>{@link Session}</li>
	 * <li>{@link Application}</li>
	 * </ol>
	 *
	 * Any sink along the path can be specified and traversal will start with the specified sink as
	 * root, eg:
	 *
	 * <ul>
	 * <li>If a component inside the page is specified then only the component and all its children
	 * will receive the event</li>
	 * <li>If Session is specified then the session, the request cycle, the page and all its
	 * components will receive the event</li>
	 * </ul>
	 *
	 */
	DEPTH,
	/**
	 * A bubble-up traversal. In a bubble-up traversal only the sink and its parents are notified.
	 *
	 * Supported sinks in order of traversal are:
	 * <ol>
	 * <li>{@link Component}s</li>
	 * <li>{@link Page}</li>
	 * <li>{@link RequestCycle}</li>
	 * <li>{@link Session}</li>
	 * <li>{@link Application}</li>
	 * </ol>
	 *
	 * Any sink along the path can be specified and traversal will start at the specified sink and
	 * work its way up to the {@link Application}, eg:
	 *
	 * <ul>
	 * <li>If a component inside the page is specified then only the component, its parents, the
	 * request cycle, the session, and the application will be notified.
	 * <li>If Session is specified then the session, the application will be notified</li>
	 * </ul>
	 */
	BUBBLE,
	/**
	 * Only the specified sink receives the event
	 */
	EXACT;
}

There is an example in wicket-examples which demonstrates the usage of this.

IEventDispatcher

M4 also introduces IEventDispatcher. Applications can register custom event dispatchers in frameworksettings; the dispatchers can be used to build custom event delivery mechanisms. For example a custom IEventDispatcher mechanism can route events to annotated methods, eg

public class MyComponent extends Component {
    @OnEvent
    private void onUserAdded(UserAddedEvent event) {...}
}

where UserAddedEvent is the event payload object.

The default Component#onEvent() method will be called even if custom dispatchers are registered.

Default ajax event

M4 also introduces a default event raised whenever wicket begins to create an ajax response. The payload of the event is the AjaxRequestTarget used for event. Sample implementation:

// component that always adds itself to the ajax response
public class MyComponent extends Component {
    public void onEvent(IEvent event) {
        if (event.getPayload() instanceof AjaxRequestTarget) {
            ((AjaxRequestTarget)event.getPayload()).add(this);
         }
    }
}

(M4) Header render sequence inverted

In Wicket 1.4 header contributions were rendered parent first. Since 1.5 we render the deepest child first. Now it's possible for containers, which manage their children, to supersede a childs contribution. See WICKET-2693

(M4) WicketTester.startPanel() and WicketTester.assertLabel()

WicketTester always requires a Page, no exception. For startPanel() to work, we use DummyPanelPage and add the panel. Until now assertLabel() required a path relative to page. That wasn't very intuitive, since it required you to prepend the panel-id to your label path. That has changed. Now the path relative to the Panel is sufficient.

(M4) IBehavior interface refactored to abstract class Behavior

IBehavior interface has been refactored into an abstract Behavior class. AbstractBehavior has been deprecated, Behavior should be extended instead. All classes directly implementing IBehavior should now instead extend Behavior.

(M4) Added support for 'x-forwarded-for' headers and more

Please see http://code.google.com/p/xebia-france/wiki/XForwardedFilter which has been used as blueprint, though we are not using a ServletFilter. It's more tightly integrated to benefit from Wicket's core functionalities. See XForwardedRequestWrapperFactory and XForwardedRequestWrapper. The most convinient place to add them is via subclassing WebApplication.newWebRequest() in your own Application object.

List of renamed classes and methods

Following the renames in subclasses is easier if the @Override annotations are present. IDE-s, like Eclipse, can be used to add missing @Override annotations before moving to wicket 1.5.