/*

  * Copyright 2010-2013 smartics, Kronseder & Reiner GmbH

  *

  * Licensed 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 de.smartics.xml.encoding;

 import java.io.IOException;

 import java.io.InputStream;

 import org.apache.commons.lang.StringUtils;

 import org.xml.sax.Attributes;

 import org.xml.sax.InputSource;

 import org.xml.sax.Locator;

 import org.xml.sax.SAXException;

 import org.xml.sax.SAXNotRecognizedException;

 import org.xml.sax.SAXNotSupportedException;

 import org.xml.sax.SAXParseException;

 import org.xml.sax.XMLReader;

 import org.xml.sax.ext.Locator2;

 import org.xml.sax.helpers.DefaultHandler;

 import org.xml.sax.helpers.XMLReaderFactory;

 /**

  * Detects the {@link XmlDescriptor descriptor} of an XML document.

  * <p>

  * The implementation requires a parser implementing

  * <code>org.xml.sax.ext.Locator2</code>. This is provided by the <a

  * href="http://xerces.apache.org/xerces2-j">Xerces</a> from version 2.0.2 on

  * (please refer to <a

  * href="http://xerces.apache.org/xerces2-j/faq-sax.html#faq-6">Xerces SAX

  * FAQ</a> for details).

  * </p>

  * <p>

  * This library does not force a special Xerces version to be used. Maven users

  * may want to add the following dependency to their POM:

  * </p>

  *

  * <pre>

  * {@markupExample "POM Dependency"

  * <dependency>

  *   <groupId>xerces</groupId>

  *   <artifactId>xercesImpl</artifactId>

  *   <version>2.10.0</version>

  * </dependency>

  * }

  * </pre>

  *

  * {@stickyNote Most implementations only provide the version and encoding

  * information if a stream is passed instead of a input source.}

  */

 public class XmlDescriptorDetector

 { // NOPMD due content handler delegation

   // ********************************* Fields *********************************

   // --- constants ------------------------------------------------------------

   /**

    * The message text to be added as prefix to the SAX exception that signals to

    * abort the parsing.

    */

   private static final String ABORTION_MESSAGE_TEXT =

       "Abort parsing. XML document descriptor detected: ";

   // --- members --------------------------------------------------------------

   /**

    * The delegate to fetch additional information from the stream.

    */

   private final XmlParsingHandler delegate;

   // ****************************** Initializer *******************************

   // ****************************** Constructors ******************************

   /**

    * Convenience constructor with no delegate that stops parsing after document

    * start event has been detected.

    */

   public XmlDescriptorDetector()

   {

     this(null);

   }

   /**

    * <p>

    * Default constructor.

    * </p>

    * {@stickyNote Please consider to throw an {@link AbortException in your

    * content handler delegate to abort the parsing as soon as all information is

    * collected.}

    *

    * @param delegate the delegate to fetch additional information from the

    *          stream.

    */

   public XmlDescriptorDetector(final XmlParsingHandler delegate)

   {

     this.delegate = delegate;

   }

   // ****************************** Inner Classes *****************************

   /**

    * Handles the XML document to detect the descriptor information (including

    * the encoding).

    */

   private final class DescriptorHandler extends DefaultHandler

   { // NOPMD due content handler delegation

     // ******************************** Fields ********************************

     // --- constants ----------------------------------------------------------

     // --- members ------------------------------------------------------------

     /**

      * The public identifier as reported by the input source. May be

      * <code>null</code>.

      */

     private final String publicId;

     /**

      * The system identifier as reported by the input source. May be

      * <code>null</code>.

      */

     private final String systemId;

     /**

      * The XML information fetched from the document.

      */

     private XmlDescriptor descriptor;

     /**

      * The locator of the XML document being parsed.

      */

     private Locator locator;

     // ***************************** Initializer ******************************

     // ***************************** Constructors *****************************

     /**

      * Default constructor.

      *

      * @param publicId the public identifier as reported by the input source.

      * @param systemId the system identifier as reported by the input source.

      */

     private DescriptorHandler(final String publicId, final String systemId)

     {

       this.publicId = publicId;

       this.systemId = systemId;

     }

     // ***************************** Inner Classes ****************************

     // ******************************** Methods *******************************

     // --- init ---------------------------------------------------------------

     // --- get&set ------------------------------------------------------------

     // --- business -----------------------------------------------------------

     /**

      * {@inheritDoc}

      *

      * @see org.xml.sax.helpers.DefaultHandler#setDocumentLocator(org.xml.sax.Locator)

      */

     @Override

     public void setDocumentLocator(final Locator locator)

     {

       this.locator = locator;

       if (delegate != null)

       {

         delegate.setDocumentLocator(locator);

       }

     }

     /**

      * {@inheritDoc}

      *

      * @see org.xml.sax.helpers.DefaultHandler#startDocument()

      */

     @Override

     public void startDocument() throws SAXException

     {

       final XmlDescriptor.Builder builder = new XmlDescriptor.Builder();

       if (locator instanceof Locator2)

       {

         final Locator2 locator2 = (Locator2) locator;

         builder.withVersion(locator2.getXMLVersion());

         builder.withEncoding(locator2.getEncoding());

       }

       if (locator != null)

       {

         builder.withPublicId(get(locator.getPublicId(), publicId));

         builder.withSystemId(get(locator.getSystemId(), systemId));

       }

       this.descriptor = builder.build();

       if (delegate == null)

       {

         throw new AbortException(ABORTION_MESSAGE_TEXT + descriptor);

       }

       else

       {

         delegate.startDocument();

       }

     }

     private String get(final String value, final String defaultValue)

     {

       if (StringUtils.isBlank(value))

       {

         return defaultValue;

       }

       return value;

     }

     // ... delegation only ....................................................

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#resolveEntity(java.lang.String,

      *      java.lang.String)

      */

     @Override

     public InputSource resolveEntity(final String publicId,

         final String systemId) throws IOException, SAXException

     {

       return delegate.resolveEntity(publicId, systemId);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#notationDecl(java.lang.String,

      *      java.lang.String, java.lang.String)

      */

     @Override

     public void notationDecl(final String name, final String publicId,

         final String systemId) throws SAXException

     {

       delegate.notationDecl(name, publicId, systemId);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#unparsedEntityDecl(java.lang.String,

      *      java.lang.String, java.lang.String, java.lang.String)

      */

     @Override

     public void unparsedEntityDecl(final String name, final String publicId,

         final String systemId, final String notationName) throws SAXException

     {

       delegate.unparsedEntityDecl(name, publicId, systemId, notationName);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#endDocument()

      */

     @Override

     public void endDocument() throws SAXException

     {

       delegate.endDocument();

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#startPrefixMapping(java.lang.String,

      *      java.lang.String)

      */

     @Override

     public void startPrefixMapping(final String prefix, final String uri)

       throws SAXException

     {

       delegate.startPrefixMapping(prefix, uri);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#endPrefixMapping(java.lang.String)

      */

     @Override

     public void endPrefixMapping(final String prefix) throws SAXException

     {

       delegate.endPrefixMapping(prefix);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#startElement(java.lang.String,

      *      java.lang.String, java.lang.String, org.xml.sax.Attributes)

      */

     @Override

     public void startElement(final String uri, final String localName,

         final String qName, final Attributes attributes) throws SAXException

     {

       delegate.startElement(uri, localName, qName, attributes);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#endElement(java.lang.String,

      *      java.lang.String, java.lang.String)

      */

     @Override

     public void endElement(final String uri, final String localName,

         final String qName) throws SAXException

     {

       delegate.endElement(uri, localName, qName);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#characters(char[], int, int)

      */

     @Override

     public void characters(final char[] ch, final int start, final int length)

       throws SAXException

     {

       delegate.characters(ch, start, length);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#ignorableWhitespace(char[], int,

      *      int)

      */

     @Override

     public void ignorableWhitespace(final char[] ch, final int start,

         final int length) throws SAXException

     {

       delegate.ignorableWhitespace(ch, start, length);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#processingInstruction(java.lang.String,

      *      java.lang.String)

      */

     @Override

     public void processingInstruction(final String target, final String data)

       throws SAXException

     {

       delegate.processingInstruction(target, data);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#skippedEntity(java.lang.String)

      */

     @Override

     public void skippedEntity(final String name) throws SAXException

     {

       delegate.skippedEntity(name);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#warning(org.xml.sax.SAXParseException)

      */

     @Override

     public void warning(final SAXParseException e) throws SAXException

     {

       delegate.warning(e);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#error(org.xml.sax.SAXParseException)

      */

     @Override

     public void error(final SAXParseException e) throws SAXException

     {

       delegate.error(e);

     }

     /**

      * {@inheritDoc}

      * <p>

      * Delegates to the {@link XmlDescriptorDetector#getDelegate() content

      * handler delegate}.

      * </p>

      *

      * @see org.xml.sax.helpers.DefaultHandler#error(org.xml.sax.SAXParseException)

      */

     @Override

     public void fatalError(final SAXParseException e) throws SAXException

     {

       delegate.fatalError(e);

     }

     // --- object basics ------------------------------------------------------

   }

   // ********************************* Methods ********************************

   // --- init -----------------------------------------------------------------

   // --- get&set --------------------------------------------------------------

   /**

    * Returns the delegate to fetch additional information from the stream.

    *

    * @return the delegate to fetch additional information from the stream.

    */

   public XmlParsingHandler getDelegate()

   {

     return delegate;

   }

   // --- business -------------------------------------------------------------

   /**

    * Creates and configures a parser instance.

    *

    * @return the new parser instance.

    * @throws SAXException on any problem creating the parser.

    * @throws SAXNotRecognizedException on any problem configuring the parser.

    * @throws SAXNotSupportedException on any problem configuring the parser.

    */

   protected XMLReader createParser() throws SAXException,

     SAXNotRecognizedException, SAXNotSupportedException

   {

     final XMLReader parser = XMLReaderFactory.createXMLReader();

     return parser;

   }

   /**

    * Reads the XML descriptor of the file provided by the input stream.

    * <p>

    * This will only detect XML version and encoding.

    * </p>

    * {@stickyNote Most implementations only provide the version and encoding

    * information if a stream is passed instead of a input source.}

    *

    * @param input the XML document whose descriptor is to be read.

    * @return the descriptor of the document. Never <code>null</code>.

    * @throws SAXException on any problem reading the XML document.

    * @throws IOException on any problem reading from the input source.

    */

   public XmlDescriptor readDescriptor(final InputStream input)

     throws SAXException, IOException

   {

     final InputSource source = new InputSource(input);

     return readDescriptor(source);

   }

   /**

    * Reads the XML descriptor of the file provided by the input source.

    * <p>

    * As soon as all relevant information is read, the paring is aborted.

    * </p>

    * {@stickyNote Most implementations read the public and system ID from the

    * input source as defaults and return them if no such information can be

    * determined from the {@code input}.}

    *

    * @param input the XML document whose descriptor is to be read.

    * @return the descriptor of the document. Never <code>null</code>.

    * @throws SAXException on any problem reading the XML document.

    * @throws IOException on any problem reading from the input source.

    */

   public XmlDescriptor readDescriptor(final InputSource input)

     throws SAXException, IOException

   {

     final XMLReader parser = createParser();

     final DescriptorHandler handler =

         new DescriptorHandler(input.getPublicId(), input.getSystemId());

     parser.setContentHandler(handler);

     try

     {

       parser.parse(input);

     }

     catch (final AbortException e)

     {

       // OK, requested abort of the XML parsing from one of the content

       // handlers.

     }

     return handler.descriptor;

   }

   // --- object basics --------------------------------------------------------

 }