Move new SinkWrapper related classes to another package

Extend Javadoc of PipelineSink and RandomAccessSink to reference the more effective SinkWrapper approach
apache · Dec 23, 2023 · 7eee2e0 · 7eee2e0
1 parent c7ad2c7
commit 7eee2e0
Show file tree

Hide file tree

Showing 9 changed files with 14 additions and 8 deletions.
diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java
@@ -36,6 +36,7 @@
 import org.apache.maven.doxia.macro.manager.MacroManager;
 import org.apache.maven.doxia.macro.manager.MacroNotFoundException;
 import org.apache.maven.doxia.sink.Sink;
+import org.apache.maven.doxia.sink.impl.SinkWrapperFactory;
 import org.apache.maven.doxia.sink.impl.SinkWrapperFactoryComparator;
 
 /**

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java b/doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java
@@ -22,6 +22,7 @@
 import java.util.Collection;
 
 import org.apache.maven.doxia.sink.Sink;
+import org.apache.maven.doxia.sink.impl.SinkWrapperFactory;
 
 /**
  * A Parser is responsible for parsing any document in a supported front-end

diff --git a/...xia/parser/BufferingSinkProxyFactory.java → .../sink/impl/BufferingSinkProxyFactory.java b/...xia/parser/BufferingSinkProxyFactory.java → .../sink/impl/BufferingSinkProxyFactory.java
@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.doxia.parser;
+package org.apache.maven.doxia.sink.impl;
 
 import java.lang.reflect.InvocationHandler;
 import java.lang.reflect.InvocationTargetException;

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/PipelineSink.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/PipelineSink.java
@@ -28,8 +28,10 @@
 
 /**
  * May be used to invoke the same method on a List of Sinks.
+ * Consider using the more flexible {@link SinkWrapper} approach which doesn't require the use of dynamic proxies.
  *
  * @author <a href="mailto:[email protected]">Trygve Laugst&oslash;l</a>
+ * @see SinkWrapper
  */
 public class PipelineSink implements InvocationHandler {
     private List<Sink> pipeline;

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/RandomAccessSink.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/RandomAccessSink.java
@@ -26,7 +26,6 @@
 import java.util.ArrayList;
 import java.util.List;
 
-import org.apache.maven.doxia.parser.SinkWrapper;
 import org.apache.maven.doxia.sink.Sink;
 import org.apache.maven.doxia.sink.SinkFactory;
 
@@ -35,9 +34,12 @@
  * A page can be prepared by first creating its structure and specifying the positions of these hooks.
  * After specifying the structure, the page can be filled with content from one or more models.
  * These hooks can prevent you to have to loop over the model multiple times to build the page as desired.
- *
+ * Consider using the {@link BufferingSinkProxyFactory} instead which allows to buffer on the (higher) Sink API level
+ * which usually is less memory intense and doesn't require dynamically creating new sinks leveraging a {@link SinkFactory} than buffering
+ * the output stream which is done by this class.
  * @author Robert Scholte
  * @since 1.3
+ * @see BufferingSinkProxyFactory
  */
 public class RandomAccessSink extends SinkWrapper {
     private SinkFactory sinkFactory;

diff --git a/...pache/maven/doxia/parser/SinkWrapper.java → ...he/maven/doxia/sink/impl/SinkWrapper.java b/...pache/maven/doxia/parser/SinkWrapper.java → ...he/maven/doxia/sink/impl/SinkWrapper.java
@@ -16,11 +16,11 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.doxia.parser;
+package org.apache.maven.doxia.sink.impl;
 
+import org.apache.maven.doxia.parser.Parser;
 import org.apache.maven.doxia.sink.Sink;
 import org.apache.maven.doxia.sink.SinkEventAttributes;
-import org.apache.maven.doxia.sink.impl.AbstractSink;
 
 /**
  * By default a {@link SinkWrapper} just delegates each method to the wrapped sink's method.

diff --git a/...aven/doxia/parser/SinkWrapperFactory.java → ...n/doxia/sink/impl/SinkWrapperFactory.java b/...aven/doxia/parser/SinkWrapperFactory.java → ...n/doxia/sink/impl/SinkWrapperFactory.java
@@ -16,7 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-package org.apache.maven.doxia.parser;
+package org.apache.maven.doxia.sink.impl;
 
 import org.apache.maven.doxia.sink.Sink;
 

diff --git a/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapperFactoryComparator.java b/doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/SinkWrapperFactoryComparator.java
@@ -20,8 +20,6 @@
 
 import java.util.Comparator;
 
-import org.apache.maven.doxia.parser.SinkWrapperFactory;
-
 /** Sorts the given {@link SinkWrapperFactory}s so that the one with the highest rank comes first (i.e. order by descending ranking) */
 public class SinkWrapperFactoryComparator implements Comparator<SinkWrapperFactory> {
 

diff --git a/doxia-core/src/test/java/org/apache/maven/doxia/parser/AbstractParserTest.java b/doxia-core/src/test/java/org/apache/maven/doxia/parser/AbstractParserTest.java
@@ -29,6 +29,8 @@
 import org.apache.maven.doxia.sink.SinkEventAttributes;
 import org.apache.maven.doxia.sink.impl.SinkEventAttributeSet;
 import org.apache.maven.doxia.sink.impl.SinkEventElement;
+import org.apache.maven.doxia.sink.impl.SinkWrapper;
+import org.apache.maven.doxia.sink.impl.SinkWrapperFactory;
 import org.apache.maven.doxia.sink.impl.TextSink;
 import org.apache.maven.doxia.sink.impl.WellformednessCheckingSink;
 import org.junit.jupiter.api.Assertions;