This interface allows an application to encapsulate information about * an input source in a single object, which may include a public identifier, * a system identifier, a byte stream (possibly with a specified encoding), * and/or a character stream.
* *There are two places that the application will deliver this input source * to the parser: as the argument to the parse method, or as the return value * of the DOMEntityResolver.resolveEntity method.
* *The DOMBuilder will use the DOMInputSource object to determine how to * read XML input. If there is a character stream available, the parser will * read that stream directly; if not, the parser will use a byte stream, if * available; if neither a character stream nor a byte stream is available, * the parser will attempt to open a URI connection to the resource identified * by the system identifier.
* *A DOMInputSource object belongs to the application: the parser shall * never modify it in any way (it may modify a copy if necessary).
* * @see DOMBuilder#parse * @see DOMEntityResolver#resolveEntity * @since DOM Level 3 */ class CDOM_EXPORT DOMInputSource { protected: // ----------------------------------------------------------------------- // Hidden constructors // ----------------------------------------------------------------------- /** @name Hidden constructors */ //@{ DOMInputSource() {}; //@} private: // ----------------------------------------------------------------------- // Unimplemented constructors and operators // ----------------------------------------------------------------------- /** @name Unimplemented constructors and operators */ //@{ DOMInputSource(const DOMInputSource &); DOMInputSource & operator = (const DOMInputSource &); //@} public: // ----------------------------------------------------------------------- // All constructors are hidden, just the destructor is available // ----------------------------------------------------------------------- /** @name Destructor */ //@{ /** * Destructor * */ virtual ~DOMInputSource() {}; //@} // ----------------------------------------------------------------------- // Virtual DOMInputSource interface // ----------------------------------------------------------------------- /** @name Functions introduced in DOM Level 3 */ //@{ // ----------------------------------------------------------------------- // Getter methods // ----------------------------------------------------------------------- /** * An input source can be set to force the parser to assume a particular * encoding for the data that input source reprsents, via the setEncoding() * method. This method returns name of the encoding that is to be forced. * If the encoding has never been forced, it returns a null pointer. * *"Experimental - subject to change"
* * @return The forced encoding, or null if none was supplied. * @see #setEncoding * @since DOM Level 3 */ virtual const XMLCh* getEncoding() const = 0; /** * Get the public identifier for this input source. * *"Experimental - subject to change"
* * @return The public identifier, or null if none was supplied. * @see #setPublicId * @since DOM Level 3 */ virtual const XMLCh* getPublicId() const = 0; /** * Get the system identifier for this input source. * *"Experimental - subject to change"
* *If the system ID is a URL, it will be fully resolved.
* * @return The system identifier. * @see #setSystemId * @since DOM Level 3 */ virtual const XMLCh* getSystemId() const = 0; /** * Get the base URI to be used for resolving relative URIs to absolute * URIs. If the baseURI is itself a relative URI, the behavior is * implementation dependent. * *"Experimental - subject to change"
* * @return The base URI. * @see #setBaseURI * @since DOM Level 3 */ virtual const XMLCh* getBaseURI() const = 0; // ----------------------------------------------------------------------- // Setter methods // ----------------------------------------------------------------------- /** * Set the encoding which will be required for use with the XML text read * via a stream opened by this input source. * *This is usually not set, allowing the encoding to be sensed in the * usual XML way. However, in some cases, the encoding in the file is known * to be incorrect because of intermediate transcoding, for instance * encapsulation within a MIME document. * *
"Experimental - subject to change"
* * @param encodingStr The name of the encoding to force. * @since DOM Level 3 */ virtual void setEncoding(const XMLCh* const encodingStr) = 0; /** * Set the public identifier for this input source. * *The public identifier is always optional: if the application writer * includes one, it will be provided as part of the location information.
* *"Experimental - subject to change"
* * @param publicId The public identifier as a string. * @see #getPublicId * @since DOM Level 3 */ virtual void setPublicId(const XMLCh* const publicId) = 0; /** * Set the system identifier for this input source. * *The system id is always required. The public id may be used to map * to another system id, but the system id must always be present as a fall * back.
* *If the system ID is a URL, it must be fully resolved.
* *"Experimental - subject to change"
* * @param systemId The system identifier as a string. * @see #getSystemId * @since DOM Level 3 */ virtual void setSystemId(const XMLCh* const systemId) = 0; /** * Set the base URI to be used for resolving relative URIs to absolute * URIs. If the baseURI is itself a relative URI, the behavior is * implementation dependent. * *"Experimental - subject to change"
* * @param baseURI The base URI. * @see #getBaseURI * @since DOM Level 3 */ virtual void setBaseURI(const XMLCh* const baseURI) = 0; //@} // ----------------------------------------------------------------------- // Non-standard Extension // ----------------------------------------------------------------------- /** @name Non-standard Extension */ //@{ /** * Makes the byte stream for this input source. * *The derived class must create and return a binary input stream of an * appropriate type for its kind of data source. The returned stream must * be dynamically allocated and becomes the parser's property. *
* *"Experimental - subject to change"
* * @see BinInputStream */ virtual BinInputStream* makeStream() const = 0; /** * Indicates if the parser should issue fatal error if this input source * is not found. If set to false, the parser issue warning message instead. * *"Experimental - subject to change"
* * @param flag True if the parser should issue fatal error if this input source is not found. * If set to false, the parser issue warning message instead. (Default: true) * * @see #getIssueFatalErrorIfNotFound */ virtual void setIssueFatalErrorIfNotFound(const bool flag) = 0; /** * Get the flag that indicates if the parser should issue fatal error if this input source * is not found. * *"Experimental - subject to change"
* * @return True if the parser should issue fatal error if this input source is not found. * False if the parser issue warning message instead. * @see #setIssueFatalErrorIfNotFound */ virtual bool getIssueFatalErrorIfNotFound() const = 0; /** * Called to indicate that this DOMInputSource is no longer in use * and that the implementation may relinquish any resources associated with it. * * Access to a released object will lead to unexpected result. */ virtual void release() = 0; //@} }; XERCES_CPP_NAMESPACE_END #endif