This is an automated email from the ASF dual-hosted git repository.

dashorst pushed a commit to branch archive/wicket-6.x
in repository https://gitbox.apache.org/repos/asf/wicket.git


The following commit(s) were added to refs/heads/archive/wicket-6.x by this 
push:
     new f28324d1d3 Add the Wicket 6 migration guide from the wiki
f28324d1d3 is described below

commit f28324d1d3327bd59967933baeaf2f212061bc19
Author: Martijn Dashorst <[email protected]>
AuthorDate: Wed Nov 4 08:21:54 2026 +0100

    Add the Wicket 6 migration guide from the wiki
    
    The migration guides move from the wiki into the source tree of their
    release line. This adds migration-to-6.md, converted from the wiki page
    "Migration to Wicket 6.0" (version 67, last edited 2017-01-09):
    
      https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=27831457
    
    The content is unchanged. Confluence macros became Markdown: code
    blocks, notes and warnings as GitHub alerts, Jira macros as links to
    the issue; the table of contents was dropped, as GitHub generates one.
    Links to the other migration guides on the wiki now point to their
    files on the branch of their release line.
    
    Generated-by: Claude Code (Claude Opus 5.5)
---
 migration-to-6.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)

diff --git a/migration-to-6.md b/migration-to-6.md
new file mode 100644
index 0000000000..2c52c30b9d
--- /dev/null
+++ b/migration-to-6.md
@@ -0,0 +1,198 @@
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+# Migration to Wicket 6
+
+## 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](https://issues.apache.org/jira/browse/WICKET-1175)).
+- All classes in wicket-extensions which are related to repeaters with sorting 
behavior have improved generics\
+  related to the sorting property 
([WICKET-4535](https://issues.apache.org/jira/browse/WICKET-4535)). In most 
cases you just have to add '**, String**' to the previous parameterized type. 
For example: *IColumn\<Entity\>* becomes *IColumn\<Entity, String\>*. But now 
it is possible to use other type for the sort property than java.lang.String 
too.
+
+#### Form Processing
+
+##### Validation
+
+- \`StringValidator\` will add the \`maxlength\` attribute if added to a 
component attached to an input tag
+- `MinimumValidator` and `MaximumValidator` are replaced by 
`RangeValidator.minimum` and `RangeValidator.maximum` respectively
+- \`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,  [...]
+- 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
+
+  ```java
+  class MyStringValidator extends StringValidator {
+      ValidationError decorate(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](https://issues.apache.org/jira/browse/WICKET-3879)
+- CheckBox never fails required check: 
[WICKET-1221](https://issues.apache.org/jira/browse/WICKET-1221)
+
+##### 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.
+
+##### Feedback messages now use ${label} instead of ${input}
+
+You should use form component.setLabel(...) to provide a good 
(internationalized) label for your form components such as text fields. If no 
label is set on your form fields, Wicket will use the component identifier as 
the label. This will change the feedback messages from:
+
+- '12345a' is not a valid integer
+
+To:
+
+- 'Number' is not a valid integer
+
+Provided that the field has a 'Number' label.
+
+##### added onAfterSubmit to Buttons and SubmitLinks
+
+The call order of onSubmit in Buttons vs Forms was inconsistent in 1.4, and 
fixed at "Button always comes first" in 1.5. Sometimes it is desirable to have 
the Button's onSubmit running after the Form's, however. In 6.0, 
`IFormSubmitter.onSubmit` is still fixed at "button first". In addition to 
that, there is now `.onAfterSubmit`. Your submitting component can implement 
either one of them or even both. Both will be called after the validation and 
form model update, just like before. The o [...]
+
+#### 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](https://cwiki.apache.org/confluence/x/NK2oAQ)
+
+##### 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:
+
+```java
+  AjaxRequestTarget target = requestCycle.find(AjaxRequestTarget.class);
+```
+
+RequestCycle.get().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:
+
+```java
+  response.renderCSSReference(new CssResourceReference(HomePage.class, 
"header.css"));
+  response.renderJavaScriptReference(new 
JavaScriptResourceReference(HomePage.class, "page.js"));
+  response.renderOnDomReadyJavaScript("foobar");
+```
+
+Needs to be replaced with:
+
+```java
+  response.render(CssHeaderItem.forReference(new 
CssResourceReference(HomePage.class, "header.css")));
+  response.render(JavaScriptHeaderItem.forReference(new 
JavaScriptResourceReference(HomePage.class, "page.js")));
+  response.render(OnDomReadyHeaderItem.forScript("foobar));
+```
+
+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](https://issues.apache.org/jira/browse/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.
+
+| Wicket 1.5 (deprecated) | Wicket 6 (replacement) |
+|---|---|
+| org.apache.wicket.behavior.SimpleAttributeModifier | 
org.apache.wicket.AttributeModifier#replace(...) |
+| org.apache.wicket.request.Url#toAbsoluteString() | 
org.apache.wicket.request.Url#toString(StringMode.FULL) |
+| org.apache.wicket.markup.html.IHeaderResponse | 
org.apache.wicket.markup.head.IHeaderResponse |
+| org.apache.wicket.markup.html.internal.HeaderResponse | 
org.apache.wicket.markup.head.internal.HeaderResponse |
+| 
org.apache.wicket.resource.filtering.HeaderResponseContainerFilteringHeaderResponse
 | org.apache.wicket.markup.head.filter.FilteringHeaderResponse |
+| org.apache.wicket.resource.filtering.HeaderResponseFilteredResponseContainer 
| org.apache.wicket.markup.head.filter.HeaderResponseContainer |
+| org.apache.wicket.resource.filtering.\* | 
org.apache.wicket.markup.head.filter.\* |
+| org.apache.wicket.markup.html.tree.\* | 
org.apache.wicket.extensions.markup.html.repeater.tree.\* |
+| org.apache.wicket.extensions.markup.html.tree.\* | 
org.apache.wicket.extensions.markup.html.repeater.tree.\* |
+| org.apache.wicket.request.mapper.\*\* | 
org.apache.wicket.core.request.mapper.\*\* (OSGi friendly) |
+| org.apache.wicket.request.handler.\*\* | 
org.apache.wicket.core.request.handler.\*\* (OSGi friendly) |
+| org.apache.wicket.util.io.\*\* | org.apache.wicket.core.util.io.\*\* (OSGi 
friendly) |
+| org.apache.wicket.util.crypt.\*\* | org.apache.wicket.core.util.crypt.\*\* 
(OSGi friendly) |
+| org.apache.wicket.util.file.\*\* | org.apache.wicket.core.util.file.\*\* 
(OSGi friendly) |
+| org.apache.wicket.util.lang.\*\* | org.apache.wicket.core.util.lang.\*\* |
+| org.apache.wicket.util.resource.\*\* | 
org.apache.wicket.core.util.resource.\*\* (OSGi friendly) |
+| org.apache.wicket.util.string.\*\* | org.apache.wicket.core.util.string.\*\* 
(OSGi friendly) |
+| org.apache.wicket.request.UrlEncoder | 
org.apache.wicket.util.encoding.UrlEncoder |
+| org.apache.wicket.request.UrlDecoder | 
org.apache.wicket.util.encoding.UrlDecoder |
+| org.apache.wicket.util.IClusterable | org.apache.wicket.util.io.IClusterable 
|
+
+#### 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](https://issues.apache.org/jira/browse/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<b>.min</b>.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).
+
+#### ResourceStreamLocator and ResourceFinder have been cleaned up
+
+The responsibilities of ResourceStreamLocator and IResourceFinder have been 
untangled and cleaned.
+
+- ResourceStreamLocator now purely generates pathnames using a 
ResourceNameIterator and then uses a list of IResourceFinders to actually get 
those resources.
+- ResourceStreamLocator no longer does resource loading from the classpath on 
its own. Instead, there is now ClassPathResourceFinder.
+- IResourceSettings no longer contains just a single ResourceFinder but rather 
a list of them that will be tried in the given order.
+- Path and WebApplicationPath no longer extend each other, and also no longer 
have a list of prefixes, only a single one. If you need several path prefixes, 
simply add more Paths, WebApplicationPaths or other IResourceFinder 
implementations to IResourceSettings#resourcesFinders.
+- The IResourcePath interface was removed, since each ResourceFinder now only 
has one path.
+- replace getResourceSettings().addResourceFolder("some/path") with 
getResourceSettings().getResourceFinders().add(new 
WebApplicationPath(getServletContext(), "some/path));
+
+#### Changes to org.apache.wicket.ajax.json.\* (since Wicket 6.27.0) 
[WICKET-6287](https://issues.apache.org/jira/browse/WICKET-6287) - Switch from 
[json.org](http://json.org/) to open-json RESOLVED
+
+Because of license issues all classes in the mentioned package have been 
replaced by classes of open-json (<https://github.com/tdunning/open-json>) 
which means that the basic functionality is nearly the same. Some classes 
however (example: org.json.HTTP) are throwing WicketRuntimeExceptions because 
there is no corresponding implementation in open-json, yet. 
[json.org](http://json.org) can be used in this case (can be found in the 
central maven repository) if the license conditions are accepted.
+
+#### Minor changes
+
+- Files#getLocalFileFromUrl(URL) decodes url before returning file
+- WizardStep header labels encode their model values by default, override 
WizardStep#getHeader() if you need the old behavior (i.e. model values not 
encoded)
+- IErrorMessageSource#substitute(Map\<String,Object\>) was merged into 
IErrorMessageSource#getMessage(String, Map\<String,Object\>)
+- org.apache.wicket.util.resource.IResourceStreamWriter#write() now works 
again with java.io.OutputStream as in Wicket 1.4.x. 
[WICKET-4601](https://issues.apache.org/jira/browse/WICKET-4601)
+- WicketTester.startPanel -\> WicketTester.startComponentInPage
+- WebSession#authenticate() was moved to AuthenticatedWebSession and now 
abstract
+- ChoiceFilteredPropertyColumn/ChoiceFilter use 
DropDownChoice#setNullValid(true) now

Reply via email to