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)

Reply via email to