001/*
002    Licensed to the Apache Software Foundation (ASF) under one
003    or more contributor license agreements.  See the NOTICE file
004    distributed with this work for additional information
005    regarding copyright ownership.  The ASF licenses this file
006    to you under the Apache License, Version 2.0 (the
007    "License"); you may not use this file except in compliance
008    with the License.  You may obtain a copy of the License at
009
010       http://www.apache.org/licenses/LICENSE-2.0
011
012    Unless required by applicable law or agreed to in writing,
013    software distributed under the License is distributed on an
014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015    KIND, either express or implied.  See the License for the
016    specific language governing permissions and limitations
017    under the License.
018 */
019package org.apache.wiki.htmltowiki;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.core.Engine;
023import org.htmlunit.cyberneko.parsers.SAXParser;
024import org.jdom2.Document;
025import org.jdom2.Element;
026import org.jdom2.JDOMException;
027import org.jdom2.input.SAXBuilder;
028import org.jdom2.input.sax.XMLReaderJDOMFactory;
029import org.jdom2.output.XMLOutputter;
030import org.xml.sax.Attributes;
031import org.xml.sax.SAXException;
032import org.xml.sax.SAXNotRecognizedException;
033import org.xml.sax.SAXNotSupportedException;
034import org.xml.sax.XMLReader;
035import org.xml.sax.helpers.AttributesImpl;
036import org.xml.sax.helpers.XMLFilterImpl;
037
038import java.io.IOException;
039import java.io.StringReader;
040import java.util.Arrays;
041import java.util.HashSet;
042import java.util.Set;
043
044/**
045 * Converting Html to Wiki Markup with NekoHtml for converting html to xhtml and
046 * Xhtml2WikiTranslator for converting xhtml to Wiki Markup.
047 *
048 */
049public class HtmlStringToWikiTranslator {
050
051    /** Hands JDOM the HTML parser directly, as it would set SAX features on it that the parser does not know about. */
052    private static final XMLReaderJDOMFactory HTML_READER_FACTORY = new XMLReaderJDOMFactory() {
053        @Override
054        public XMLReader createXMLReader() {
055            return new AttributeUriFilter( new SAXParser() );
056        }
057
058        @Override
059        public boolean isValidating() {
060            return false;
061        }
062    };
063
064    private final Engine e;
065
066    /**
067     *  Create a new translator.
068     */
069    public HtmlStringToWikiTranslator( final Engine e ) {
070        this.e = e;
071    }
072
073    /**
074     *  Translates text from HTML into WikiMarkup without a WikiContext (meaning
075     *  some things perhaps cannot be translated).  Uses the default configuration.
076     *
077     *  @param html HTML text to translate
078     *  @return WikiMarkup
079     *
080     *  @throws JDOMException If parsing fails
081     *  @throws IOException For other kinds of errors.
082     */
083    public String translate( final String html ) throws JDOMException, IOException, ReflectiveOperationException {
084        return translate( html, new XHtmlToWikiConfig() );
085    }
086
087    /**
088     *  Translates text from HTML into WikiMarkup with a WikiContext.  The translation
089     *  accuracy is better.  Uses the default configuration.
090     *
091     *  @param html HTML text to translate
092     *  @param wikiContext The WikiContext to use.
093     *  @return WikiMarkup
094     *
095     *  @throws JDOMException If parsing fails
096     *  @throws IOException For other kinds of errors.
097     */
098    public String translate( final String html, final Context wikiContext ) throws JDOMException, IOException, ReflectiveOperationException {
099        return translate( html, new XHtmlToWikiConfig( wikiContext ) );
100    }
101
102    /**
103     *  Translates text from HTML into WikiMarkup using a specified configuration.
104     *
105     *  @param html HTML text to translate
106     *  @param config The configuration to use.
107     *  @return WikiMarkup
108     *
109     *  @throws JDOMException If parsing fails
110     *  @throws IOException For other kinds of errors.
111     */
112    public String translate( final String html, final XHtmlToWikiConfig config ) throws JDOMException, IOException, ReflectiveOperationException {
113        final Element element = htmlStringToElement( html );
114        final XHtmlElementToWikiTranslator xhtmlTranslator = new XHtmlElementToWikiTranslator( e, element, config );
115        return xhtmlTranslator.getWikiString();
116    }
117
118    /**
119     * Use NekoHtml to parse HTML like well-formed XHTML
120     *
121     * @param html HTML to parse.
122     * @return xhtml jdom root element (node "html")
123     * @throws JDOMException when errors occur in parsing
124     * @throws IOException when an I/O error prevents a document from being fully parsed
125     */
126    private Element htmlStringToElement( final String html ) throws JDOMException, IOException {
127        final SAXBuilder builder = new SAXBuilder( HTML_READER_FACTORY, null, null );
128        //builder.setProperty( XMLConstants.ACCESS_EXTERNAL_DTD, "" );
129        //builder.setProperty( XMLConstants.ACCESS_EXTERNAL_SCHEMA, "" );
130        final Document doc = builder.build( new StringReader( html ) );
131        return doc.getRootElement();
132    }
133
134    /**
135     *  A static helper method to create HTML from an Element.
136     *
137     *  @param element The element to get HTML from.
138     *  @return HTML
139     */
140    public static String element2String( final Element element ) {
141        final Document document = new Document( element );
142        final XMLOutputter outputter = new XMLOutputter();
143        return outputter.outputString( document );
144    }
145
146    /**
147     *  The HTML parser reports {@code null} as the namespace URI of the attributes, where the SAX contract says it is the empty string,
148     *  and JDOM cannot handle that.
149     */
150    private static final class AttributeUriFilter extends XMLFilterImpl {
151
152        private static final Set< String > EXTERNAL_ENTITY_FEATURES = new HashSet<>( Arrays.asList(
153                "http://xml.org/sax/features/external-general-entities",
154                "http://xml.org/sax/features/external-parameter-entities" ) );
155
156        AttributeUriFilter( final XMLReader parent ) {
157            super( parent );
158        }
159
160        /**
161         * JDOM sets the features of its reader that handle external entities. The HTML parser never resolves them, and does not
162         * know those features, so whatever JDOM asks for is not an error.
163         */
164        @Override
165        public void setFeature( final String name, final boolean value ) throws SAXNotRecognizedException, SAXNotSupportedException {
166            try {
167                super.setFeature( name, value );
168            } catch( final SAXNotRecognizedException | SAXNotSupportedException e ) {
169                if( !EXTERNAL_ENTITY_FEATURES.contains( name ) ) {
170                    throw e;
171                }
172            }
173        }
174
175        @Override
176        public void startElement( final String uri, final String localName, final String qName, final Attributes atts ) throws SAXException {
177            final AttributesImpl attributes = new AttributesImpl( atts );
178            for( int i = 0; i < attributes.getLength(); i++ ) {
179                if( attributes.getURI( i ) == null ) {
180                    attributes.setURI( i, "" );
181                }
182            }
183            super.startElement( uri, localName, qName, attributes );
184        }
185
186    }
187
188}