/*
 * Copyright (C) 2011 United States Government as represented by the Administrator of the
 * National Aeronautics and Space Administration.
 * All Rights Reserved.
 */
package gov.nasa.worldwind.ogc.ows;

import gov.nasa.worldwind.exception.WWRuntimeException;
import gov.nasa.worldwind.util.*;
import gov.nasa.worldwind.util.xml.*;

import javax.xml.namespace.QName;
import javax.xml.stream.*;
import javax.xml.stream.events.XMLEvent;
import java.util.*;
import java.util.logging.Level;

/**
 * Parses an OGC Web Service Common (OWS) ExceptionReport element and provides access to its contents. See
 * http://schemas.opengis.net/ows/2.0/owsExceptionReport.xsd.
 * <p/>
 * Service exception reports are generated by an OGC Web Service (OWS) upon receiving an invalid client request and upon
 * detecting an exceptional condition. In either case, the web service responds to the client request with an exception
 * report XML document. Exception reports typically contain one or more independent exceptions indicating an independent
 * error.
 * <p/>
 * <code>OWSExceptionReport</code> can parse an OGC exception report XML document and hold the parsed information, or
 * export an OGC exception report XML document from its current state. To parse an exception report XML document, create
 * a new <code>OWSExceptionReport</code> from a document source and parse its contents by calling <code>{@link
 * #OWSExceptionReport(Object)}</code> then <code>{@link #parse(Object...)}</code> on the new
 * <code>OWSExceptionReport</code>. To export an exception report's current state to an XML document, call <code>{@link
 * #export(Object)}</code>.
 *
 * @author dcollins
 * @version $Id: OWSExceptionReport.java 1 2011-07-16 23:22:47Z dcollins $
 */
public class OWSExceptionReport extends AbstractXMLEventParser
{
    /**
     * Indicates the exception report's list of web service exceptions. Each exception indicates an independent error.
     * Initially assigned to a new <code>ArrayList</code>.
     */
    protected List<OWSException> exceptions = new ArrayList<OWSException>();
    /**
     * The event reader used to parse the document's XML. This is <code>null<code> if the exception report is not
     * created from an XML document source.
     */
    protected XMLEventReader eventReader;
    /**
     * The parser context for the document. This is <code>null<code> if the exception report is not created from an XML
     * document source.
     */
    protected XMLEventParserContext parserContext;

    /** Creates a new <code>OWSExceptionReport</code> with an empty list of exceptions and no version. */
    public OWSExceptionReport()
    {
        super(OWSConstants.OWS_1dot1_NAMESPACE);
    }

    /**
     * Creates a new <code>OWSExceptionReport</code> from the specified XML document source. The new
     * <code>OWSExceptionReport</code> is ready to parse the specified document source. The caller must initiate parsing
     * by calling <code>{@link #parse(Object...)}</code>.
     *
     * @param docSource the XML source. May be a filename, file, stream or other type allowed by <code>{@link
     *                  WWXML#openEventReader(Object)}</code>.
     *
     * @throws IllegalArgumentException if <code>docSource</code> is <code>null</code>.
     * @throws WWRuntimeException       if the XML source cannot be opened.
     * @see #parse(Object...)
     */
    public OWSExceptionReport(Object docSource)
    {
        super(OWSConstants.OWS_1dot1_NAMESPACE);

        if (docSource == null)
        {
            String message = Logging.getMessage("nullValue.DocumentSourceIsNull");
            Logging.logger().severe(message);
            throw new IllegalArgumentException(message);
        }

        this.eventReader = this.createReader(docSource);
        if (this.eventReader == null)
            throw new WWRuntimeException(Logging.getMessage("XML.UnableToOpenDocument", docSource));

        this.initializeParser();
    }

    /**
     * Indicates the version string of the OGC web service that generated this exception report. The version it
     * typically formatted as <code>x.y.z</code>, where <code>x, y</code> and <code>z</code> are integers in the range
     * 0-99.
     *
     * @return the version of the OGC web service that generated the report, or <code>null</code> if no version is
     *         available.
     *
     * @see #setVersion(String)
     */
    public String getVersion()
    {
        return (String) this.getField("version");
    }

    /**
     * Specifies the version string of the OGC web service that generated this exception report. The version should be
     * formatted as <code>x.y.z</code>, where <code>x, y</code> and <code>z</code> are integers in the range 0-99.
     *
     * @param version the version of the OGC web service that generated the report, may be <code>null</code>.
     *
     * @see #getVersion()
     */
    public void setVersion(String version)
    {
        this.setField("version", version);
    }

    /**
     * Indicates this exception report's list of web service exceptions. Each exception indicates an independent error.
     *
     * @return the report's list of web service exceptions, or <code>null</code> if the report has no exceptions.
     *
     * @see #setExceptions(java.util.List)
     */
    public List<OWSException> getExceptions()
    {
        return this.exceptions;
    }

    /**
     * Specifies this exception report's list of web service exceptions. Each exception indicates an independent error.
     *
     * @param exceptions a list of exceptions, or <code>null</code> to specify that the report has no exceptions.
     *
     * @see #getExceptions()
     */
    public void setExceptions(List<OWSException> exceptions)
    {
        this.exceptions = exceptions;
    }

    /**
     * Adds the specified <code>exception</code> to this exception report's internal exception list. This does nothing
     * if the <code>exception</code> is <code>null</code> or if the internal exception list has been set to
     * <code>null</code>.
     *
     * @param exception the OGC exception to add, may be <code>null</code>.
     */
    public void addException(OWSException exception)
    {
        if (this.getExceptions() != null && exception != null)
            this.getExceptions().add(exception);
    }

    /**
     * Called from the constructor that takes an XML document source, just before it returns. If overriding this method
     * be sure to call <code>super.initialize()</code>.
     *
     * @see #OWSExceptionReport(Object)
     */
    protected void initializeParser()
    {
        this.parserContext = this.createParserContext(this.eventReader);
    }

    /**
     * Creates the exception report's XML event reader. Called from the constructor that takes an XML document source.
     *
     * @param docSource the document source to create a reader for. The type can be any of those supported by {@link
     *                  gov.nasa.worldwind.util.WWXML#openEventReader(Object)}.
     *
     * @return a new event reader, or null if the source type cannot be determined.
     *
     * @see #OWSExceptionReport(Object)
     */
    protected XMLEventReader createReader(Object docSource)
    {
        return WWXML.openEventReader(docSource);
    }

    /**
     * Called during <code>{@link #initializeParser()}</code> to create the parser context.
     *
     * @param reader the reader to associate with the parser context.
     *
     * @return a new parser context.
     */
    protected XMLEventParserContext createParserContext(XMLEventReader reader)
    {
        return new OWSParserContext(reader, this.getNamespaceURI());
    }

    /**
     * Indicates the XML parser context created during <code>{@link #initializeParser()}</code>. Returns
     * <code>null</code> if the exception report was not created form an XML document source.
     *
     * @return the XML parser context, or <code>null</code> the exception report does not have a parser context.
     */
    protected XMLEventParserContext getParserContext()
    {
        return this.parserContext;
    }

    /**
     * Starts document parsing. This method initiates parsing of the OGC exception report XML document and returns when
     * the full exception report document has been parsed. If this exception report was not created from an XML document
     * source, this does nothing and returns <code>null</code>.
     *
     * @param args optional arguments to pass to parsers of sub-elements.
     *
     * @return <code>this</code> if parsing is successful, otherwise <code>null</code>.
     *
     * @throws XMLStreamException if an exception occurs while attempting to read the XML document event stream.
     * @see #OWSExceptionReport(Object)
     */
    public OWSExceptionReport parse(Object... args) throws XMLStreamException
    {
        XMLEventParserContext ctx = this.getParserContext();
        if (ctx == null)
            return null;

        QName rootElementName = new QName(this.getNamespaceURI(), "ExceptionReport");

        for (XMLEvent event = ctx.nextEvent(); ctx.hasNext(); event = ctx.nextEvent())
        {
            if (event == null)
                continue;

            if (ctx.isStartElement(event, rootElementName))
            {
                super.parse(ctx, event, args);
                return this;
            }
        }

        return null;
    }

    /**
     * Overridden to detect <code>OWSException</code> instances creating during XML document parsing, and add these
     * instances to the exception report's internal exception list.
     *
     * @param o     the parsed object to add.
     * @param ctx   the XML parser context.
     * @param event the XML document event.
     * @param args  optional arguments specified when document parsing started.
     *
     * @throws XMLStreamException if an exception occurs while attempting to read the XML document event stream.
     */
    @Override
    protected void doAddEventContent(Object o, XMLEventParserContext ctx, XMLEvent event, Object... args)
        throws XMLStreamException
    {
        if (o instanceof OWSException)
        {
            this.addException((OWSException) o);
        }
        else
        {
            super.doAddEventContent(o, ctx, event, args);
        }
    }

    /**
     * Writes this exception report and its exception list to the specified <code>output</code> as an OGC Web Service
     * Common (OWS) <code>ExceptionReport</code> XML document.
     * <p/>
     * The exported element is formatted according to the OGC Web Service Common (OWS) specification, and is compatible
     * with OWS version <code>1.0.0</code>, <code>1.1.0</code>, and <code>2.0.0</code>.
     *
     * @param output the XML output stream. May be a <code>{@link java.io.OutputStream}</code>, a <code>{@link
     *               java.io.Writer}</code>, or any type allowed by <code>{@link gov.nasa.worldwind.util.WWXML#openStreamWriter(Object)}</code>.
     *
     * @throws IllegalArgumentException if <code>output</code> is <code>null</code>, or if <code>output</code> is not
     *                                  one of the recognized types.
     * @throws XMLStreamException       if an exception occurs while attempting to export the XML event stream.
     */
    public void export(Object output) throws XMLStreamException
    {
        if (output == null)
        {
            String message = Logging.getMessage("nullValue.OutputIsNull");
            Logging.logger().severe(message);
            throw new IllegalArgumentException(message);
        }

        XMLStreamWriter writer;
        boolean closeWriterWhenFinished = false;

        if (output instanceof XMLStreamWriter)
        {
            writer = (XMLStreamWriter) output;
        }
        else
        {
            writer = WWXML.openStreamWriter(output);
            closeWriterWhenFinished = true;
        }

        if (writer == null)
        {
            String message = Logging.getMessage("Export.UnsupportedOutputObject", output);
            Logging.logger().severe(message);
            throw new IllegalArgumentException(message);
        }

        writer.setDefaultNamespace(this.getNamespaceURI());
        writer.writeStartDocument();
        writer.writeStartElement("ExceptionReport");
        writer.writeDefaultNamespace(this.getNamespaceURI());

        if (!WWUtil.isEmpty(this.getVersion()))
            writer.writeAttribute("version", this.getVersion());

        if (this.getExceptions() != null)
        {
            for (OWSException ex : this.getExceptions())
            {
                try
                {
                    if (ex != null)
                        ex.export(writer);
                }
                catch (Exception e)
                {
                    Logging.logger().log(Level.WARNING, Logging.getMessage("Export.UnableToExportObject", ex), e);
                }
            }
        }

        writer.writeEndElement();
        writer.writeEndDocument();
        writer.flush();

        if (closeWriterWhenFinished)
            writer.close();
    }
}