/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef DOMInputSource_HEADER_GUARD_

#define DOMInputSource_HEADER_GUARD_

/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You under the Apache License, Version 2.0

 * (the "License"); you may not use this file except in compliance with

 * the License.  You may obtain a copy of the License at

 * 

 *      http://www.apache.org/licenses/LICENSE-2.0

 * 

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

/*

 * $Id: DOMInputSource.hpp 568078 2007-08-21 11:43:25Z amassari $

 */

#include <xercesc/util/XercesDefs.hpp>

XERCES_CPP_NAMESPACE_BEGIN

class BinInputStream;

/**

  * This interface represents a single input source for an XML entity.

  *

  * <p>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.</p>

  *

  * <p>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.</p>

  *

  * <p>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.</p>

  *

  * <p>A DOMInputSource object belongs to the application: the parser shall

  * never modify it in any way (it may modify a copy if necessary).</p>

  *

  * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * <p>If the system ID is a URL, it will be fully resolved.</p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p>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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p>The public identifier is always optional: if the application writer

     * includes one, it will be provided as part of the location information.</p>

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p>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.</p>

     *

     * <p>If the system ID is a URL, it must be fully resolved.</p>

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p>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.

     * </p>

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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.

     *

     * <p><b>"Experimental - subject to change"</b></p>

     *

     * @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