/*
    * 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"
   * &lt;dependency&gt;
   *   &lt;groupId&gt;xerces&lt;/groupId&gt;
   *   &lt;artifactId&gt;xercesImpl&lt;/artifactId&gt;
   *   &lt;version&gt;2.10.0&lt;/version&gt;
   * &lt;/dependency&gt;
   * }
   * </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 --------------------------------------------------------
 
 }