/*

* Copyright (c) 2008 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:

*

*/

/** @file

@publishedAll

@released

*/

#ifndef XMLENGELEMENT_H

#define XMLENGELEMENT_H

#include <xml/dom/xmlengattr.h>

#include <xml/dom/xmlengnamespace.h>

template<class T> class RXmlEngNodeList;

/**

This class represents an XML element in the DOM tree.

Namespace handling:

The namespace of a XML element is an URI that in pair with the local part of

the element's name consistute the @c expanded-name of the element. It is said

that "the element is of NNN namespace".

XML elements are shown as belonging to a specific namespace by using prefixes

that previously were bound to some namespace URIs. The scope of a prefix is the

element, where it was declared and all its child (sub-)elements.

Namespace declaration is created by using a special @c xmlns:{prefix-name} 

attribute (which is not really considered as an attribute in DOM):

@code 

   <a xmlns:pr="http://some.uri.com/"> ... </a>

OR

   <pr:a xmlns:pr="http://some.uri.com/"> ... </a>

   <a xmlns="http://some.uri.com/"> ... </a>

@endcode

The latter two examples are equivalent and show the use of @c default namespace.

Implementation notes:

- Elements having no namespace are either presented with a NULL 

  TXmlEngNamespace node or a TXmlEngNamespace node that has NULL (KNullDesC8)

  prefix and namespace URI set to "" (an empty descriptor).  The former is 

	used by default on all nodes, whereas the latter is for cases when some node 

	contains undeclaration of the default namespace:

  @code

	   <a xmlns=""> .. </a>

  @endcode

- The prefix of the default attribute is NULL (KNullDesC8), not an "" (empty

	descriptor).  An empty descriptor which corresponds to

  @code

      <a xmlns:="http://some.uri.com/"> ... </a>

  @endcode

  (it does not contradict XML spec, but you are strongly advised against using 

  this)

- Prefix "xml" is reserved by XML Namespace spec for special purposes; it is 

  implicitly bound to XML's namespace <i>"http://www.w3.org/XML/1998/namespace"</i> 

  and no one is allowed to use this prefix except as with spec-defined 

  elements and attributes or to rebind this prefix to other namespaces

- Namespace URI may be "" (an empty descriptor) only for default namespace. In

  other words, "" namespace URI may not be bound to non-NULL prefix.

  Declaration of "" (an empty descriptor) namespace with NULL (KNullDesC8) 

  prefix results in:

  @code

      <a xmlns=""> ... </a>

  @endcode

  which undeclares any existing (in some parent element) default namespace

  for the scope of element 'a': element, its attributes and all child nodes 

  of DOM tree. Note, that such "undeclaration" will be added only if neccessary.

- Unneccessary namespace declaration are ignored. Attemps to add namespace binding 

  using same namespace URI and prefix if such binding already exists in the scope

  will have no effect.

- IMPORTANT! Attributes DO NOT HAVE default namespaces. If an attribute has no

  prefix, its namespace is undeclared even if there is some default namespaces for

  the scope of the element, which contains the attribute.

So, it is wrong to write something like this:

@code

    <a xmlns="ns_uri"  attr="value"> ... </a>

@endcode

and assume that the attr belongs to namespace pointed to with @c ns_uri.

HINTS:

- Use namespace declaration nodes as much as possible (but watch out for prefix collisions).

- Add most referred to namespace declarations (AddNamespaceDeclarationL(uri,pref)) after

  any other namespace declarations in a element -- they will be found faster in

  namespace lookups.

For more informarion on NULL and NULL nodes:

@see TXmlEngNode

@see KNullDesC8

*/

class TXmlEngElement : public TXmlEngNode

{

  public:

    /** Default constructor */

    inline TXmlEngElement();

    /**

    Constructor

	@param aInternal element pointer

	*/

    inline TXmlEngElement(void* aInternal);

    /*

	Extensions to the DOM Level 3 Core methods

	*/

    /**

    Retrieves a list of the attribute nodes of an element

	Upon return, aList is initialized and is ready for use with HasNext() and

	Next() methods:

      @code

          ...

          TXmlEngElement root = doc.DocumentElement();

          RXmlEngNodeList<TXmlEngAttr>    attlist;

          root.GetAttributes(attlist);

          while (attlist.HasNext())

              processAttribute(attlist.Next());

          ...

	      attlist.Close();

      @endcode

		If there are no attributes the list will be empty.

    @param aList An attribute list to initialize

    */

    IMPORT_C void GetAttributes(RXmlEngNodeList<TXmlEngAttr>& aList) const;

    /**

    Retrieves a list of child elements of an element.

	Upon return, aList is initialized and is ready for use with HasNext() and

	Next() methods.

	Note: This returns a list of the child element nodes only.

	There is no affect if the element attributes are empty.

	@param aList A child list to initialize

	*/ 

    IMPORT_C void GetChildElements(RXmlEngNodeList<TXmlEngElement>& aList) const;

	/**

	Creates a new attribute node outside of any namespace (i.e. it has no

	prefix), sets the attribute's value and links it as the last attribute of

	the current element.

	Note:

			- No checks are made that an attribute with the same name exists.

              Use this method only on newly created elements!

              Otherwise, use TXmlEngElement::SetAttributeL()

            - Attributes do not inherit default namespace of its element

              (http://w3.org/TR/REC-xml-names/#defaulting)

            - The attribute's value is the second argument in all AddNewAttributeL() methods

    When adding the first attribute, use TXmlEngNode::SetAsFirstSibling() on the attribute:

    @code

        TXmlEngElement el = ... ; // get some element

        el.AddNewAttributeL("version","0.1").SetAsFirstSibling();

    @endcode

	 Copies are taken of descripters passed in.

	@see SetAsLastSibling()

	@see MoveBeforeSibling(TXmlEngNode) 

	@see MoveAfterSibling(TXmlEngNode)

	 * 

	@param  aName   A local name of the attribute

	@param  aValue  Value to set for new attribute or KNullDesC8

	@return The created attribute

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aName is empty

	@leave - One of the system-wide error codes

	*/

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, const TDesC8& aValue);

    /**

    Creates a new attribute node and adds it to the element.

	The provided namespace declaration is used to set the attribute's namespace.

	Note:  If aNsDef is not defined in some of the attribute's ascendants

	(including this element), then the ReconcileNamespacesL() method must be

	called on this element later.

	 Copies are taken of descripters passed in.

	@param  aName   The local name of attribute

	@param  aValue  Value to set for new attribute or KNullDesC8

	@param  aNsDef  Namespace to add to the attribute

	@return The created attribute

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aName is empty

	@leave - One of the system-wide error codes

	*/

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName,

                                    const TDesC8& aValue, 

                                    const TXmlEngNamespace aNsDef);

	/**

	Creates a new attribute for the element. A namespace declaration for the

	attribute namespace is also created.

	Note:  Namespace declarations are reused if possible (no redundant ones are

	created)

	 Copies are taken of descripters passed in.

	@param  aName   The local name of attribute

    @param  aValue  Value to set for the new attribute or an empty string

    @param  aNsUri  Namespace URI

    @param  aPrefix  Namespace prefix

    @return The created attribute

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aName is empty

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngAttr AddNewAttributeL(const TDesC8& aName, 

                                    const TDesC8& aValue,

                                    const TDesC8& aNsUri, 

                                    const TDesC8& aPrefix);

	/**

	Creates a new attribute node using the namespace of its parent element

	(this element), sets the attribute's value and links it as the last

	attribute of the element

    For more hints how to use it @see AddNewAttributeL(const TDesC8&,const TDesC8&)

	Note:

        - No checks are made that an attribute with the same name exists

        - if the namespace of the parent element is default (i.e. bound prefix is KNullDesC8),

          then a temporary prefix will be used and bound to the same namespace URI as the element

          (It is due to the fact that default namespaces do not spread on unprefixed attributes,

          see http://w3.org/TR/REC-xml-names/#defaulting)

	 Copies are taken of descripters passed in.

	 @see KNullDesC8

	@param aName Local name of attribute 

    @param aValue Value to set for the new attribute or empty.

    @return The created attribute

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aName is empty

	@leave - One of the system-wide error codes

    */

    inline   TXmlEngAttr AddNewAttributeSameNsL(const TDesC8& aName, const TDesC8& aValue);

    /**

    Creates a new attribute using the namespace which is bound to the specified prefix

    Use this mothod only for construction of new parts of DOM tree where

    you know for sure that the prefix is bound in the given scope.

    @code

        TXmlEngElement el = parent.AddNewAttributeUsePrefixL("property","ObjName","rdf");

        el.AddNewAttributeUsePrefixL("type", "xs:integer", "rdf");

    @endcode

    Otherwise, you should check that the prefix is bound like this example shows:

    @code

        TXmlEngNamespace boundNS = TXmlEngNamespace::LookupByPrefix(thisElement, prefix);

        if (boundNS.NotNull()){

            thisElement.AddNewAttributeUsePrefixL("name", value, prefix);

        }

    @endcode

	Note: Use AddNewAttributeNsL(name,value,nsDefNode) as much as you can,

	because it is the most efficient way to create namespaced DOM elements (no

	additional lookups for namespace declarations are required).

    @code

        // If namespace with given URI is not in the scope, then it will be declared

        // and bound to "data" prefix.

        TXmlEngNamespace nsDef = elem.FindOrCreateNsDefL("http://../Data", "data");

        elem.AddNewAttributeL("location", "...", nsDef);

        elem.AddNewElementL("child", nsDef).AddNewAttributeL("attr","...value...");

        // the result is

            ...

         <elem xmlns:data="http://../Data" data:location="...">

            <data:child attr="...value..."/>

         </elem>

            ...

        //

    @endcode    

	 Copies are taken of descripters passed in.

	@param  aLocalName   The local name of the attribute

    @param  aValue  Value to set for the new attribute or empty string.

    @param  aPrefix  Namespace prefix for the new attribute

    @return The created attribute

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aLocalName is empty

	@leave KErrNoMemory The namespace is not found and the URI is not

	http://www.w3.org/XML/1998/namespace; or there is a memory allocation error

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngAttr AddNewAttributeUsePrefixL(const TDesC8& aLocalName, 

                                             const TDesC8& aValue, 

                                             const TDesC8& aPrefix);

    /**

    Creates new attributes using the namespace in scope, which has the specified URI

    Almost the same as AddNewAttributeUsePrefixL() but does lookup by namespace URI

    @see AddNewAttributeUsePrefixL(const TDesC8&,const TDesC8&,const TDesC8&)

	 Copies are taken of descripters passed in.

	 @see KNullDesC8

	@param  aLocalName   The local name of the attribute

    @param  aValue  Value to set for new attribute or empty string.

    @param  aNsUri  Namespace URI for new attribute

	@return NULL attribute if namespace declaration is not found OR newly added

	to the end of attribute list attribute of this element.

	@leave KXmlEngErrNullNode The node is NULL

	@leave KXmlEngErrWrongUseOfAPI aLocalName is empty

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngAttr AddNewAttributeWithNsL(const TDesC8& aLocalName, 

                                          const TDesC8& aValue, 

                                          const TDesC8& aNsUri);

	/**

	Adds attribute to element that will be used as Xml:Id.  Does not check if

	an attribute with the same name exists.

	Note: Call RXmlEngDocument.RegisterXmlIdL(aName,aNsUri) first to register

	existed id's in the document.  If the ids are not registered the ID will

	not be added to the element.

	 Copies are taken of descripters passed in.

	@param aLocalName Name of the attribute

	@param aValue Value of the attribute

	@param aNs Namespace of the attribute

	@return Attribute if created. Null attribute if Xml:Id exists

	@leave KXmlEngErrWrongUseOfAPI Element is NULL or attribute doesn't exist

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngAttr AddXmlIdL(const TDesC8& aLocalName,

                                       const TDesC8& aValue,

                                       TXmlEngNamespace aNs = TXmlEngNamespace());

	/**

	Adds a child element with no namespace.  This results in adding an element

	with aName and no prefix.

	This method is the best for creation of non-namespace based documents

	or document fragments, where no default namespace declared.

	It may be used also as a method for adding elements from the default

	namespace, BUT namespace will be assigned ONLY after serialization of the

	current document and parsing it back into a DOM tree!! If you need the new

	element to inherit the default namespace use:

    @code

       ...

       TXmlEngNamespace defns = element.DefaultNamespace();

       TXmlEngElement newEl = element.AddNewElementL("Name",defns);

       ...

    @endcode

	It is not recommended that you use an undefined namespace with libxml.  

	If an undefined namespace for the element is truly required, then DO NOT

	USE this method if there is a default namespace in the scope!

	@see AddNamespaceDeclarationL

	Copies are taken of descripters passed in.

	@param aName The name of the element

	@return The created element

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name is not specified

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aName);

	/**

	Creates a new child element with the provided name and namespace

	declaration and adds it as the last child of its parent.

	 Copies are taken of descripters passed in.

	@param aLocalName The name of the element

    @param aNsDecl The namespace declaration that must be retrieved from

               one of the ascendant nodes of the new elements (and its prefix

               should not be remapped to another namespace URI for the scope

               of the new element)

    @return Created element node

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name is not specified

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, TXmlEngNamespace aNsDecl);

	/**

	Creates a new child element with provided the name, prefix and namespace

	URI and adds it as the last child of its parent.

	The new namespace declaration will be attached to the parent (this) element

	and used as the namespace for newly created child element. If such a

	binding already exists (same prefix is bound to same URI), it will be

	reused. If the prefix is already bound to some other namespace URI, it will

	be rebound by the new namespace declaration node.

	 Copies are taken of descripters passed in.

	@param aLocalName Name of the element

    @param aNsUri     URI of the element's namespace

    @param aPrefix    Prefix of the element

    @return The created element node 

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name or URI or prefix is not specified

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementL(const TDesC8& aLocalName, 

                                     const TDesC8& aNsUri, 

                                     const TDesC8& aPrefix);

	/**

	Creates a child element with the same namespace (and prefix if present) as

	the parent element and adds it as the last child of its parent.

	 Copies are taken of descripters passed in.

	@param aLocalName The element's name

    @return The created element

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name is not specified

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementSameNsL(const TDesC8& aLocalName);

	/**

	Performs a lookup for the namespace declaration for the specified prefix

	and adds a new child element with the found namespace as the last child of

	its parent.

	@pre The prefix is bound

	 Copies are taken of descripters passed in.

	@param aLocalName The element's name

    @param aPrefix    The prefix to use for the search

    @return The created element

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name is not specified

	@leave KErrNoMemory The namespace is not found and the prefix is not "xml" 

	(i.e http://www.w3.org/XML/1998/namespace); or there is a memory allocation 

	error.

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementUsePrefixL(const TDesC8& aLocalName, const TDesC8& aPrefix);

	/**

	Performs a lookup for the namespace declaration for the specified namespace

	URI and adds a new child element with the found namespace.  The new element

	is added as the last child of this element.

	 Copies are taken of descripters passed in.

	@pre A namespace with the given URI has been declared

	@param aLocalName    The element's name

    @param aNsUri        The namespace of the element

    @return The created element

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name is not specified

	@leave KErrNoMemory The namespace is not found and the URI is not http://www.w3.org/XML/1998/namespace 

	or there is a memory allocation error

	@leave - One of the system-wide error codes

    */

    IMPORT_C TXmlEngElement AddNewElementWithNsL(const TDesC8& aLocalName, const TDesC8& aNsUri);

	/**

	Creates a new child element.  If there is no a prefix binding for the new

	element's namespace, a namespace decaration is created with a generated

	prefix at the specified element.

	The location of the namespace declaration may be controlled with

	aNsDeclTarget:

    @code

        el.AddNewElementAutoPrefixL(tagName,uri,KNullDesC8); // declare on the new element

        el.AddNewElementAutoPrefixL(tagName,uri,el);   // declare on the parent element

        el.AddNewElementAutoPrefixL(tagName,uri,doc.DocumentElement()); // declare on the root element

       ...

    @endcode

	Note:  The farther namespace declaration up in the document tree, the

	longer the namespace declaration lookups take.

	 Copies are taken of descripters passed in.

	@param aLocalName    Name of the element to create

	@param aNsUri        Namespace URI of the new element

	@param aNsDeclTarget The element where the namespace declaraton should be placed.

	@return The created element

	@leave KXmlEngErrNullNode Element is NULL

	@leave KXmlEngErrWrongUseOfAPI Name or URI is not specified

	@leave - One of the system-wide error codes

    */