From 64eea8a17bed29ac55f4a4bd25d3c0cdfbb63300 Mon Sep 17 00:00:00 2001 From: Abel Salgado Romero Date: Mon, 22 May 2023 21:46:42 +0200 Subject: [PATCH 1/2] Remove deprecated methods from extension package * Remove deprecated methods in asciidoctorj-core/org.asciidoctor.extension * Remove deprecated constants in asciidoctorj-api/org.asciidoctor.extension Fixes #1203 --- .../asciidoctor/extension/BlockProcessor.java | 145 ------------------ .../extension/PreprocessorReader.java | 31 +--- .../org/asciidoctor/extension/Reader.java | 27 +--- .../internal/PreprocessorReaderImpl.java | 11 -- .../jruby/extension/internal/ReaderImpl.java | 15 +- .../extension/ArrowsAndBoxesBlock.java | 2 +- .../PositionalAttrsIncludeProcessor.java | 2 +- .../extension/UriIncludeProcessor.java | 2 +- .../WhenJavaExtensionGroupIsRegistered.java | 4 +- .../WhenJavaExtensionIsRegistered.java | 4 +- 10 files changed, 17 insertions(+), 226 deletions(-) diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/BlockProcessor.java b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/BlockProcessor.java index e8b09d811..61d6fadf8 100644 --- a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/BlockProcessor.java +++ b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/BlockProcessor.java @@ -7,151 +7,6 @@ public abstract class BlockProcessor extends BaseProcessor { - /** - * This value is used as the config option key when defining the block type - * a Processor should process. - * Its value must be a list of String constants: - * - *

Example to make a BlockProcessor work on listings and examples named foo: - * 

-     * 
-     * Map<String, Object> config = new HashMap<>();
-     * config.put(CONTEXTS, Arrays.asList(EXAMPLE, LISTING));
-     * BlockProcessor blockProcessor = new BlockProcessor("foo", config);
-     * asciidoctor.javaExtensionRegistry().block(blockProcessor);
-     * 
-     *
- *

- * - * @deprecated Please use {@link Contexts#KEY} - */ - @Deprecated - public static final String CONTEXTS = "contexts"; - - /** - * Predefined constant for making a BlockProcessor work on open blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on open blocks: - * 
-     * [foo]
-     * --
-     * An open block can be an anonymous container,
-     * or it can masquerade as any other block.
-     * --
-     *
- * - * @deprecated Please use {@link Contexts#OPEN} - */ - @Deprecated - public static final String CONTEXT_OPEN = ":open"; - - /** - * Predefined constant for making a BlockProcessor work on example blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on example blocks: - * 
-     * [foo]
-     * ====
-     * This is just a neat example.
-     * ====
-     *
- * - * @deprecated Please use {@link Contexts#EXAMPLE} - */ - @Deprecated - public static final String CONTEXT_EXAMPLE = ":example"; - - /** - * Predefined constant for making a BlockProcessor work on sidebar blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on sidebar blocks: - * 
-     * [foo]
-     * ****
-     * This is just a sidebar.
-     * ****
-     *
- * - * @deprecated Please use {@link Contexts#SIDEBAR} - */ - @Deprecated - public static final String CONTEXT_SIDEBAR = ":sidebar"; - - /** - * Predefined constant for making a BlockProcessor work on literal blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on literal blocks: - * 
-     * [foo]
-     * ....
-     * This is just a literal block.
-     * ....
-     *
- * - * @deprecated Please use {@link Contexts#LITERAL} - */ - @Deprecated - public static final String CONTEXT_LITERAL = ":literal"; - - /** - * Predefined constant for making a BlockProcessor work on source blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on source blocks: - * 
-     * [foo]
-     * ....
-     * This is just a literal block.
-     * ....
-     *
- * - * @deprecated Please use {@link Contexts#LISTING} - */ - @Deprecated - public static final String CONTEXT_LISTING = ":listing"; - - /** - * Predefined constant for making a BlockProcessor work on quote blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on quote blocks: - * 
-     * [foo]
-     * ____
-     * To be or not to be...
-     * ____
-     *
- * - * @deprecated Please use {@link Contexts#QUOTE} - */ - @Deprecated - public static final String CONTEXT_QUOTE = ":quote"; - - /** - * Predefined constant for making a BlockProcessor work on passthrough blocks. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on passthrough blocks: - * - * 
-     * [foo]
-     * ++++
-     * <h1>Big text</h1>
-     * ++++
-     *
- * - * @deprecated Please use {@link Contexts#PASS} - */ - @Deprecated - public static final String CONTEXT_PASS = ":pass"; - - /** - * Predefined constant for making a BlockProcessor work on paragraph blocks. - * This is also the default for the {@link #CONTEXTS} config option if no other context is given. - * When passed with the {@link #CONTEXTS} config option this BlockProcessor works on paragraph blocks: - * - * 
-     * [foo]
-     * Please process this paragraph.
-     *
-     * And don't process this.
-     *
- * - * @deprecated Please use {@link Contexts#PARAGRAPH} - */ - @Deprecated - public static final String CONTEXT_PARAGRAPH = ":paragraph"; - protected String name; public BlockProcessor() { diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/PreprocessorReader.java b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/PreprocessorReader.java index def925daa..bb4642a15 100644 --- a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/PreprocessorReader.java +++ b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/PreprocessorReader.java @@ -9,42 +9,17 @@ public interface PreprocessorReader extends Reader { /** * Push source content onto the front of the reader and switch the context * based on the file, document-relative path and line information given. - * This method is typically used in an {@link IncludeProcessor} to add content - * read from the target specified. - * - * @deprecated Use {@link #pushInclude(String, String, String, int, Map)} instead. - * - * @param data content to push - * @param file representation of name of the included file. Does not need to exists - * @param path representation of path of the included file. Does not need to exists - * @param lineNumber line number of the first line of the included content - * @param attributes additional attributes to pass - */ - @Deprecated - void push_include(String data, String file, String path, int lineNumber, Map attributes); - - /** - * Push source content onto the front of the reader and switch the context - * based on the file, document-relative path and line information given. - * This method is typically used in an {@link IncludeProcessor} to add content + * This method is typically used in an {@link IncludeProcessor} to add content * read from the target specified. * * @param data content to push - * @param file representation of name of the included file. Does not need to exists - * @param path representation of path of the included file. Does not need to exists + * @param file representation of name of the included file. Does not need to exist + * @param path representation of path of the included file. Does not need to exist * @param lineNumber line number of the first line of the included content * @param attributes additional attributes to pass */ void pushInclude(String data, String file, String path, int lineNumber, Map attributes); - /** - * @deprecated Please use {@link #getDocument()} - * - * @return Document representation. - */ - @Deprecated - Document document(); - /** * @return Document representation. */ diff --git a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/Reader.java b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/Reader.java index 5138ae14d..6a206aa38 100644 --- a/asciidoctorj-api/src/main/java/org/asciidoctor/extension/Reader.java +++ b/asciidoctorj-api/src/main/java/org/asciidoctor/extension/Reader.java @@ -4,15 +4,6 @@ public interface Reader { - /** - * Get the 1-based offset of the current line. - * - * @return 1-based offset. - * @deprecated Please use {@link #getLineNumber()} - */ - @Deprecated - int getLineno(); - /** * Get the 1-based offset of the current line. * @@ -45,7 +36,7 @@ public interface Reader { /** * Peek at the next line and check if it's empty (i.e., whitespace only) - * + *

* This method Does not consume the line from the stack. * * @return True if the there are no more lines or if the next line is empty @@ -73,15 +64,8 @@ public interface Reader { * * @return the String of the next line of the source data if data is present or * nulll if there is no more data. - */ - String readLine(); - - /** - * @return A copy of the String List of lines remaining in this Reader - * @deprecated Use {@link #getLines()} */ - @Deprecated - List lines(); + String readLine(); /** * @return A copy of the String List of lines remaining in this Reader @@ -90,7 +74,7 @@ public interface Reader { /** * Push the String line onto the beginning of the Array of source data. - * + *

* Since this line was (assumed to be) previously retrieved through the * reader, it is marked as seen. */ @@ -98,7 +82,7 @@ public interface Reader { /** * Push multiple lines onto the beginning of the Array of source data. - * + *

* Since this lines were (assumed to be) previously retrieved through the * reader, they are marked as seen. */ @@ -107,7 +91,7 @@ public interface Reader { /** * Peek at the next line of source data. Processes the line, if not * already marked as processed, but does not consume it. - * + *

* This method will probe the reader for more lines. */ String peekLine(); @@ -130,7 +114,6 @@ public interface Reader { boolean advance(); /** - * * Public: Advance to the end of the reader, consuming all remaining lines */ void terminate(); diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/PreprocessorReaderImpl.java b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/PreprocessorReaderImpl.java index 1f1edc747..2939f8bc5 100644 --- a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/PreprocessorReaderImpl.java +++ b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/PreprocessorReaderImpl.java @@ -14,11 +14,6 @@ public PreprocessorReaderImpl(IRubyObject rubyNode) { super(rubyNode); } - @Override - public void push_include(String data, String file, String path, int lineNumber, Map attributes) { - pushInclude(data, file, path, lineNumber, attributes); - } - @Override public void pushInclude(String data, String file, String path, int lineNumber, Map attributes) { RubyHash attributeHash = RubyHash.newHash(getRuntime()); @@ -27,12 +22,6 @@ public void pushInclude(String data, String file, String path, int lineNumber, M getRubyProperty("push_include", data, file, path, lineNumber, attributes); } - @Override - @Deprecated - public Document document() { - return getDocument(); - } - @Override public Document getDocument() { return (Document) NodeConverter.createASTNode(getRubyProperty("document")); diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/ReaderImpl.java b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/ReaderImpl.java index d6bf0647b..8ca6c847b 100644 --- a/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/ReaderImpl.java +++ b/asciidoctorj-core/src/main/java/org/asciidoctor/jruby/extension/internal/ReaderImpl.java @@ -1,7 +1,5 @@ package org.asciidoctor.jruby.extension.internal; -import java.util.List; - import org.asciidoctor.extension.Reader; import org.asciidoctor.jruby.internal.RubyObjectWrapper; import org.jruby.Ruby; @@ -9,6 +7,8 @@ import org.jruby.RubyClass; import org.jruby.runtime.builtin.IRubyObject; +import java.util.List; + public class ReaderImpl extends RubyObjectWrapper implements Reader { public ReaderImpl(IRubyObject rubyNode) { @@ -25,12 +25,6 @@ static ReaderImpl createReader(Ruby runtime, List lines) { return new ReaderImpl(readerClass.callMethod("new", rubyLines)); } - @Override - @Deprecated - public int getLineno() { - return getLineNumber(); - } - @Override public int getLineNumber() { return getInt("lineno"); @@ -71,11 +65,6 @@ public String readLine() { return getString("read_line"); } - @Override - public List lines() { - return getList("lines", String.class); - } - @Override public List getLines() { return getList("lines", String.class); diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/ArrowsAndBoxesBlock.java b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/ArrowsAndBoxesBlock.java index b0b43d0d9..ca244ecf7 100644 --- a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/ArrowsAndBoxesBlock.java +++ b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/ArrowsAndBoxesBlock.java @@ -22,7 +22,7 @@ public ArrowsAndBoxesBlock(String context, Document document) { public Object process(StructuralNode parent, Reader reader, Map attributes) { - List lines = reader.lines(); + List lines = reader.getLines(); StringBuilder outputLines = new StringBuilder(); outputLines.append("

");
diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/PositionalAttrsIncludeProcessor.java b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/PositionalAttrsIncludeProcessor.java
index 71244d6c2..c68a1d808 100644
--- a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/PositionalAttrsIncludeProcessor.java
+++ b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/PositionalAttrsIncludeProcessor.java
@@ -32,7 +32,7 @@ public void process(Document document, PreprocessorReader reader, String target,
             str += "," + it.next().getValue();
         }
 
-        reader.push_include(str, target, target, 1, attributes);
+        reader.pushInclude(str, target, target, 1, attributes);
 
     }
 
diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/UriIncludeProcessor.java b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/UriIncludeProcessor.java
index e282595f4..d2d6e18e8 100644
--- a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/UriIncludeProcessor.java
+++ b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/UriIncludeProcessor.java
@@ -29,7 +29,7 @@ public void process(Document document, PreprocessorReader reader, String target,
                         Map attributes) {
 
         StringBuilder content = readContent(target);
-        reader.push_include(content.toString(), target, target, 1, attributes);
+        reader.pushInclude(content.toString(), target, target, 1, attributes);
     }
 
     private StringBuilder readContent(String target) {
diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionGroupIsRegistered.java b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionGroupIsRegistered.java
index 56e695366..c1478ad03 100644
--- a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionGroupIsRegistered.java
+++ b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionGroupIsRegistered.java
@@ -104,7 +104,7 @@ public RubyIncludeSource(Map config) {
         public void process(Document document, PreprocessorReader reader, String target,
                             Map attributes) {
             StringBuilder content = readContent(target);
-            reader.push_include(content.toString(), target, target, 1, attributes);
+            reader.pushInclude(content.toString(), target, target, 1, attributes);
         }
 
         private StringBuilder readContent(String target) {
@@ -171,7 +171,7 @@ public void an_inner_anonymous_class_should_be_registered() {
                     public void process(Document document, PreprocessorReader reader, String target,
                                         Map attributes) {
                         StringBuilder content = readContent(target);
-                        reader.push_include(content.toString(), target, target, 1, attributes);
+                        reader.pushInclude(content.toString(), target, target, 1, attributes);
                     }
 
                     private StringBuilder readContent(String target) {
diff --git a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionIsRegistered.java b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionIsRegistered.java
index bea89cbae..1e95a73cc 100644
--- a/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionIsRegistered.java
+++ b/asciidoctorj-core/src/test/java/org/asciidoctor/extension/WhenJavaExtensionIsRegistered.java
@@ -106,7 +106,7 @@ public RubyIncludeSource(Map config) {
         public void process(Document document, PreprocessorReader reader, String target,
                             Map attributes) {
             StringBuilder content = readContent(target);
-            reader.push_include(content.toString(), target, target, 1, attributes);
+            reader.pushInclude(content.toString(), target, target, 1, attributes);
         }
 
         private StringBuilder readContent(String target) {
@@ -174,7 +174,7 @@ public void an_inner_anonymous_class_should_be_registered() {
             public void process(Document document, PreprocessorReader reader, String target,
                                 Map attributes) {
                 StringBuilder content = readContent(target);
-                reader.push_include(content.toString(), target, target, 1, attributes);
+                reader.pushInclude(content.toString(), target, target, 1, attributes);
             }
 
             private StringBuilder readContent(String target) {

From 50fd97584e48d6fa36aaa7f6c8b9e627f39af88a Mon Sep 17 00:00:00 2001
From: Abel Salgado Romero 
Date: Mon, 22 May 2023 22:29:33 +0200
Subject: [PATCH 2/2] v3 migration guide for 'extension' removed methods

Fixes #1203
---
 CHANGELOG.adoc                                |  4 +-
 .../api-migration-guide-v25x-to-v30.adoc      |  4 ++
 ...eprecated-constants-in-BlockProcessor.adoc | 38 +++++++++++++++++++
 ...precated-methods-in-extension-package.adoc | 20 ++++++++++
 4 files changed, 65 insertions(+), 1 deletion(-)
 create mode 100644 docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
 create mode 100644 docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index fcc0c3c65..c32321bb8 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -37,7 +37,9 @@ Improvement::
 * Return Document AST when using convert or convertFile with appropriate options (#1171) (@abelsromero)
 * Expose Links in the catalog (#1183) (@abelsromero)
 * BREAKING: Remove deprecated methods in Options, OptionsBuilder, Attributes & AttributesBuilder (#1199) (@abelsromero)
-* BREAKING: Remove deprecated Asciidoctor interface (#1201) (@abelsromero)
+* BREAKING: Remove deprecated methods from Asciidoctor interface (#1201) (@abelsromero)
+* BREAKING: Remove deprecated methods from Document interface (#1202) (@abelsromero)
+* BREAKING: Remove deprecated methods and constants from extension package (#1203) (@abelsromero)
 
 Bug Fixes::
 
diff --git a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
index 3ecc4160a..90a60bacc 100644
--- a/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
+++ b/docs/modules/guides/pages/api-migration-guide-v25x-to-v30.adoc
@@ -17,3 +17,7 @@ include::partial$removal-of-deprecated-asMap-from-builders.adoc[]
 include::partial$removal-of-deprecated-methods-in-asciidoctor.adoc[]
 
 include::partial$removal-of-deprecated-methods-in-document.adoc[]
+
+include::partial$removal-of-deprecated-constants-in-BlockProcessor.adoc[]
+
+include::partial$removal-of-deprecated-methods-in-extension-package.adoc[]
diff --git a/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc b/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
new file mode 100644
index 000000000..e0830159b
--- /dev/null
+++ b/docs/modules/guides/partials/removal-of-deprecated-constants-in-BlockProcessor.adoc
@@ -0,0 +1,38 @@
+== Removal of deprecated constants from `org.asciidoctor.extension.BlockProcessor`
+
+All constants in `org.asciidoctor.extension.BlockProcessor` class that were marked as `@Deprecated` have been removed.
+
+You can find the new values in `org.asciidoctor.extension.Contexts` interface.
+See the table below for the equivalencies.
+
+|===
+|Deprecated value |Contexts value
+
+|CONTEXTS
+|KEY
+
+|CONTEXT_OPEN
+|OPEN
+
+|CONTEXT_EXAMPLE
+|EXAMPLE
+
+|CONTEXT_SIDEBAR
+|SIDEBAR
+
+|CONTEXT_LITERAL
+|LITERAL
+
+|CONTEXT_LISTING
+|LISTING
+
+|CONTEXT_QUOTE
+|QUOTE
+
+|CONTEXT_PASS
+|PASS
+
+|CONTEXT_PARAGRAPH
+|PARAGRAPH
+
+|===
diff --git a/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc b/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc
new file mode 100644
index 000000000..6584103d3
--- /dev/null
+++ b/docs/modules/guides/partials/removal-of-deprecated-methods-in-extension-package.adoc
@@ -0,0 +1,20 @@
+== Removal of deprecated methods in `org.asciidoctor.extension` package
+
+Several methods under `org.asciidoctor.extension that were marked as `@Deprecated` have been removed.
+The new methods align better with Java naming patterns and are easily identifiable.
+
+[,java]
+.Removed deprecated methods
+----
+PreprocessorReader::push_include
+Reader::getLineno
+Reader::lines
+----
+
+[,java]
+.Final methods
+----
+PreprocessorReader::pushInclude
+Reader::getLineNumber
+Reader::getLines
+----