Skip to content

Commit

Permalink
[DOXIA-711] Introduce SinkWrapper and according SinkWrapperFactory (#184
Browse files Browse the repository at this point in the history
)

Add a BufferingSinkProxyWrapper which buffers all calls on the
underlying sink until it is flushed.
Deprecate PipelineSink and RandomAccessSink to reference the
more effective SinkWrapper approach.
  • Loading branch information
kwin authored Dec 24, 2023
1 parent 4f5d91b commit 1fef4c5
Show file tree
Hide file tree
Showing 13 changed files with 859 additions and 963 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -33,6 +36,8 @@
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;

/**
* An abstract base class that defines some convenience methods for parsers.
Expand All @@ -48,6 +53,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?
*/
Expand Down Expand Up @@ -171,7 +181,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
*/
Expand All @@ -189,6 +217,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}.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
16 changes: 16 additions & 0 deletions doxia-core/src/main/java/org/apache/maven/doxia/parser/Parser.java
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,10 @@
package org.apache.maven.doxia.parser;

import java.io.Reader;
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
Expand Down Expand Up @@ -83,4 +85,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();
}
Original file line number Diff line number Diff line change
@@ -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.sink.impl;

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 proxied Sink until its {@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 not a BufferingSink but a " + sink.getClass());
}
}

@Override
public int getPriority() {
return 0;
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,12 @@

/**
* May be used to invoke the same method on a List of Sinks.
* @deprecated Use the {@link SinkWrapper} approach which doesn't require the use of dynamic proxies.
*
* @author <a href="mailto:trygvis@inamo.no">Trygve Laugst&oslash;l</a>
* @see SinkWrapper
*/
@Deprecated
public class PipelineSink implements InvocationHandler {
private List<Sink> pipeline;

Expand Down
Loading

0 comments on commit 1fef4c5

Please sign in to comment.