Migrating to Wicket 6.0

Environment

• Wicket 6.0 requires at least Java 6

Repeaters

• `IDataProvider` was converted to using `long` instead of `int` to better line up with JPA and other persistence frameworks. This has caused a rather large cascade of `int` to `long` changes all over the repeater packages (WICKET-1175).

Form Processing

Validation

• `StringValidator` will add the `maxlength` attribute if added to a component attached to an input tag
• `AbstractValidator` has been removed
• `ValidationError` now makes creating standard error keys (classname and classname.subtype) easier. Before one had to do: new ValidationError().addMessageKey(validator.getClass().getSimpleName()) to construct the default key, now you can simply say new ValidationError(validator) and it will do the above for you. Also, for more specific keys one had to do new ValidationError().addMessageKey(validator.getClass().getSimpleName()+".variant"), now you can do new ValidationError(validator, "variant").
• Most validators provide a `decorate(ValidationError, Validatable)` method for overriding how they report errors. For example, to add an extra resource key for the error message to StringValidator one can do

  class MyStringValidator extends StringValidator {
      ValidationError decoreate(ValidationError error, IValidatable validatable) {
         error.addKey("mystringerror");
         return error;
      }
  }
  

• org.apache.wicket.validation.RawValidationError is introduced. It can be used to bring a raw Serializable object which is registered as FeedbackMessage with org.apache.wicket.Component#error(Serializable).
• IFormValidator can have its own resource bundle as other IValidator implementations. WICKET-3879

Feedback Storage Refactoring

• Feedback messages reported against components are now stored in component's metadata rather then in session. This will allow them to survive across requests, see WICKET-2705.
• Previously the cleanup of messages was controlled by RequestCycle#cleanupFeedbackMessages(), now it is controlled by an IFeedbackMessageFilter set via IApplicationSettings#setFeedbackMessageCleanupFilter(). When session and components are detached they will run this filter on any stored messages, all messages accepted by the filter are removed. The default filter will accept any rendered message, so by default feedback messages are removed once rendered.
• Form components will clear any stored messages when validate() is called. This will remove any unredered, but now stale, messages.
• Since messages are now stored in session and in component tree retrieving them is not as simple as Session.getFeedbackMessages(). To assist with this common usecase please see FeedbackCollector.
• In test land cleanup of feedback messages was controlled by RequestCycle#set/isCleanupFeedbackMessagesOnDetach(), but this method is now deprecated. Instead, in testland you can now call WicketTester#cleanupFeedbackMessages() to clean up message just like it would be done at the end of a request. Alternatively, WicketTester#clearFeedbackMessages() can be used to clear all feedback messages. By default WicketTester will not clean any feedback messages.

Ajax

Use JQuery as a backing library for Wicket Ajax functionality

Apache Wicket needed to improve the implementation of its JavaScript libraries used for Ajax functionality (wicket-ajax.js and wicket-event.js) by using any of the bigger JavaScript libraries and delegate to it the handling of the differences in the browsers (DOM, events, Ajax, ...). After a discussion in the mailing lists the Wicket team decided to use JQuery for that.
For more information read Wicket Ajax

AjaxRequestTarget is an interface

o.a.w.ajax.AjaxRequestTarget is an interface now with a default implementation o.a.w.ajax.AjaxRequestHandler. This way it will be possible to replace it with a different implementation, or mock/spy it in tests.
This change required to refactor AjaxRequestTarget.get() too. The replacement code is:

  AjaxRequestTarget target = requestCycle.find(AjaxRequestTarget.class);

RequestCycle.find(Class<? extends IRequestHandler>) can be used to find the currently running or a scheduled IRequestHandler for other types too.

IHeaderResponse, including decorators and filters

IHeaderResponse has been rewritten to render HeaderItems. All render* methods have been replaced by a single render(HeaderItem) method. HeaderItems can be instantiated using the factory methods in JavaScriptHeaderItem, CssHeaderItem, OnDomReadyHeaderItem, OnLoadHeaderItem, OnEventHeaderItem and StringHeaderItem. For example, the following code in renderHead:

  response.renderCSSReference(new CssResourceReference(HomePage.class, "header.css"));
  response.renderJavaScriptReference(new JavaScriptResourceReference(HomePage.class, "page.js"));

Needs to be replaced with:

  response.render(CssHeaderItem.forReference(new CssResourceReference(HomePage.class, "header.css")));
  response.render(JavaScriptHeaderItem.forReference(new JavaScriptResourceReference(HomePage.class, "page.js")));

Custom HeaderResponseDecorators and IHeaderResponseFilters also need to be adjusted for the changed methods. These classes now have only one method for rendering and filtering.

Order of Header contributions and wicket:head

The order of header contributions (including wicket:head) has changed with Wicket 6.0. By default components are visited child-first to contribute to the header. For every component, the header contribution from the markup (wicket:head) is rendered first, followed by header contributions done in the code. This means that headers contributed by the page are rendered at the bottom of the header, where they used to be at the top with Wicket 1.5.
This way if the user application uses a component library and a component (or Page) from the library contributes some resource the user application has the possibility to override this contribution with its own one.

package.properties renamed to wicket-package.properties

The special resource bundle that can contain resources for a whole package has been renamed from package.properties to wicket-package.properties. This prefix will be used for all wicket resources which may collide somehow with resources provided by other frameworks. See WICKET-4211

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 6.

Here's a table of deprecated classes and methods in Wicket 1.5 and the corresponding replacement in Wicket 6.

Refactorings

• HttpsMapper has been refactored to make subclassing easier

o.a.w.IComponentSource and o.a.w.ComponentSourceEntry are removed

These classes were used as placeholders for further optimizations in Component's size but were never finished.

o.a.w.Component#onMarkupAttached() has been dropped in favour of o.a.w.Component#onInitialize().

Both methods had the same semantics. #onMarkupAttached() was the one less used and thus got dropped.

IInitializers are initialized before Application#init()

All IInitializer classes configured in wicket.properties are initialized before the call to Application#init(). This way the application has the control to re-configure something that comes from external library. WICKET-4088

PackageResourceReference can load a minified version of a package resource

PackageResourceReference is improved to be able to load a minified/compressed version of a resource.
By default in development mode the non-minimized resource is loaded (resource.ext) while in production mode it will try to load resource.min.ext by automatically inserting .min right before the extension. If there is no such resource with that name then it will fall back to the non-minified version.
This behavior can be configured with org.apache.wicket.settings.IResourceSettings#setUseMinifiedResources(boolean).