You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "Abel Salgado Romero (Jira)" <ji...@apache.org> on 2020/06/27 12:41:00 UTC
[jira] [Updated] (DOXIA-614) Support obtaining the source reference
in a Doxia Parser
[ https://issues.apache.org/jira/browse/DOXIA-614?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Abel Salgado Romero updated DOXIA-614:
--------------------------------------
Description:
Currently, the 'org.apache.maven.doxia.parser.Parser' interface provides 2 methods that parsers can implement, one with and the other without the source reference. However, in reality the one with the reference is never invoked, thus making it unusable.
Methods are:
* void parse( Reader source, Sink sink )
* void parse( Reader source, Sink sink, String reference )
1. Base implementation 'org.apache.maven.doxia.parser.AbstractParser' ('doxia-core') of the reference method calls the other, removing the reference if it is provided.
{code:java}
public void parse( Reader source, Sink sink, String reference )
throws ParseException
{
parse( source, sink );
}{code}
2. In 'org.apache.maven.doxia.DefaultDoxia#parse' ('doxia-core') the parser method 'parser (reader, sink)' is called at the end, which means 'parser(reader, sink, reference)' is never used.
{code:java}
public void parse( Reader source, String parserId, Sink sink )
throws ParserNotFoundException, ParseException
{
Parser parser = parserManager.getParser( parserId );
parser.enableLogging( new PlexusLoggerWrapper( getLogger() ) );
parser.parse( source, sink );
}
{code}
3. 'org.apache.maven.doxia.Doxia#parse(Reader source, String parserId, Sink sink )' and it's implementation 'DefaultDoxia' ('doxia-core') does not receive the source reference, so it cannot pass it in any way.
For these 3 reasons, 'org.apache.maven.doxia.siterenderer.DefaultSiteRenderer#renderDocument' ('doxia-sitetools') who has the source reference is not able to pass it to the above components.
To sum up, the chaing of calls is: DefaultSiteRenderer -> Doxia/DefaultDoxia -> Parser implementation (e.g. AbstractParser)
After discussion with [~hboutemy] the proposal is to fix it in several steps to avoid using SNAPSHOTS and ensure no breaking points:
# Change doxia-core components to support new method with "reference", still having both methods. This means, changing AbstractParser and it's implementations to recieve the "reference". This does not break anything since no one is using this param now.
# Change doxia-sitetools's 'DefaultSiteRenderer' component to pass the reference to Doxia/DefautDoxia.
# Release new doxia-sitetools version.
# Once released, modifty doxia-core components to pass the reference and remove the (Reader, Sink) method completely. Also, in advance that Parsers may need more information about the source, instead of passing "String reference", we will pass a new class "SourceMetadata" that encapsulates the "String regference. That way we can add more information in the future if needed.
was:
Currently, the 'org.apache.maven.doxia.parser.Parser' interface provides 2 methods that parsers can implement, one with and the other without the source reference. However, in reality the one with the reference is never invoked, thus making it unusable.
Methods are:
* void parse( Reader source, Sink sink )
* void parse( Reader source, Sink sink, String reference )
1. Base implementation 'org.apache.maven.doxia.parser.AbstractParser' ('doxia-core') of the reference method calls the other, removing the reference if it is provided.
{code:java}
public void parse( Reader source, Sink sink, String reference )
throws ParseException
{
parse( source, sink );
}{code}
2. In 'org.apache.maven.doxia.DefaultDoxia#parse' ('doxia-core') the parser method 'parser (reader, sink)' is called at the end, which means 'parser(reader, sink, reference)' is never used.
{code:java}
public void parse( Reader source, String parserId, Sink sink )
throws ParserNotFoundException, ParseException
{
Parser parser = parserManager.getParser( parserId );
parser.enableLogging( new PlexusLoggerWrapper( getLogger() ) );
parser.parse( source, sink );
}
{code}
3. 'org.apache.maven.doxia.Doxia#parse(Reader source, String parserId, Sink sink )' and it's implementation 'DefaultDoxia' ('doxia-core') does not receive the source reference, so it cannot pass it in any way.
For these 3 reasons, 'org.apache.maven.doxia.siterenderer.DefaultSiteRenderer#renderDocument' ('doxia-sitetools') who has the source reference is not able to pass it to the above components.
To sum up, the chaing of calls is: DefaultSiteRenderer -> Doxia/DefaultDoxia -> Parser implementation (e.g. AbstractParser)
After discussion with [~hboutemy] the proposal is to fix it in several steps to avoid using SNAPSHOTS and ensure no breaking points:
# Change doxia-core components to support new method with "reference", still having both methods. These means, changing AbstractParser and it's implementations to recieve the "reference". This does not break anything since no one is using this param now.
# Change doxia-sitetools's 'DefaultSiteRenderer' component to pass the reference to Doxia/DefautDoxia.
# Release new doxia-sitetools version.
# Once released, modifty doxia-core components to pass the reference and remove the (Reader, Sink) method completely. Also, in advance that Parsers may need more information about the source, instead of passing "String reference", we will pass a new class "SourceMetadata" that encapsulates the "String regference. That way we can add more information in the future if needed.
> Support obtaining the source reference in a Doxia Parser
> --------------------------------------------------------
>
> Key: DOXIA-614
> URL: https://issues.apache.org/jira/browse/DOXIA-614
> Project: Maven Doxia
> Issue Type: Improvement
> Components: Core, Modules, Site Renderer (moved to DOXIASITETOOLS)
> Reporter: Abel Salgado Romero
> Priority: Major
>
> Currently, the 'org.apache.maven.doxia.parser.Parser' interface provides 2 methods that parsers can implement, one with and the other without the source reference. However, in reality the one with the reference is never invoked, thus making it unusable.
> Methods are:
> * void parse( Reader source, Sink sink )
> * void parse( Reader source, Sink sink, String reference )
>
> 1. Base implementation 'org.apache.maven.doxia.parser.AbstractParser' ('doxia-core') of the reference method calls the other, removing the reference if it is provided.
> {code:java}
> public void parse( Reader source, Sink sink, String reference )
> throws ParseException
> {
> parse( source, sink );
> }{code}
> 2. In 'org.apache.maven.doxia.DefaultDoxia#parse' ('doxia-core') the parser method 'parser (reader, sink)' is called at the end, which means 'parser(reader, sink, reference)' is never used.
>
> {code:java}
> public void parse( Reader source, String parserId, Sink sink )
> throws ParserNotFoundException, ParseException
> {
> Parser parser = parserManager.getParser( parserId );
> parser.enableLogging( new PlexusLoggerWrapper( getLogger() ) );
> parser.parse( source, sink );
> }
> {code}
>
> 3. 'org.apache.maven.doxia.Doxia#parse(Reader source, String parserId, Sink sink )' and it's implementation 'DefaultDoxia' ('doxia-core') does not receive the source reference, so it cannot pass it in any way.
>
> For these 3 reasons, 'org.apache.maven.doxia.siterenderer.DefaultSiteRenderer#renderDocument' ('doxia-sitetools') who has the source reference is not able to pass it to the above components.
> To sum up, the chaing of calls is: DefaultSiteRenderer -> Doxia/DefaultDoxia -> Parser implementation (e.g. AbstractParser)
>
> After discussion with [~hboutemy] the proposal is to fix it in several steps to avoid using SNAPSHOTS and ensure no breaking points:
> # Change doxia-core components to support new method with "reference", still having both methods. This means, changing AbstractParser and it's implementations to recieve the "reference". This does not break anything since no one is using this param now.
> # Change doxia-sitetools's 'DefaultSiteRenderer' component to pass the reference to Doxia/DefautDoxia.
> # Release new doxia-sitetools version.
> # Once released, modifty doxia-core components to pass the reference and remove the (Reader, Sink) method completely. Also, in advance that Parsers may need more information about the source, instead of passing "String reference", we will pass a new class "SourceMetadata" that encapsulates the "String regference. That way we can add more information in the future if needed.
>
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)