//

// SAXException.h

//

// Library: XML

// Package: SAX

// Module:  SAX

//

// SAX exception classes.

//

// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.

// and Contributors.

//

// SPDX-License-Identifier: BSL-1.0

//

#ifndef SAX_SAXException_INCLUDED

#define SAX_SAXException_INCLUDED

#include "Poco/XML/XML.h"

#include "Poco/XML/XMLException.h"

#include "Poco/XML/XMLString.h"

namespace Poco::XML {

POCO_DECLARE_EXCEPTION(XML_API, SAXException, XMLException)

  /// The base class for all SAX-related exceptions like SAXParseException,

  /// SAXNotRecognizedException or SAXNotSupportedException.

  ///

  /// This class can contain basic error or warning information from either the XML parser

  /// or the application: a parser writer or application writer can subclass it to provide

  /// additional functionality. SAX handlers may throw this exception or any exception subclassed

  /// from it.

  ///

  /// If the application needs to pass through other types of exceptions, it must wrap those exceptions

  /// in a SAXException or an exception derived from a SAXException.

  ///

  /// If the parser or application needs to include information about a specific location in an XML

  /// document, it should use the SAXParseException subclass.

POCO_DECLARE_EXCEPTION(XML_API, SAXNotRecognizedException, SAXException)

  /// Exception class for an unrecognized identifier.

  ///

  /// An XMLReader will throw this exception when it finds an unrecognized feature or property

  /// identifier; SAX applications and extensions may use this class for other, similar purposes.

POCO_DECLARE_EXCEPTION(XML_API, SAXNotSupportedException, SAXException)

  /// Exception class for an unsupported operation.

  ///

  /// An XMLReader will throw this exception when it recognizes a feature or property identifier,

  /// but cannot perform the requested operation (setting a state or value). Other SAX2 applications

  /// and extensions may use this class for similar purposes.

class Locator;

class XML_API SAXParseException: public SAXException

  /// Encapsulate an XML parse error or warning.

  ///

  /// This exception may include information for locating the error in the original XML document,

  /// as if it came from a Locator object. Note that although the application will receive a

  /// SAXParseException as the argument to the handlers in the ErrorHandler interface, the application

  /// is not actually required to throw the exception; instead, it can simply read the information in it

  /// and take a different action.

  ///

  /// Since this exception is a subclass of SAXException, it inherits the ability to wrap another exception.

{

public:

  SAXParseException(const std::string& msg, const Locator& loc);

    /// Create a new SAXParseException from a message and a Locator.

  SAXParseException(const std::string& msg, const Locator& loc, const Poco::Exception& exc);

    /// Wrap an existing exception in a SAXParseException.

  SAXParseException(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber);

    /// Create a new SAXParseException with an embedded exception.

    ///

    /// This constructor is most useful for parser writers.

    /// All parameters except the message are as if they were provided by a Locator.

    /// For example, if the system identifier is a URL (including relative filename),

    /// the caller must resolve it fully before creating the exception.

  SAXParseException(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber, const Poco::Exception& exc);

    /// Create a new SAXParseException.

    ///

    /// This constructor is most useful for parser writers.

    /// All parameters except the message are as if they were provided by a Locator.

    /// For example, if the system identifier is a URL (including relative filename),

    /// the caller must resolve it fully before creating the exception.

  SAXParseException(const SAXParseException& exc);

    /// Creates a new SAXParseException from another one.

  ~SAXParseException() noexcept;

    /// Destroy the exception.

  SAXParseException& operator = (const SAXParseException& exc);

    /// Assignment operator.

  const char* name() const noexcept;

    /// Returns a static string describing the exception.

  const char* className() const noexcept;

    /// Returns the name of the exception class.

  Poco::Exception* clone() const;

    /// Creates an exact copy of the exception.

  void rethrow() const;

    /// (Re)Throws the exception.

  const XMLString& getPublicId() const;

    /// Get the public identifier of the entity where the exception occurred.

  const XMLString& getSystemId() const;

    /// Get the system identifier of the entity where the exception occurred.

  int getLineNumber() const;

    /// The line number of the end of the text where the exception occurred.

    /// The first line is line 1.

  int getColumnNumber() const;

    /// The column number of the end of the text where the exception occurred.

    /// The first column in a line is position 1.

protected:

  static std::string buildMessage(const std::string& msg, const XMLString& publicId, const XMLString& systemId, int lineNumber, int columnNumber);

private:

  SAXParseException();

  XMLString _publicId;

  XMLString _systemId;

  int       _lineNumber;

  int       _columnNumber;

};

//

// inlines

//

inline const XMLString& SAXParseException::getPublicId() const

{

  return _publicId;

}

inline const XMLString& SAXParseException::getSystemId() const

{

  return _systemId;

}

inline int SAXParseException::getLineNumber() const

{

  return _lineNumber;

}

inline int SAXParseException::getColumnNumber() const

{

  return _columnNumber;

}

} // namespace Poco::XML

#endif // SAX_SAXException_INCLUDED