[DOXIA-711] Introduce SinkWrapper and according SinkWrapperFactory

doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java

@@ -25,6 +25,9 @@
 import java.io.InputStream;
 import java.io.Reader;
 import java.io.StringReader;
+import java.util.Collection;
+import java.util.LinkedList;
+import java.util.PriorityQueue;
 import java.util.Properties;
 
 import org.apache.maven.doxia.macro.Macro;
@@ -33,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.SinkWrapperFactoryComparator;
 
 /**
  * An abstract base class that defines some convenience methods for parsers.
@@ -48,6 +52,11 @@ public abstract class AbstractParser implements Parser {
     @Inject
     private MacroManager macroManager;
 
+    @Inject
+    private Collection<SinkWrapperFactory> automaticallyRegisteredSinkWrapperFactories;
+
+    private final Collection<SinkWrapperFactory> manuallyRegisteredSinkWrapperFactories = new LinkedList<>();
+
     /**
      * Emit Doxia comment events when parsing comments?
      */
@@ -171,7 +180,25 @@ public void parse(Reader source, Sink sink) throws ParseException {
     }
 
     /**
-     * Set <code>secondParsing</code> to true, if we need a second parsing.
+     * Retrieves the sink pipeline built from all registered {@link SinkWrapperFactory} objects.
+     * For secondary parsers (i.e. ones with {@link #isSecondParsing()} returning {@code true} just the given original sink is returned.
+     * @param sink
+     * @return the Sink pipeline to be used
+     */
+    protected Sink getWrappedSink(Sink sink) {
+        // no wrapping for secondary parsing
+        if (secondParsing) {
+            return sink;
+        }
+        Sink currentSink = sink;
+        for (SinkWrapperFactory factory : getSinkWrapperFactories()) {
+            currentSink = factory.createWrapper(currentSink);
+        }
+        return currentSink;
+    }
+
+    /**
+     * Set <code>secondParsing</code> to true, if this represents a secondary parsing of the same source.
      *
      * @param second true for second parsing
      */
@@ -189,6 +216,22 @@ protected boolean isSecondParsing() {
         return secondParsing;
     }
 
+    @Override
+    public void addSinkWrapperFactory(SinkWrapperFactory factory) {
+        manuallyRegisteredSinkWrapperFactories.add(factory);
+    }
+
+    @Override
+    public Collection<SinkWrapperFactory> getSinkWrapperFactories() {
+        PriorityQueue<SinkWrapperFactory> effectiveSinkWrapperFactories =
+                new PriorityQueue<>(new SinkWrapperFactoryComparator());
+        if (automaticallyRegisteredSinkWrapperFactories != null) {
+            effectiveSinkWrapperFactories.addAll(automaticallyRegisteredSinkWrapperFactories);
+        }
+        effectiveSinkWrapperFactories.addAll(manuallyRegisteredSinkWrapperFactories);
+        return effectiveSinkWrapperFactories;
+    }
+
     /**
      * Gets the current {@link MacroManager}.
      *

doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java

@@ -131,7 +131,7 @@ public void parse(Reader source, Sink sink, String reference) throws ParseExcept
             // Note: do it after input is set, otherwise values are reset
             initXmlParser(parser);
 
-            parseXml(parser, sink);
+            parseXml(parser, getWrappedSink(sink));
         } catch (XmlPullParserException ex) {
             throw new ParseException("Error parsing the model", ex, ex.getLineNumber(), ex.getColumnNumber());
         } catch (MacroExecutionException ex) {

doxia-core/src/main/java/org/apache/maven/doxia/parser/BufferingSinkProxyFactory.java

@@ -0,0 +1,112 @@
+/*
+ * 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.
+ */
+package org.apache.maven.doxia.parser;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Proxy;
+import java.util.LinkedList;
+import java.util.Queue;
+
+import org.apache.maven.doxia.sink.Sink;
+
+/**
+ * Buffers all method calls on the wrapped Sink until the proxy sink's method {@link Sink#flush()} is called.
+ */
+public class BufferingSinkProxyFactory implements SinkWrapperFactory {
+
+    private static final class MethodWithArguments {
+        private final Method method;
+        private final Object[] args;
+
+        MethodWithArguments(Method method, Object[] args) {
+            super();
+            this.method = method;
+            this.args = args;
+        }
+
+        void invoke(Object object) {
+            try {
+                method.invoke(object, args);
+            } catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException e) {
+                throw new IllegalStateException("Could not call buffered method " + method, e);
+            }
+        }
+    }
+
+    public interface BufferingSink extends Sink {
+        // just a marker interface
+        Sink getBufferedSink();
+    }
+
+    private static final class BufferingSinkProxy implements InvocationHandler {
+        private final Queue<MethodWithArguments> bufferedInvocations;
+        private final Sink delegate;
+        private static final Method FLUSH_METHOD;
+        private static final Method GET_BUFFERED_SINK_METHOD;
+
+        static {
+            try {
+                FLUSH_METHOD = Sink.class.getMethod("flush");
+                GET_BUFFERED_SINK_METHOD = BufferingSink.class.getMethod("getBufferedSink");
+            } catch (NoSuchMethodException | SecurityException e) {
+                throw new IllegalStateException("Could not find flush method in Sink!", e);
+            }
+        }
+
+        BufferingSinkProxy(Sink delegate) {
+            bufferedInvocations = new LinkedList<>();
+            this.delegate = delegate;
+        }
+
+        @Override
+        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
+            if (method.equals(FLUSH_METHOD)) {
+                bufferedInvocations.forEach(i -> i.invoke(delegate));
+                bufferedInvocations.clear();
+            } else if (method.equals(GET_BUFFERED_SINK_METHOD)) {
+                return delegate;
+            } else {
+                bufferedInvocations.add(new MethodWithArguments(method, args));
+            }
+            return null;
+        }
+    }
+
+    @Override
+    public Sink createWrapper(Sink delegate) {
+        BufferingSinkProxy proxy = new BufferingSinkProxy(delegate);
+        return (Sink) Proxy.newProxyInstance(
+                delegate.getClass().getClassLoader(), new Class<?>[] {BufferingSink.class}, proxy);
+    }
+
+    public static BufferingSink castAsBufferingSink(Sink sink) {
+        if (sink instanceof BufferingSink) {
+            return (BufferingSink) sink;
+        } else {
+            throw new IllegalArgumentException("The given sink is no BufferingSink but a " + sink.getClass());
+        }
+    }
+
+    @Override
+    public int getPriority() {
+        return 0;
+    }
+}

doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java

@@ -19,6 +19,7 @@
 package org.apache.maven.doxia.parser;
 
 import java.io.Reader;
+import java.util.Collection;
 
 import org.apache.maven.doxia.sink.Sink;
 
@@ -83,4 +84,18 @@ public interface Parser {
      * @return <code>true</code> (default value) if comment Doxia events are emitted
      */
     boolean isEmitComments();
+
+    /**
+     * Registers a given {@link SinkWrapperFactory} with the parser used in subsequent calls of {@code parse(...)}
+     * @param factory the factory to create the sink wrapper
+     * @since 2.0.0
+     */
+    void addSinkWrapperFactory(SinkWrapperFactory factory);
+
+    /**
+     *
+     * @return all sink wrapper factories in the correct order (both registered automatically and manually)
+     * @since 2.0.0
+     */
+    Collection<SinkWrapperFactory> getSinkWrapperFactories();
 }