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

papegaaij pushed a commit to branch partial-update-data
in repository https://gitbox.apache.org/repos/asf/wicket.git

commit 1337517e1b9e0de12c0d02f7db92d4a69ead9000
Author: Emond Papegaaij <[email protected]>
AuthorDate: Sat Nov 14 21:57:20 2026 +0100

    Document data entries over web sockets and namespaced names, and add the 
migration section
    
    The review of the data part in pull request #1834 asked for two points
    in the Javadoc of IPartialPageRequestHandler#addData. A partial update
    pushed over a web socket belongs to no Ajax call, so the subscribers of
    '/ajax/call/data' get an empty object as attrs; the Javadoc only spoke
    of the attributes of the Ajax call. And every subscriber sees every
    entry, with the name as the only thing telling them apart, so two
    libraries choosing the same name would read each other's data; the
    Javadoc now recommends a name prefixed with the library's name.
    
    The data part added two abstract methods, which breaks implementations
    that do not extend the base classes, so migration-to-12.md gets the
    section the commit introducing them only drafted.
    
    Co-Authored-By: Claude Opus 5.5 <[email protected]>
---
 migration-to-12.md                                            |  6 ++++++
 .../core/request/handler/IPartialPageRequestHandler.java      | 11 ++++++++---
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/migration-to-12.md b/migration-to-12.md
index d1011c6c22..3e99b0d849 100644
--- a/migration-to-12.md
+++ b/migration-to-12.md
@@ -25,3 +25,9 @@ To come from Wicket 10, migrate to Wicket 11 first, with the 
[migration guide to
 `PageParameters.hashCode()` now agrees with `equals()`, which ignores the 
order of the named parameters 
([#1866](https://github.com/apache/wicket/issues/1866)). The fix is backported 
to Wicket 11.1.0 and 10.13.0, so an application already on one of those sees no 
change. Before, two `PageParameters` that differed only in that order were 
equal but had different hashes, so a `HashMap` or `HashSet` kept them as two 
keys.
 
 This shows in rendered pages. When a page renders a CSS or JavaScript 
reference header item twice for the same resource, with the same page 
parameters added in a different order, it now gets one `<link>` or `<script>` 
tag, with the URL of the first item. Before, it got two. An application that 
keeps `PageParameters` in a hash-based collection of its own now finds 
reordered parameters under the same entry.
+
+## New abstract methods for the data part of an Ajax response
+
+An Ajax response can carry named data for client-side code, besides components 
and scripts. On the server, `IPartialPageRequestHandler#addData(String, 
CharSequence)` adds an entry, and on the client the topic `'/ajax/call/data'` 
publishes it. That added two abstract methods: 
`IPartialPageRequestHandler#addData(String, CharSequence)` and 
`PartialPageUpdate#writeData(Response, String, CharSequence)`.
+
+An application that uses `AjaxRequestTarget`, the web socket request handler 
or `XmlPartialPageUpdate` sees no change. A class that implements 
`IPartialPageRequestHandler` without extending 
`AbstractPartialPageRequestHandler`, or that extends `PartialPageUpdate` 
without extending `XmlPartialPageUpdate`, no longer compiles until it 
implements the new method.
diff --git 
a/wicket-core/src/main/java/org/apache/wicket/core/request/handler/IPartialPageRequestHandler.java
 
b/wicket-core/src/main/java/org/apache/wicket/core/request/handler/IPartialPageRequestHandler.java
index bf4261e3f6..68ed78917e 100644
--- 
a/wicket-core/src/main/java/org/apache/wicket/core/request/handler/IPartialPageRequestHandler.java
+++ 
b/wicket-core/src/main/java/org/apache/wicket/core/request/handler/IPartialPageRequestHandler.java
@@ -106,12 +106,17 @@ public interface IPartialPageRequestHandler extends 
IPageRequestHandler
         * escapes nor evaluates it. On the client it is published on the topic
         * <code>Wicket.Event.Topic.AJAX_CALL_DATA</code> 
(<code>'/ajax/call/data'</code>) with the
         * arguments <code>(attrs, name, value)</code>, where 
<code>attrs</code> are the attributes of
-        * the Ajax call. Data entries are published in the order they were 
added, after the components
-        * have been replaced and the JavaScripts evaluated, and before the 
success handlers of the call
-        * run.
+        * the Ajax call. A partial update pushed over a web socket belongs to 
no Ajax call, so its
+        * subscribers receive an empty object as <code>attrs</code>. Data 
entries are published in the
+        * order they were added, after the components have been replaced and 
the JavaScripts
+        * evaluated, and before the success handlers of the call run.
         * <p>
         * A subscriber that interprets the value, for example as JSON, has to 
treat it as data and
         * never evaluate it as script or insert it as markup.
+        * <p>
+        * Every subscriber on the page sees every entry, and the name is all 
that tells them apart.
+        * Libraries should therefore use a name of their own, prefixed with 
the library's name, so
+        * their entries do not collide with those of another library.
         *
         * @param name
         *            the name of the entry, used by subscribers to recognise it

Reply via email to