This is an automated email from the ASF dual-hosted git repository.
dashorst pushed a commit to branch archive/wicket-9.x
in repository https://gitbox.apache.org/repos/asf/wicket.git
The following commit(s) were added to refs/heads/archive/wicket-9.x by this
push:
new 1840a4bfbf Add the Wicket 9 migration guide from the wiki
1840a4bfbf is described below
commit 1840a4bfbf66bd60b885ed103e57de4dbedb2e71
Author: Martijn Dashorst <[email protected]>
AuthorDate: Wed Nov 4 08:21:54 2026 +0100
Add the Wicket 9 migration guide from the wiki
The migration guides move from the wiki into the source tree of their
release line. This adds migration-to-9.md, converted from the wiki page
"Migration to Wicket 9.0" (version 34, last edited 2021-04-07):
https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=87295921
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-9.md | 201 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 201 insertions(+)
diff --git a/migration-to-9.md b/migration-to-9.md
new file mode 100644
index 0000000000..ac958e3158
--- /dev/null
+++ b/migration-to-9.md
@@ -0,0 +1,201 @@
+<!--
+ 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 9
+
+## **Important notes before you start**
+
+With version 9 Wicket introduced a content security policy
([CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)) active by
default which prevents inline JavaScript and CSS code from been executed. If
you are not planning to make your web app CSP compliant you can disable this
policy using a simple line of code during app initialization:
+
+*disable csp*
+
+```java
+public void init() {
+ getCspSettings().blocking().disabled();
+}
+```
+
+For more details see [CSP paragraph](#CSP).
+
+## **Changes**
+
+#### Component placeholders and form hidden fields
+
+Hidden markup generated by Component placeholders and forms is no longer
hidden with style="display:none;" but with HTML5 "hidden" attribute instead:
+
+<https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/hidden>
+
+Applications must ensure that their CSS do not reveal this markup, e.g. by
falsely changing the CSS display:
+
+```xml
+/* applied to *all* divs, including hidden */
+div {
+ display: flex;
+
+}
+
+/* fix */
+*[hidden] {
+ display: none;
+}
+```
+
+#### IPageStore rework
[WICKET-6563](https://issues.apache.org/jira/browse/WICKET-6563)
+
+Storage of pages was reworked:
+
+- PageStoreManager was broken up into specific managers for storing pages in
the request and session and further storage
+- IPageStore and IDataStore were unified
+
+Most application code should be uneffected by this change, IPageManager stays
the central mediator between the application and page storage(s).\
+Users might consider utilizing new features as:
+
+- CryptingPageStore for encryption of persisted pages
+- FilePageStore with improvements for storing of pages that receive
alternating requests
+
+Stores in <https://github.com/wicketstuff/core/wiki/DataStores> were also
updated.
+
+#### PriorityHeadItems siblings ordering
[WICKET-6673](https://issues.apache.org/jira/browse/WICKET-6673)
+
+The order of siblings' PriorityHeaderItems are now preserved.
+
+#### <a id="CSP"></a>Content Security Policy
[WICKET-6733](https://issues.apache.org/jira/browse/WICKET-6733)
+
+A strict content security policy (CSP) is now in effect in Wicket 9. This
policy forbids any inline javascript and styling. This includes inline
javascript event handlers. This CSP greatly enhances the security of a web
application, but it can be difficult to make a large application compliant. See
[WICKET-6687](https://issues.apache.org/jira/browse/WICKET-6687) for the
changes that were made in Wicket for this change.
+
+The documentation on the configuration of the CSP and guidelines for fixing
violations can be found in the user guide:
[https://ci.apache.org/projects/wicket/guide/9.x/single.html#\_content_security_policy_csp](https://ci.apache.org/projects/wicket/guide/9.x/single.html#_content_security_policy_csp)
+
+While we do not recommend disabling the CSP entirely, this can be done with
one line of code in your application's init method:
+
+```
+getCspSettings().blocking().disabled();
+```
+
+Disabling the CSP will not make your application less secure than it was with
Wicket 8, but you will miss the extra protection against attacks like XSS.
+
+#### Flush and detach (and asynchronous page serialization)
+
+Since Wicket 8.x pages were serialized asynchronously by default
[WICKET-6177](https://issues.apache.org/jira/browse/WICKET-6177), i.e. requests
are processed, detached and flushed to the client without waiting for the
serialization of the touched pages. This feature was introduced to reduce the
response time for requests to Wicket pages.
+
+However this resulted in possible race conditions, when consecutive requests
hit an identical page instance, which is still under process of serialization
from a prior request.
[WICKET-6702](https://issues.apache.org/jira/browse/WICKET-6702)
+
+[WICKET-6831](https://issues.apache.org/jira/browse/WICKET-6831) presents a
better solution to this problem: Pages are always serialized synchronously now
(storing the serialized data in a persistent storage is still done
asynchronously though). But the request is now flushed to the client **before**
detaching of the RequestCycle - besides other clean-up of the request this
includes serialization of all touched pages\
+IRequestCycleListener#onEndRequest(), RequestCycle#onEndRequest() and
Session#endRequest() are called before flush, thus allowing code to create
[WICKET-6847](https://issues.apache.org/jira/browse/WICKET-6847) or invalidate
a session [WICKET-6848](https://issues.apache.org/jira/browse/WICKET-6848).
+
+Note: This improvement was backported to WIcket 8.11.0.
+
+## **API Changes**
+
+#### Deprecate package org.apache.wicket.util.time from wicket-util
[WICKET-6662](https://issues.apache.org/jira/browse/WICKET-6662)
+
+Wicket used custom classes from package org.apache.wicket.util.time to handle
and manipulate time entities such as "duration" or "current instant".\
+These classes have been replaced with standard Java 8 classes
java.time.Duration and java.time.Instant.
+
+#### Deprecate src/main/java/org/apache/wicket/util/collections/MicroMap.java
from wicket-util
[WICKET-6783](https://issues.apache.org/jira/browse/WICKET-6783)
+
+Map#of(Object, Object) should be used instead
+
+#### Deprecate ModalWindow from wicket-extension
[WICKET-6666](https://issues.apache.org/jira/browse/WICKET-6666)
+
+ModalWindow was deprecated and its usage should be replaced with the new
ModalDialog implementation.
+
+#### Deprecate Appliation#setHeaderResponseDecorator()
[WICKET-6729](https://issues.apache.org/jira/browse/WICKET-6729)
+
+Applications now support multiple decorators for header responses. This
simplifies adding a decorator:
+
+*Wicket 9.x*
+
+```java
+// improved API
+getHeaderResponseDecorators().add(response -> new CustomResponse(response));
+```
+
+With the deprecated API you were required to keep a ResourceAggregator around.
Its usage is not recommended, since it prevents usage of CSP ([see
above](#CSP)):
+
+*Wicket 8.x*
+
+```java
+// deprecated API
+setHeaderResponseDecorator(response -> new ResourceAggregator(new
CustomResponse()));
+```
+
+#### Move ConversationPropagator.getPage
+
+The method ConversationPropagator.getPage(IRequestHandler) has been moved to
IPageRequestHandler.
+
+## **Removals**
+
+#### Utility class available in JDK is removed
[WICKET-6783](https://issues.apache.org/jira/browse/WICKET-6783)
+
+wicket-util/src/main/java/org/apache/wicket/util/collections/ConcurrentHashSet.java
+
+#### Removed from wicket-core all the deprecated classes
[WICKET-6562](https://issues.apache.org/jira/browse/WICKET-6562)
+
+Several deprecated classes were removed from wicket-core:
+
+- org/apache/wicket/RequestListenerInterface.java
+- org/apache/wicket/markup/IMarkup.java
+- org/apache/wicket/model/AbstractReadOnlyModel.java
+- org/apache/wicket/model/IChainingModel.java
+- org/apache/wicket/protocol/http/documentvalidation/Comment.java
+- org/apache/wicket/protocol/http/documentvalidation/DocumentElement.java
+- org/apache/wicket/protocol/http/documentvalidation/HtmlDocumentParser.java
+- org/apache/wicket/protocol/http/documentvalidation/HtmlDocumentValidator.java
+- org/apache/wicket/protocol/http/documentvalidation/Tag.java
+- org/apache/wicket/protocol/http/documentvalidation/TextContent.java
+- org/apache/wicket/request/cycle/AbstractRequestCycleListener.java
+
+#### Browser User agent detection
[WICKET-6544](https://issues.apache.org/jira/browse/WICKET-6544)
+
+Wicket's user agent detection was removed (was deprecated in Wicket 8.x), as
the API and implementation was not sufficient for modern browsers. Users are
encouraged to utilize <https://github.com/nielsbasjes/yauaa>
+
+#### IE\<11 and other browser workarounds
[WICKET-6667](https://issues.apache.org/jira/browse/WICKET-6667)
+
+Several workarounds for older browsers were removed. The special JavaScript
event "inputchange" for IE is no longer supported and should be replaced with
the standard "input change" instead.
+
+The Ajax debug-window was removed, users should use their favorite browser's
JS console instead.
+
+#### AjaxFormChoiceComponentUpdatingBehavior and FormComponentUpdatingBehavior
"change" event [WICKET-6718](https://issues.apache.org/jira/browse/WICKET-6718)
+
+Behaviors to update form components always use the "change" JavaScript event
now, the previous workaround with "click" for IE\<9 was removed.
+
+## **Dependencies\**
+
+#### Wicket 9.0 requires Java 11
+
+#### **Upgrade JUnit to version 5
[WICKET-6595](https://issues.apache.org/jira/browse/WICKET-6595)**
+
+All \*\*Tester classes (e.g. WicketTester, FormTester, TagTester,
WebSocketTester) now depend on JUnit 5.x instead of 4.x.
+
+#### **Update CDI integration to CDI 2.0 specification
[WICKET-6581](https://issues.apache.org/jira/browse/WICKET-6581)**
+
+The old wicket-cdi module based on CDI 1.0 has been removed. The with
wicket-cdi-1.1 module (based on CDI 1.1), has been updated to CDI 2.0 and
renamed to wicket-cdi. No code change or API break has been required for this
update. Those who were using wicket-cdi-1.1 should switch to the new wicket-cdi
module. No other steps are needed. Anyone still using the old wicket-cdi module
should migrate to CDI 2.0.
+
+#### **Use JQuery 3.x by default
[WICKET-6596](https://issues.apache.org/jira/browse/WICKET-6596)**
+
+JQuery 2.x is not maintained anymore by jQuery team. Wicket will use by
default latest available 3.x version.
+
+#### Upgrade Apache Velocity to 2.x
[WICKET-6653](https://issues.apache.org/jira/browse/WICKET-6653)
+
+wicket-velocity module now uses org.apache.velocity:velocity-engine-core:2.1
dependency instead of org.apache.velocity:velocity:1.7. Because of this change
there are small API changes in the signature of the Wicket Model used for the
variables.
+
+#### **Overall updates**
+
+All libraries on which Wicket modules depend are updated to their latest
stable versions.\
+The most notable ones are:
+
+- Spring Framework 5.x
+- Objenesis 3.x
[WICKET-6598](https://issues.apache.org/jira/browse/WICKET-6598)