You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/09/03 16:08:20 UTC
(maven-doxia) branch agent/deprecate-parser-hooks created (now 26fb4344)
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a change to branch agent/deprecate-parser-hooks
in repository https://gitbox.apache.org/repos/asf/maven-doxia.git
at 26fb4344 Warn parser subclasses before the SinkEventAttributeSet hooks are retyped
This branch includes the following new commits:
new 26fb4344 Warn parser subclasses before the SinkEventAttributeSet hooks are retyped
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-doxia) 01/01: Warn parser subclasses before the SinkEventAttributeSet hooks are retyped
Posted by sl...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch agent/deprecate-parser-hooks
in repository https://gitbox.apache.org/repos/asf/maven-doxia.git
commit 26fb434424f29a95be7708149a170224398523e2
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Thu Sep 3 16:58:02 2026 +0200
Warn parser subclasses before the SinkEventAttributeSet hooks are retyped
Retyping these to SinkEventAttributes is a silent break, not a loud one: an
override compiled against the old signature stops overriding and is simply
never called again, with nothing failing at build or run time. A deprecation
warning now is the only notice a downstream parser author gets before that.
Of the five hooks #1074 lists, only consecutiveSections was already marked.
Deprecating baseStartTag(String, ...) and baseEndTag(String, ...) also
silences the impl.SinkEventAttributeSet warnings inside their bodies, since
the JLS does not warn for uses within a deprecated declaration. That drops
doxia-core from 84 deprecation warnings to 18; nothing was fixed, the
warnings moved out of view.
Part of #1074
---
.../maven/doxia/parser/AbstractXmlParser.java | 21 ++++++++++++++++
.../maven/doxia/parser/Xhtml1BaseParser.java | 2 ++
.../maven/doxia/parser/Xhtml5BaseParser.java | 28 ++++++++++++++++++++++
.../apache/maven/doxia/module/xdoc/XdocParser.java | 1 +
.../maven/doxia/module/xhtml5/Xhtml5Parser.java | 1 +
5 files changed, 53 insertions(+)
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java
index 63375a46..9986f208 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java
@@ -167,7 +167,12 @@ public abstract class AbstractXmlParser extends AbstractParser implements XmlMar
* @param parser A parser, not null.
* @return a SinkEventAttributeSet or null if the current parser event is not a start tag.
* @since 1.1
+ * @deprecated The return type will become {@link org.apache.maven.doxia.sink.SinkEventAttributes} in the next
+ * major version. Callers are unaffected if they declare the result as that interface; every use in Doxia
+ * itself already needs nothing more than the interface. An override of this method will stop being called
+ * once the return type changes, with no error at build or run time. See <a href="https://github.com/apache/maven-doxia/issues/1074">issue 1074</a>.
*/
+ @Deprecated
protected SinkEventAttributeSet getAttributesFromParser(XmlPullParser parser) {
int count = parser.getAttributeCount();
@@ -382,6 +387,22 @@ public abstract class AbstractXmlParser extends AbstractParser implements XmlMar
handleUnknown(parser.getName(), attribs, sink, type);
}
+ /**
+ * Emits an element that has no dedicated Sink event as
+ * {@link Sink#unknown(String, Object[], org.apache.maven.doxia.sink.SinkEventAttributes)}.
+ *
+ * @param elementName the name of the element.
+ * @param attribs the attributes of the element, may be null.
+ * @param sink the sink to receive the event.
+ * @param type the tag event type, passed as the first required parameter of the Sink event. This should be one
+ * of HtmlMarkup.TAG_TYPE_SIMPLE, HtmlMarkup.TAG_TYPE_START, HtmlMarkup.TAG_TYPE_END or
+ * HtmlMarkup.ENTITY_TYPE.
+ * @deprecated The {@code attribs} parameter will become
+ * {@link org.apache.maven.doxia.sink.SinkEventAttributes} in the next major version.
+ * An override of this signature will stop being called once the parameter type changes, with no error
+ * at build or run time, so move the override to the new signature when it lands. See <a href="https://github.com/apache/maven-doxia/issues/1074">issue 1074</a>.
+ */
+ @Deprecated
protected void handleUnknown(String elementName, SinkEventAttributeSet attribs, Sink sink, int type) {
Object[] required = new Object[] {type};
sink.unknown(elementName, required, attribs);
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml1BaseParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml1BaseParser.java
index 860f96f4..25107a06 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml1BaseParser.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml1BaseParser.java
@@ -148,6 +148,7 @@ public class Xhtml1BaseParser extends Xhtml5BaseParser {
* Translates obsolete XHTML 1.0 attributes/elements to valid XHTML5 ones before calling the underlying {@link Xhtml5BaseParser}.
*/
@Override
+ @SuppressWarnings("deprecation")
protected boolean baseStartTag(XmlPullParser parser, Sink sink) {
SinkEventAttributeSet attribs = getAttributesFromParser(parser);
String elementName = parser.getName();
@@ -173,6 +174,7 @@ public class Xhtml1BaseParser extends Xhtml5BaseParser {
}
@Override
+ @SuppressWarnings("deprecation")
protected boolean baseEndTag(XmlPullParser parser, Sink sink) {
SinkEventAttributeSet attribs = getAttributesFromParser(parser);
String elementName = parser.getName();
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
index 4029d2ba..2d0facfe 100644
--- a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
+++ b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Xhtml5BaseParser.java
@@ -192,11 +192,25 @@ public class Xhtml5BaseParser extends AbstractXmlParser implements HtmlMarkup {
* @param sink the sink to receive the events.
* @return True if the event has been handled by this method, i.e. the tag was recognized, false otherwise.
*/
+ @SuppressWarnings("deprecation")
protected boolean baseStartTag(XmlPullParser parser, Sink sink) {
SinkEventAttributeSet attribs = getAttributesFromParser(parser);
return baseStartTag(parser.getName(), attribs, sink);
}
+ /**
+ * Handles a start tag by element name, so that a subclass can map an element name before the common handling
+ * runs. This is what {@link Xhtml1BaseParser} uses to translate obsolete XHTML 1.0 element names.
+ *
+ * @param elementName the name of the element.
+ * @param attribs the attributes of the element, may be null.
+ * @param sink the sink to receive the events.
+ * @return True if the event has been handled by this method, i.e. the tag was recognized, false otherwise.
+ * @deprecated The {@code attribs} parameter will become {@link SinkEventAttributes} in the next major version.
+ * An override of this signature will stop being called once the parameter type changes, with no error
+ * at build or run time, so move the override to the new signature when it lands. See <a href="https://github.com/apache/maven-doxia/issues/1074">issue 1074</a>.
+ */
+ @Deprecated
protected boolean baseStartTag(String elementName, SinkEventAttributeSet attribs, Sink sink) {
boolean visited = true;
isBeginningOfLineInsideBlock = true;
@@ -486,11 +500,25 @@ public class Xhtml5BaseParser extends AbstractXmlParser implements HtmlMarkup {
* @param sink the sink to receive the events.
* @return True if the event has been handled by this method, false otherwise.
*/
+ @SuppressWarnings("deprecation")
protected boolean baseEndTag(XmlPullParser parser, Sink sink) {
SinkEventAttributeSet attribs = getAttributesFromParser(parser);
return baseEndTag(parser.getName(), attribs, sink);
}
+ /**
+ * Handles an end tag by element name, so that a subclass can map an element name before the common handling
+ * runs. This is what {@link Xhtml1BaseParser} uses to translate obsolete XHTML 1.0 element names.
+ *
+ * @param elementName the name of the element.
+ * @param attribs the attributes of the element, may be null.
+ * @param sink the sink to receive the events.
+ * @return True if the event has been handled by this method, false otherwise.
+ * @deprecated The {@code attribs} parameter will become {@link SinkEventAttributes} in the next major version.
+ * An override of this signature will stop being called once the parameter type changes, with no error
+ * at build or run time, so move the override to the new signature when it lands. See <a href="https://github.com/apache/maven-doxia/issues/1074">issue 1074</a>.
+ */
+ @Deprecated
protected boolean baseEndTag(String elementName, SinkEventAttributeSet attribs, Sink sink) {
boolean visited = true;
isBeginningOfLineInsideBlock = true;
diff --git a/doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java b/doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java
index 0bc8a14b..6398a82a 100644
--- a/doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java
+++ b/doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java
@@ -106,6 +106,7 @@ public class XdocParser extends Xhtml1BaseParser implements XdocMarkup {
}
}
+ @SuppressWarnings("deprecation")
protected void handleStartTag(XmlPullParser parser, Sink sink)
throws XmlPullParserException, MacroExecutionException {
isEmptyElement = parser.isEmptyElementTag();
diff --git a/doxia-modules/doxia-module-xhtml5/src/main/java/org/apache/maven/doxia/module/xhtml5/Xhtml5Parser.java b/doxia-modules/doxia-module-xhtml5/src/main/java/org/apache/maven/doxia/module/xhtml5/Xhtml5Parser.java
index 4cfae0af..13337c31 100644
--- a/doxia-modules/doxia-module-xhtml5/src/main/java/org/apache/maven/doxia/module/xhtml5/Xhtml5Parser.java
+++ b/doxia-modules/doxia-module-xhtml5/src/main/java/org/apache/maven/doxia/module/xhtml5/Xhtml5Parser.java
@@ -62,6 +62,7 @@ public class Xhtml5Parser extends Xhtml5BaseParser implements Xhtml5Markup {
*/
private String sourceContent;
+ @SuppressWarnings("deprecation")
protected void handleStartTag(XmlPullParser parser, Sink sink)
throws XmlPullParserException, MacroExecutionException {
isEmptyElement = parser.isEmptyElementTag();