xercesc/sax/Locator.hpp

0001 /*
0002  * Licensed to the Apache Software Foundation (ASF) under one or more
0003  * contributor license agreements.  See the NOTICE file distributed with
0004  * this work for additional information regarding copyright ownership.
0005  * The ASF licenses this file to You under the Apache License, Version 2.0
0006  * (the "License"); you may not use this file except in compliance with
0007  * the License.  You may obtain a copy of the License at
0008  *
0009  *      http://www.apache.org/licenses/LICENSE-2.0
0010  *
0011  * Unless required by applicable law or agreed to in writing, software
0012  * distributed under the License is distributed on an "AS IS" BASIS,
0013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0014  * See the License for the specific language governing permissions and
0015  * limitations under the License.
0016  */
0017
0018 /*
0019  * $Id$
0020  */
0021
0022 #if !defined(XERCESC_INCLUDE_GUARD_LOCATOR_HPP)
0023 #define XERCESC_INCLUDE_GUARD_LOCATOR_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026
0027 XERCES_CPP_NAMESPACE_BEGIN
0028
0029 /**
0030   * Interface for associating a SAX event with a document location.
0031   *
0032   * <p>If a SAX parser provides location information to the SAX
0033   * application, it does so by implementing this interface and then
0034   * passing an instance to the application using the document
0035   * handler's setDocumentLocator method.  The application can use the
0036   * object to obtain the location of any other document handler event
0037   * in the XML source document.</p>
0038   *
0039   * <p>Note that the results returned by the object will be valid only
0040   * during the scope of each document handler method: the application
0041   * will receive unpredictable results if it attempts to use the
0042   * locator at any other time.</p>
0043   *
0044   * <p>SAX parsers are not required to supply a locator, but they are
0045   * very strong encouraged to do so.  If the parser supplies a
0046   * locator, it must do so before reporting any other document events.
0047   * If no locator has been set by the time the application receives
0048   * the startDocument event, the application should assume that a
0049   * locator is not available.</p>
0050   *
0051   * @see DocumentHandler#setDocumentLocator
0052   */
0053
0054 class SAX_EXPORT Locator
0055 {
0056 public:
0057
0058     /** @name Constructors and Destructor */
0059     //@{
0060     /** Default constructor */
0061     Locator()
0062     {
0063     }
0064
0065     /** Destructor */
0066     virtual ~Locator()
0067     {
0068     }
0069
0070     //@}
0071
0072     /** @name The locator interface */
0073     //@{
0074   /**
0075     * Return the public identifier for the current document event.
0076     * <p>This will be the public identifier
0077     * @return A string containing the public identifier, or
0078     *         null if none is available.
0079     * @see #getSystemId
0080     */
0081     virtual const XMLCh* getPublicId() const = 0;
0082
0083   /**
0084     * Return the system identifier for the current document event.
0085     *
0086     * <p>If the system identifier is a URL, the parser must resolve it
0087     * fully before passing it to the application.</p>
0088     *
0089     * @return A string containing the system identifier, or null
0090     *         if none is available.
0091     * @see #getPublicId
0092     */
0093     virtual const XMLCh* getSystemId() const = 0;
0094
0095   /**
0096     * Return the line number where the current document event ends.
0097     * Note that this is the line position of the first character
0098     * after the text associated with the document event.
0099     * @return The line number, or 0 if none is available.
0100     * @see #getColumnNumber
0101     */
0102     virtual XMLFileLoc getLineNumber() const = 0;
0103
0104   /**
0105     * Return the column number where the current document event ends.
0106     * Note that this is the column number of the first
0107     * character after the text associated with the document
0108     * event.  The first column in a line is position 1.
0109     * @return The column number, or 0 if none is available.
0110     * @see #getLineNumber
0111     */
0112     virtual XMLFileLoc getColumnNumber() const = 0;
0113     //@}
0114
0115 private :
0116     /* Copy constructor */
0117     Locator(const Locator&);
0118
0119     /* Assignment operator */
0120     Locator& operator=(const Locator&);
0121 };
0122
0123 XERCES_CPP_NAMESPACE_END
0124
0125 #endif