xercesc/dom/DOMLSInput.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_DOMLSINPUT_HPP)
0023 #define XERCESC_INCLUDE_GUARD_DOMLSINPUT_HPP
0024
0025 #include <xercesc/util/XercesDefs.hpp>
0026
0027 XERCES_CPP_NAMESPACE_BEGIN
0028
0029
0030 class InputSource;
0031
0032
0033 /**
0034   * This interface represents a single input source for an XML entity.
0035   *
0036   * <p>This interface allows an application to encapsulate information about
0037   * an input source in a single object, which may include a public identifier,
0038   * a system identifier, a byte stream (possibly with a specified encoding),
0039   * and/or a character stream.</p>
0040   *
0041   * <p>There are two places that the application will deliver this input source
0042   * to the parser: as the argument to the parse method, or as the return value
0043   * of the DOMLSResourceResolver.resolveResource method.</p>
0044   *
0045   * <p>The DOMLSParser will use the DOMLSInput object to determine how to
0046   * read XML input. If there is a character stream available, the parser will
0047   * read that stream directly; if not, the parser will use a byte stream, if
0048   * available; if neither a character stream nor a byte stream is available,
0049   * the parser will attempt to open a URI connection to the resource identified
0050   * by the system identifier.</p>
0051   *
0052   * <p>A DOMLSInput object belongs to the application: the parser shall
0053   * never modify it in any way (it may modify a copy if necessary).</p>
0054   *
0055   * @see DOMLSParser#parse
0056   * @see DOMLSResourceResolver#resolveResource
0057   * @since DOM Level 3
0058   */
0059 class CDOM_EXPORT DOMLSInput
0060 {
0061 protected:
0062     // -----------------------------------------------------------------------
0063     //  Hidden constructors
0064     // -----------------------------------------------------------------------
0065     /** @name Hidden constructors */
0066     //@{
0067     DOMLSInput() {};
0068     //@}
0069
0070 private:
0071     // -----------------------------------------------------------------------
0072     // Unimplemented constructors and operators
0073     // -----------------------------------------------------------------------
0074     /** @name Unimplemented constructors and operators */
0075     //@{
0076     DOMLSInput(const DOMLSInput &);
0077     DOMLSInput & operator = (const DOMLSInput &);
0078     //@}
0079
0080 public:
0081     // -----------------------------------------------------------------------
0082     //  All constructors are hidden, just the destructor is available
0083     // -----------------------------------------------------------------------
0084     /** @name Destructor */
0085     //@{
0086     /**
0087      * Destructor
0088      *
0089      */
0090     virtual ~DOMLSInput() {};
0091     //@}
0092
0093     // -----------------------------------------------------------------------
0094     //  Virtual DOMLSInput interface
0095     // -----------------------------------------------------------------------
0096     /** @name Functions introduced in DOM Level 3 */
0097     //@{
0098     // -----------------------------------------------------------------------
0099     //  Getter methods
0100     // -----------------------------------------------------------------------
0101     /**
0102      * String data to parse. If provided, this will always be treated as a sequence of 16-bit units (UTF-16 encoded characters).
0103      * It is not a requirement to have an XML declaration when using stringData. If an XML declaration is present, the value of
0104      * the encoding attribute will be ignored.
0105      *
0106      */
0107     virtual const XMLCh* getStringData() const = 0;
0108
0109     /**
0110      * Returns the byte stream for this input source.
0111      *
0112      * @see InputSource
0113      */
0114     virtual InputSource* getByteStream() const = 0;
0115
0116     /**
0117      * An input source can be set to force the parser to assume a particular
0118      * encoding for the data that input source reprsents, via the setEncoding()
0119      * method. This method returns name of the encoding that is to be forced.
0120      * If the encoding has never been forced, it returns a null pointer.
0121      *
0122      * @return The forced encoding, or null if none was supplied.
0123      * @see #setEncoding
0124      * @since DOM Level 3
0125      */
0126     virtual const XMLCh* getEncoding() const = 0;
0127
0128
0129     /**
0130      * Get the public identifier for this input source.
0131      *
0132      * @return The public identifier, or null if none was supplied.
0133      * @see #setPublicId
0134      * @since DOM Level 3
0135      */
0136     virtual const XMLCh* getPublicId() const = 0;
0137
0138
0139     /**
0140      * Get the system identifier for this input source.
0141      *
0142      * <p>If the system ID is a URL, it will be fully resolved.</p>
0143      *
0144      * @return The system identifier.
0145      * @see #setSystemId
0146      * @since DOM Level 3
0147      */
0148     virtual const XMLCh* getSystemId() const = 0;
0149
0150
0151     /**
0152      * Get the base URI to be used for resolving relative URIs to absolute
0153      * URIs. If the baseURI is itself a relative URI, the behavior is
0154      * implementation dependent.
0155      *
0156      * @return The base URI.
0157      * @see #setBaseURI
0158      * @since DOM Level 3
0159      */
0160     virtual const XMLCh* getBaseURI() const = 0;
0161
0162     // -----------------------------------------------------------------------
0163     //  Setter methods
0164     // -----------------------------------------------------------------------
0165     // -----------------------------------------------------------------------
0166     /**
0167      * Sets the UTF-16 string for this input source.
0168      *
0169      */
0170     virtual void setStringData(const XMLCh* data) = 0;
0171
0172     /**
0173      * Sets the byte stream for this input source.
0174      *
0175      * @see BinInputStream
0176      */
0177     virtual void setByteStream(InputSource* stream) = 0;
0178
0179     /**
0180      * Set the encoding which will be required for use with the XML text read
0181      * via a stream opened by this input source.
0182      *
0183      * <p>This is usually not set, allowing the encoding to be sensed in the
0184      * usual XML way. However, in some cases, the encoding in the file is known
0185      * to be incorrect because of intermediate transcoding, for instance
0186      * encapsulation within a MIME document.
0187      *
0188      * @param encodingStr The name of the encoding to force.
0189      * @since DOM Level 3
0190      */
0191     virtual void setEncoding(const XMLCh* const encodingStr) = 0;
0192
0193
0194     /**
0195      * Set the public identifier for this input source.
0196      *
0197      * <p>The public identifier is always optional: if the application writer
0198      * includes one, it will be provided as part of the location information.</p>
0199      *
0200      * @param publicId The public identifier as a string.
0201      * @see #getPublicId
0202      * @since DOM Level 3
0203      */
0204     virtual void setPublicId(const XMLCh* const publicId) = 0;
0205
0206     /**
0207      * Set the system identifier for this input source.
0208      *
0209      * <p>The system id is always required. The public id may be used to map
0210      * to another system id, but the system id must always be present as a fall
0211      * back.</p>
0212      *
0213      * <p>If the system ID is a URL, it must be fully resolved.</p>
0214      *
0215      * @param systemId The system identifier as a string.
0216      * @see #getSystemId
0217      * @since DOM Level 3
0218      */
0219     virtual void setSystemId(const XMLCh* const systemId) = 0;
0220
0221     /**
0222      * Set the base URI to be used for resolving relative URIs to absolute
0223      * URIs. If the baseURI is itself a relative URI, the behavior is
0224      * implementation dependent.
0225      *
0226      * @param baseURI The base URI.
0227      * @see #getBaseURI
0228      * @since DOM Level 3
0229      */
0230     virtual void setBaseURI(const XMLCh* const baseURI) = 0;
0231     //@}
0232
0233     // -----------------------------------------------------------------------
0234     //  Non-standard Extension
0235     // -----------------------------------------------------------------------
0236     /** @name Non-standard Extension */
0237     //@{
0238
0239     /**
0240      * Indicates if the parser should issue fatal error if this input source
0241      * is not found.  If set to false, the parser issue warning message instead.
0242      *
0243      * @param  flag True if the parser should issue fatal error if this input source is not found.
0244      *               If set to false, the parser issue warning message instead.  (Default: true)
0245      *
0246      * @see #getIssueFatalErrorIfNotFound
0247      */
0248     virtual void setIssueFatalErrorIfNotFound(bool flag) = 0;
0249
0250
0251     /**
0252      * Get the flag that indicates if the parser should issue fatal error if this input source
0253      * is not found.
0254      *
0255      * @return True if the parser should issue fatal error if this input source is not found.
0256      *         False if the parser issue warning message instead.
0257      * @see #setIssueFatalErrorIfNotFound
0258      */
0259     virtual bool getIssueFatalErrorIfNotFound() const = 0;
0260
0261     /**
0262      * Called to indicate that this DOMLSInput is no longer in use
0263      * and that the implementation may relinquish any resources associated with it.
0264      *
0265      * Access to a released object will lead to unexpected result.
0266      */
0267     virtual void release() = 0;
0268     //@}
0269 };
0270
0271
0272 XERCES_CPP_NAMESPACE_END
0273
0274 #endif