[DOXIA-614] support source reference in doxia parser

doxia-core/src/main/java/org/apache/maven/doxia/DefaultDoxia.java

@@ -56,12 +56,20 @@ public class DefaultDoxia
     /** {@inheritDoc} */
     public void parse( Reader source, String parserId, Sink sink )
         throws ParserNotFoundException, ParseException
+    {
+        this.parse( source, parserId, sink, null );
+    }
+
+    /** {@inheritDoc} */
+    @Override
+    public void parse( Reader source, String parserId, Sink sink, String reference )
+        throws ParserNotFoundException, ParseException
     {
         Parser parser = parserManager.getParser( parserId );
 
         parser.enableLogging( new PlexusLoggerWrapper( getLogger() ) );
 
-        parser.parse( source, sink );
+        parser.parse( source, sink, reference );
     }
 
     /** {@inheritDoc} */

doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java

@@ -41,24 +41,35 @@ public interface Doxia
      * Parses the given source model using a parser with given id,
      * and emits Doxia events into the given sink.
      *
-     * @param source not null reader that provides the source document.
-     * You could use <code>newReader</code> methods from {@link org.codehaus.plexus.util.ReaderFactory}.
-     * @param parserId Identifier for the parser to use.
-     * @param sink A sink that consumes the Doxia events.
-     * @throws org.apache.maven.doxia.parser.manager.ParserNotFoundException
-     * if no parser could be found for the given id.
-     * @throws org.apache.maven.doxia.parser.ParseException if the model could not be parsed.
+     * @param source not null reader that provides the source document
+     * @param parserId identifier for the parser to use
+     * @param sink a sink that consumes the Doxia events
+     * @throws ParserNotFoundException if no parser could be found for the given id
+     * @throws ParseException if the model could not be parsed
      */
     void parse( Reader source, String parserId, Sink sink )
         throws ParserNotFoundException, ParseException;
 
+    /**
+     * Parses the given source model using a parser with given id,
+     * and emits Doxia events into the given sink.
+     *
+     * @param source not null reader that provides the source document
+     * @param parserId identifier for the parser to use
+     * @param sink a sink that consumes the Doxia events
+     * @param reference string containing the reference to the source (e.g. filename)
+     * @throws ParserNotFoundException if no parser could be found for the given id
+     * @throws ParseException if the model could not be parsed
+     */
+    void parse( Reader source, String parserId, Sink sink, String reference )
+        throws ParserNotFoundException, ParseException;
+
     /**
      * Return a parser for the given <code>parserId</code>.
      *
-     * @param parserId Identifier for the parser to use.
-     * @return the parser defining by parserId.
-     * @throws org.apache.maven.doxia.parser.manager.ParserNotFoundException
-     * if no parser could be found for the given id.
+     * @param parserId identifier for the parser to use
+     * @return the parser identified by parserId
+     * @throws ParserNotFoundException if no parser could be found for the given id
      */
     Parser getParser( String parserId )
         throws ParserNotFoundException;

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

@@ -101,7 +101,7 @@ public abstract class AbstractParser
     /**
      * {@inheritDoc}
      *
-     * @return a int.
+     * @return a int
      */
     public int getType()
     {
@@ -117,7 +117,7 @@ public void setEmitComments( boolean emitComments )
     /**
      * <p>isEmitComments.</p>
      *
-     * @return a boolean.
+     * @return a boolean
      */
     public boolean isEmitComments()
     {
@@ -127,11 +127,11 @@ public boolean isEmitComments()
     /**
      * Execute a macro on the given sink.
      *
-     * @param macroId An id to lookup the macro.
-     * @param request The corresponding MacroRequest.
-     * @param sink The sink to receive the events.
-     * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution.
-     * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found.
+     * @param macroId an id to lookup the macro
+     * @param request the corresponding MacroRequest
+     * @param sink the sink to receive the events
+     * @throws org.apache.maven.doxia.macro.MacroExecutionException if an error occurred during execution
+     * @throws org.apache.maven.doxia.macro.manager.MacroNotFoundException if the macro could not be found
      */
     // Made public right now because of the structure of the APT parser and
     // all its inner classes.
@@ -148,7 +148,7 @@ public void executeMacro( String macroId, MacroRequest request, Sink sink )
     /**
      * Returns the current base directory.
      *
-     * @return The base directory.
+     * @return the base directory
      * @deprecated this does not work in multi-module builds, see DOXIA-373
      */
     protected File getBasedir()
@@ -171,29 +171,46 @@ protected File getBasedir()
      *
      * Convenience method to parse an arbitrary string and emit events into the given sink.
      *
-     * @param string A string that provides the source input.
-     * @param sink A sink that consumes the Doxia events.
-     * @throws org.apache.maven.doxia.parser.ParseException if the string could not be parsed.
+     * @param string a string that provides the source input
+     * @param sink a sink that consumes the Doxia events
+     * @throws org.apache.maven.doxia.parser.ParseException if the string could not be parsed
      * @since 1.1
      */
     public void parse( String string, Sink sink )
         throws ParseException
     {
-        parse( new StringReader( string ), sink );
+        this.parse( string, sink, null );
     }
-
+
+    /**
+     * {@inheritDoc}
+     *
+     * Convenience method to parse an arbitrary string and emit events into the given sink.
+     *
+     * @param string a string that provides the source input
+     * @param sink a sink that consumes the Doxia events
+     * @param reference a string containing the reference to the source of the input string (e.g. filename)
+     * @throws org.apache.maven.doxia.parser.ParseException if the string could not be parsed
+     * @since 1.9.2
+     */
+    public void parse( String string, Sink sink, String reference )
+        throws ParseException
+    {
+        parse( new StringReader( string ), sink, reference );
+    }
+
     /** {@inheritDoc} */
     @Override
-    public void parse( Reader source, Sink sink, String reference )
+    public void parse( Reader source, Sink sink )
         throws ParseException
     {
-        parse( source, sink );
+        parse( source, sink, null );
     }
 
     /**
      * Set <code>secondParsing</code> to true, if we need a second parsing.
      *
-     * @param second True for second parsing.
+     * @param second true for second parsing
      */
     public void setSecondParsing( boolean second )
     {
@@ -203,7 +220,7 @@ public void setSecondParsing( boolean second )
     /**
      * Indicates if we are currently parsing a second time.
      *
-     * @return true if we are currently parsing a second time.
+     * @return true if we are currently parsing a second time
      * @since 1.1
      */
     protected boolean isSecondParsing()
@@ -237,7 +254,7 @@ protected Log getLog()
     /**
      * Gets the current {@link MacroManager}.
      *
-     * @return The current {@link MacroManager}.
+     * @return the current {@link MacroManager}
      * @since 1.1
      */
     protected MacroManager getMacroManager()
@@ -260,7 +277,7 @@ protected void init()
     /**
      * The current Doxia version.
      *
-     * @return the current Doxia version as a String.
+     * @return the current Doxia version as a String
      * @since 1.2
      */
     protected static String doxiaVersion()

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

@@ -100,7 +100,7 @@ public abstract class AbstractXmlParser
     private boolean validate = false;
 
     /** {@inheritDoc} */
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         init();
@@ -153,7 +153,7 @@ public void parse( Reader source, Sink sink )
         setSecondParsing( false );
         init();
     }
-    
+
     /**
      * Initializes the parser with custom entities or other options.
      *
@@ -166,18 +166,6 @@ protected void initXmlParser( XmlPullParser parser )
         // nop
     }
 
-    /**
-     * {@inheritDoc}
-     *
-     * Convenience method to parse an arbitrary string and emit any xml events into the given sink.
-     */
-    @Override
-    public void parse( String string, Sink sink )
-        throws ParseException
-    {
-        super.parse( string, sink );
-    }
-
     /** {@inheritDoc} */
     @Override
     public final int getType()

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

@@ -81,14 +81,14 @@ public class Xhtml5BaseParser
 
     /** {@inheritDoc} */
     @Override
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         init();
 
         try
         {
-            super.parse( source, sink );
+            super.parse( source, sink, reference );
         }
         finally
         {

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

@@ -82,14 +82,14 @@ public class XhtmlBaseParser
 
     /** {@inheritDoc} */
     @Override
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         init();
 
         try
         {
-            super.parse( source, sink );
+            super.parse( source, sink, reference );
         }
         finally
         {

doxia-core/src/test/java/org/apache/maven/doxia/DefaultDoxiaTest.java

@@ -0,0 +1,54 @@
+package org.apache.maven.doxia;
+
+/*
+ * 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.
+ */
+
+import org.apache.maven.doxia.parser.manager.ParserNotFoundException;
+import org.codehaus.plexus.PlexusTestCase;
+import org.junit.Test;
+
+public class DefaultDoxiaTest extends PlexusTestCase
+{
+
+    @Test
+    public void testCreatesDefaultDoxia()
+    {
+        final DefaultDoxia defaultDoxia = new DefaultDoxia();
+
+        assertNotNull( defaultDoxia );
+    }
+
+    @Test
+    public void testFailsWhenParserIdDoesNotExist() throws Exception
+    {
+        final String parserId = "a-parser";
+        final Doxia doxia = lookup( Doxia.class );
+
+        try
+        {
+            doxia.getParser( parserId );
+            fail( "Call should fail with ParserNotFoundException" );
+        }
+        catch ( ParserNotFoundException e )
+        {
+            assertEquals( "Cannot find parser with id = a-parser", e.getMessage() );
+        }
+    }
+
+}

doxia-modules/doxia-module-fml/src/main/java/org/apache/maven/doxia/module/fml/FmlParser.java

@@ -89,7 +89,7 @@ public class FmlParser
     private Map<String, Object> macroParameters = new HashMap<>();
 
     /** {@inheritDoc} */
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         this.faqs = null;
@@ -118,7 +118,7 @@ public void parse( Reader source, Sink sink )
             this.faqs = new Faqs();
 
             // this populates faqs
-            super.parse( tmp, sink );
+            super.parse( tmp, sink, reference );
 
             writeFaqs( sink );
         }

doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java

@@ -163,7 +163,7 @@ public int getType()
 
     /** {@inheritDoc} */
     @Override
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         try

doxia-modules/doxia-module-xdoc/src/main/java/org/apache/maven/doxia/module/xdoc/XdocParser.java

@@ -85,7 +85,7 @@ public class XdocParser
     private boolean hasTitle;
 
     /** {@inheritDoc} */
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         this.sourceContent = null;
@@ -110,7 +110,7 @@ public void parse( Reader source, Sink sink )
 
         try
         {
-            super.parse( new StringReader( sourceContent ), sink );
+            super.parse( new StringReader( sourceContent ), sink, reference );
         }
         finally
         {

doxia-modules/doxia-module-xhtml/src/main/java/org/apache/maven/doxia/module/xhtml/XhtmlParser.java

@@ -333,7 +333,7 @@ protected void init()
     }
 
     /** {@inheritDoc} */
-    public void parse( Reader source, Sink sink )
+    public void parse( Reader source, Sink sink, String reference )
         throws ParseException
     {
         this.sourceContent = null;
@@ -355,7 +355,7 @@ public void parse( Reader source, Sink sink )
 
         try
         {
-            super.parse( new StringReader( sourceContent ), sink );
+            super.parse( new StringReader( sourceContent ), sink, reference );
         }
         finally
         {

doxia-modules/doxia-module-xhtml/src/test/java/org/apache/maven/doxia/module/xhtml/XhtmlParserTest.java

@@ -21,6 +21,7 @@
 
 import java.io.File;
 import java.io.FileFilter;
+import java.io.StringReader;
 import java.util.Iterator;
 import java.util.regex.Pattern;