Refactor, adding comments, improving performance

git-svn-id: http://svn.apache.org/repos/asf/axis/axis2/c/core/trunk@929982 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 264 insertions, 399 deletions

diff --git a/axiom/include/axiom_element.h b/axiom/include/axiom_element.h
index 1e10167..cd1de06 100644
--- a/axiom/include/axiom_element.h
+++ b/axiom/include/axiom_element.h
@@ -43,22 +43,20 @@ extern "C"
      */
 
     /**
-      * Creates an AXIOM element with given local name
-      * @param env Environment. MUST NOT be NULL.
-      * @param parent parent of the element node to be created. can be NULL.
-      * @param localname local name of the elment. cannot be NULL.
-      * @param ns namespace of the element.  can be NULL.
-      *                       If the value of the namespace has not already been declared
-      *                       then the namespace structure ns will be declared and will be
-      *                       freed when the tree is freed.
-      *                       If the value of the namespace has already been declared using
-      *                       another namespace structure then the namespace structure ns
-      *                       will be freed.
-      * @param node This is an out parameter. cannot be NULL.
-      *                       Returns the node corresponding to the comment created.
-      *                       Node type will be set to AXIOM_ELEMENT
-      * @return a pointer to the newly created element struct
-      */
+     * Creates an AXIOM element with given local name
+     * @param env Environment. MUST NOT be NULL.
+     * @param parent parent of the element node to be created. can be NULL.
+     * @param localname local name of the element. cannot be NULL.
+     * @param ns namespace of the element.  can be NULL.
+     *                       If the value of the namespace has not already been declared
+     *                       then the namespace structure ns will be cloned and declared and will be
+     *                       freed when the tree is freed.
+     *                       Caller has to delete the original ns object passed to the method.
+     * @param node This is an out parameter. cannot be NULL.
+     *                       Returns the node corresponding to the comment created.
+     *                       Node type will be set to AXIOM_ELEMENT
+     * @return a pointer to the newly created element struct
+     */
     AXIS2_EXTERN axiom_element_t *AXIS2_CALL
     axiom_element_create(
         const axutil_env_t * env,
@@ -83,11 +81,37 @@ extern "C"
         axiom_node_t * parent,
         const axutil_qname_t * qname,
         axiom_node_t ** node);
-    /*
+
+    /**
+     * Frees given element
+     * @param element AXIOM element to be freed.
+     * @param env Environment. MUST NOT be NULL.
+     * @return status of the operation. AXIS2_SUCCESS on success ,AXIS2_FAILURE on error.
+     */
+    AXIS2_EXTERN void AXIS2_CALL
+    axiom_element_free(
+        axiom_element_t * element,
+        const axutil_env_t * env);
+
+    /**
+     * finds a namespace in current element's scope, by uri or prefix or both
+     * @param om_element pointer to om_element
+     * @param env environment MUST not be NULL
+     * @param uri namespace uri, may be null
+     * @param prefix prefix
+     * @return axiom_namespace_t if found, else return NULL
+     */
+    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
+    axiom_element_find_declared_namespace(
+        axiom_element_t * om_element,
+        const axutil_env_t * env,
+        const axis2_char_t * uri,
+        const axis2_char_t * prefix);
+
+    /**
      * Find a namespace in the scope of the document.
      * Start to find from the given node and go up the hierarchy.
-     * @param om_element pointer to om_element_struct contained in
-     *        node , 
+     * @param om_element pointer to om_element_struct contained in node ,
      * @param env Environment. MUST NOT be NULL.
      * @param node node containing an instance of an AXIOM element,cannot be NULL.
      * @param uri namespace uri..
@@ -104,41 +128,12 @@ extern "C"
         const axis2_char_t * prefix);
 
     /**
-      * Declare a namespace in current element (in the scope of this element ).
-      * It checks to see if it is already declared.
-      * @param om_element contained in the om node struct
-      * @param env Environment. MUST NOT be NULL.
-      * @param node node containing an instance of an AXIOM element.
-      * @param ns pointer to the namespace struct to be declared
-      * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE.
-      */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_declare_namespace(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_node_t * node,
-        axiom_namespace_t * ns);
-    /**
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE.
-     *
-     */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_declare_namespace_assume_param_ownership(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_namespace_t * ns);
-
-    /**
-     * Finds a namespace using qname
-     * Start to find from the given node and go up the hierarchy.
+     * Finds a namespace using qname. Start to find from the given node and go up the hierarchy.
      * @param om_element om_element contained in node
      * @param env Environment. MUST NOT be NULL.
-     * @param node node containing an instance of an AXIOM element, cannot be NULL.   
+     * @param node node containing an instance of an AXIOM element, cannot be NULL.
      * @param qname qname of the namespace to be found. cannot be NULL.
-     * @return pointer to the namespace, if found, else NULL. On error, returns 
+     * @return pointer to the namespace, if found, else NULL. On error, returns
      *           NULL and sets the error code in environment's error struct.
      */
     AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
@@ -149,211 +144,212 @@ extern "C"
         axutil_qname_t * qname);
 
     /**
-      * Adds an attribute to current element The current element takes responsibility of the assigned attribute
-      * @param om_element element to which the attribute is to be added.cannot be NULL.
+      * Declare a namespace in current element (in the scope of this element ).
+      * It checks to see if it is already declared at this level or in its ancestors
+      * @param om_element contained in the om node struct
       * @param env Environment. MUST NOT be NULL.
-      * @param attribute attribute to be added.
-      * @param node axiom_node_t node that om_element is contained in
-      * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE.
+      * @param node node containing an instance of an AXIOM element.
+      * @param ns pointer to the namespace struct to be declared. Should not be null
+      * @return status of the operation. AXIS2_SUCCESS on success else AXIS2_FAILURE.
       */
     AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_add_attribute(
+    axiom_element_declare_namespace(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_attribute_t * attribute,
-        axiom_node_t * node);
+        axiom_node_t * node,
+        axiom_namespace_t * ns);
 
     /**
-      * Gets (finds) the attribute with the given qname
-      * @param element element whose attribute is to be found. 
-      * @param env Environment. MUST NOT be NULL.
-      * @qname qname qname of the attribute to be found. should not be NULL.
-      * @return a pointer to the attribute with given qname if found, else NULL.
-      *           On error, returns NULL and sets the error code in environment's error struct.
-      */
-    AXIS2_EXTERN axiom_attribute_t *AXIS2_CALL
-    axiom_element_get_attribute(
+     * get the namespace  of om_element
+     * @param om_element om_element struct
+     * @param env environment, MUST NOT be NULL.
+     * @returns pointer to axiom_namespace_t struct
+     *          NULL if there is no namespace associated with the element,
+     *          NULL on error with error code set to environment's error
+     */
+    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
+    axiom_element_get_namespace(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axutil_qname_t * qname);
+        axiom_node_t * ele_node);
 
     /**
-    * Gets (finds) the attribute value with the given qname
-    * @param element element whose attribute is to be found. 
-    * @param env Environment. MUST NOT be NULL.
-    * @qname qname qname of the attribute to be found. should not be NULL.
-    * @return the attribute value with given qname if found, else NULL.
-    *  On error, returns NULL and sets the error code in environment's error struct.
-    */
-    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
-    axiom_element_get_attribute_value(
+     * set the namespace of the element
+     * @param om_element pointer to om_element
+     * @param env environment MUST not be NULL
+     * @param ns pointer to namespace. Must not be NULL
+     *                       If the value of the namespace has not already been declared
+     *                       then the namespace structure ns will be declared and will be
+     *                       freed when the tree is freed.
+     * @returns status code of the op, with error code
+     *                  set to environment's error
+     */
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_set_namespace(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axutil_qname_t * qname);
+        axiom_namespace_t * ns,
+        axiom_node_t * node);
 
     /**
-      * Frees given element 
-      * @param element AXIOM element to be freed.
-      * @param env Environment. MUST NOT be NULL.
-       * @return satus of the op. AXIS2_SUCCESS on success ,AXIS2_FAILURE on error.
-      */
-    AXIS2_EXTERN void AXIS2_CALL
-    axiom_element_free(
-        axiom_element_t * element,
+     * get the namespace list of the element
+     * @param om_element pointer to om_element
+     * @param env environment MUST not be NULL
+     * @returns axutil_hash pointer to namespaces hash
+     * this hash table is read only
+     */
+    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
+    axiom_element_get_namespaces(
+        axiom_element_t * om_element,
         const axutil_env_t * env);
 
     /**
-      * Serializes the start part of the given element
-      * @param element element to be serialized.
-      * @param env Environment. MUST NOT be NULL.
-      * @param om_output AXIOM output handler to be used in serializing
-      * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE
-      */
+     * Adds an attribute to current element. The current element takes responsibility of the
+     * assigned attribute
+     * @param om_element element to which the attribute is to be added.cannot be NULL.
+     * @param env Environment. MUST NOT be NULL.
+     * @param attribute attribute to be added.
+     * @param node axiom_node_t node that om_element is contained in
+     * @return status of the operation. AXIS2_SUCCESS on success else AXIS2_FAILURE.
+     */
     AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_serialize_start_part(
+    axiom_element_add_attribute(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_output_t * om_output,
-        axiom_node_t * ele_node);
+        axiom_attribute_t * attribute,
+        axiom_node_t * node);
 
     /**
-     * Serializes the end part of the given element. serialize_start_part must 
-     *     have been called before calling this method.
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * @param om_output AXIOM output handler to be used in serializing
-     * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE
+     * Gets (finds) the attribute with the given qname
+     * @param element element whose attribute is to be found.
+     * @param env Environment. MUST NOT be NULL.
+     * @qname qname qname of the attribute to be found. should not be NULL.
+     * @return a pointer to the attribute with given qname if found, else NULL.
+     *           On error, returns NULL and sets the error code in environment's error struct.
      */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_serialize_end_part(
+    AXIS2_EXTERN axiom_attribute_t *AXIS2_CALL
+    axiom_element_get_attribute(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_output_t * om_output);
+        axutil_qname_t * qname);
 
     /**
-     * finds a namespace in current element's scope, 
-     *     by uri or prefix or both
+     * get  the attribute list of the element
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param uri namespace uri, may be null
-     * @param prefix prefix 
-     * @return axiom_namespace_t if found, else return NULL
+     * @returns axutil_hash pointer to attributes hash
+     * This hash table is read only
      */
-
-    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
-    axiom_element_find_declared_namespace(
+    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
+    axiom_element_get_all_attributes(
         axiom_element_t * om_element,
-        const axutil_env_t * env,
-        const axis2_char_t * uri,
-        const axis2_char_t * prefix);
+        const axutil_env_t * env);
 
     /**
-     * returns the localname of this element
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @returns localname of element, returns NULL on error.
+     * Gets (finds) the attribute value with the given qname
+     * @param element element whose attribute is to be found.
+     * @param env Environment. MUST NOT be NULL.
+     * @qname qname qname of the attribute to be found. should not be NULL.
+     * @return the attribute value with given qname if found, else NULL.
+     *  On error, returns NULL and sets the error code in environment's error struct.
      */
     AXIS2_EXTERN axis2_char_t *AXIS2_CALL
-    axiom_element_get_localname(
+    axiom_element_get_attribute_value(
         axiom_element_t * om_element,
-        const axutil_env_t * env);
+        const axutil_env_t * env,
+        axutil_qname_t * qname);
 
     /**
-     * set the localname of this element
+     *  Extract attributes , returns a clones hash table of attributes,
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @localname text value to be set as localname 
-     * @returns status code of op, AXIS2_SUCCESS on success,
-     *                   AXIS2_FAILURE on error.
+     * @param om_node pointer to this element node
      */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_set_localname(
+    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
+    axiom_element_extract_attributes(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        const axis2_char_t * localname);
+        axiom_node_t * ele_node);
 
     /**
-     * get the namespace  of om_element 
-     * @param om_element om_element struct
-     * @param env environemt, MUST NOT be NULL.
-     * @returns pointer to axiom_namespace_t struct 
-     *          NULL if there is no namespace associated with the element,
-     *          NULL on error with error code set to environment's error
+     * Returns the attribute value as a string for the given element
+     * @param om_element pointer to om_element
+     * @param env environment MUST not be NULL
+     * @param attr_name the attribute name
+     * @return the attribute value as a string
      */
-    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
-    axiom_element_get_namespace(
-        axiom_element_t * om_element,
+    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
+    axiom_element_get_attribute_value_by_name(
+        axiom_element_t * om_ele,
         const axutil_env_t * env,
-        axiom_node_t * ele_node);
+        axis2_char_t * attr_name);
 
     /**
-     * set the namespace of the element
+     * Select all the text children and concatenate them to a single string. The string
+     * returned by this method call will be free by axiom when this method is called again.
+     * So it is recommended to have a copy of the return value if this method is going to
+     * be called more that once and the return values of the earlier calls are important.
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param ns pointer to namespace
-     *                       If the value of the namespace has not already been declared
-     *                       then the namespace structure ns will be declared and will be 
-     *                       freed when the tree is freed.
-     * @returns status code of the op, with error code 
-     *                  set to environment's error
+     * @param element node , the container node of this om element
+     * @return the concatenated text of all text children text values
+     *         return null if no text children is available or on error
      */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_set_namespace(
+    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
+    axiom_element_get_text(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_namespace_t * ns,
-        axiom_node_t * node);
-
+        axiom_node_t * element_node);
 
     /**
-     * unconditionally set the namespace of the element
+     * Sets the text of the given element.
+     * caution - This method will wipe out all the text elements (and hence any mixed content)
+     * before setting the text
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param ns pointer to namespace
-     *                       The namespace ns is assumed to have been declared already.
-     * @returns status code of the op, with error code
-     *                  set to environment's error
+     * @param text text to set.
+     * @param element_node node of element.
+     * @return AXIS2_SUCCESS if attribute was found and removed, else
+     *           AXIS2_FAILURE
      */
     AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_set_namespace_assume_param_ownership(
+    axiom_element_set_text(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_namespace_t * ns);
+        const axis2_char_t * text,
+        axiom_node_t * element_node);
 
     /**
-     * get  the attribute list of the element 
+     * returns the localname of this element
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @returns axutil_hash poiner to attributes hash
-     * This hash table is read only 
+     * @returns localname of element, returns NULL on error.
      */
-    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
-    axiom_element_get_all_attributes(
+    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
+    axiom_element_get_localname(
         axiom_element_t * om_element,
         const axutil_env_t * env);
 
     /**
-     * get the namespace list of the element
+     * set the localname of this element
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @returns axutil_hash pointer to namespaces hash
-     * this hash table is read only
+     * @localname text value to be set as localname
+     * @returns status code of operation, AXIS2_SUCCESS on success,
+     *                   AXIS2_FAILURE on error.
      */
-    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
-    axiom_element_get_namespaces(
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_set_localname(
         axiom_element_t * om_element,
-        const axutil_env_t * env);
+        const axutil_env_t * env,
+        const axis2_char_t * localname);
 
     /**
-     *@return qname of this element
-     * the returned qname should not be externaly freed
-     * when om_element struct is freed qname is also
-     * freed 
+     * return qname of this element. The returned qname should not be freed by the caller.
+     * It will be freed when om_element struct is freed
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param ele_node pointer to this element node
-     *
      * @returns axutil_qname_t struct , NULL on failure
      */
     AXIS2_EXTERN axutil_qname_t *AXIS2_CALL
@@ -363,14 +359,11 @@ extern "C"
         axiom_node_t * ele_node);
 
     /**
-     *   returns a list of children iterator
-     *   returned iterator is freed when om_element struct
-     *   is freed
-     *   iterators reset function must be called by user
+     * returns a list of children iterator. Returned iterator is freed when om_element struct
+     * is freed.
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param element_node pointer to this element node
-     *
      */
     AXIS2_EXTERN axiom_children_iterator_t *AXIS2_CALL
     axiom_element_get_children(
@@ -379,15 +372,13 @@ extern "C"
         axiom_node_t * element_node);
 
     /**
-     *   returns a list of children iterator with qname
-     *   returned iterator is freed when om element struct
-     *  is freed 
+     * returns a list of children iterator with qname. Returned iterator is freed when om element
+     * struct is freed
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param element_node pointer to this element node
      * @returns children qname iterator struct
      */
-
     AXIS2_EXTERN axiom_children_qname_iterator_t *AXIS2_CALL
     axiom_element_get_children_with_qname(
         axiom_element_t * om_element,
@@ -396,16 +387,15 @@ extern "C"
         axiom_node_t * element_node);
 
     /**
-     * Returns the om_element corresponding to element_qname
+     * Returns the first om_element corresponding to element_qname
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param element_qname qname of the element 
+     * @param element_qname qname of the element
      * @param om_node pointer to this element node
-     * @param element_node 
-     * @param child_node 
+     * @param element_node
+     * @param child_node
      * @returns children qname iterator struct
      */
-
     AXIS2_EXTERN axiom_element_t *AXIS2_CALL
     axiom_element_get_first_child_with_qname(
         axiom_element_t * om_element,
@@ -415,62 +405,11 @@ extern "C"
         axiom_node_t ** child_node);
 
     /**
-     * removes an attribute from the element attribute list
-     * user must free this attribute, element free function does not free 
-     * attributes that are not is it's attribute list
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_attribute attribute to be removed
-     * @return AXIS2_SUCCESS if attribute was found and removed, else 
-     *           AXIS2_FAILURE
-     */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_remove_attribute(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_attribute_t * om_attribute);
-
-    /**
-     * Sets the text of the given element.
-     * caution - This method will wipe out all the text elements (and hence any
-     * mixed content) before setting the text
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param text text to set.
-     * @param element_node node of element.
-     * @return AXIS2_SUCCESS if attribute was found and removed, else 
-     *           AXIS2_FAILURE
-     */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_set_text(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        const axis2_char_t * text,
-        axiom_node_t * element_node);
-
-    /**
-     * Select all the text children and concatenate them to a single string. The string
-	 * returned by this method call will be free by axiom when this method is called again. 
-	 * So it is recommended to have a copy of the return value if this method is going to
-	 * be called more that once and the return values of the earlier calls are important.
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param element node , the container node of this om element
-     * @return the concatenated text of all text children text values
-     *         return null if no text children is available or on error
-     */
-    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
-    axiom_element_get_text(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_node_t * element_node);
-
-    /**
      * returns the first child om element of this om element node
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param om_node pointer to this element node
-     * @return om_element if one is availble otherwise return NULL
+     * @return om_element if one is available otherwise return NULL
      */
     AXIS2_EXTERN axiom_element_t *AXIS2_CALL
     axiom_element_get_first_element(
@@ -480,84 +419,88 @@ extern "C"
         axiom_node_t ** first_element_node);
 
     /**
-     * returns the serilized text of this element and its children
+     * returns an iterator with child elements of type AXIOM_ELEMENT
+     * iterator is freed when om_element node is freed
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param element_node the container node this on element is contained 
-     * @return a char array of xml , returns NULL on error
+     * @param element_node
+     * @returns axiom_child_element_iterator_t , NULL on error
      */
-    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
-    axiom_element_to_string(
+    AXIS2_EXTERN axiom_child_element_iterator_t *AXIS2_CALL
+    axiom_element_get_child_elements(
         axiom_element_t * om_element,
         const axutil_env_t * env,
         axiom_node_t * element_node);
 
+#if 0
     /**
-     * returns an iterator with child elements of type AXIOM_ELEMENT
-     * iterator is freed when om_element node is freed
+     * builds this om_element_node completely, This is only possible
+     * if the om_stax_builder is associated with the om_element_node,
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param element_node
-     * @returns axiom_child_element_iterator_t , NULL on error    
+     * @param om_node pointer to this element node
+     * @param element_node corresponding om element node of this om element
+     * struct
+     * @returns AXIS2_SUCCESS if this element node was successfully completed,
+     * otherwise returns AXIS2_FAILURE
      */
-    AXIS2_EXTERN axiom_child_element_iterator_t *AXIS2_CALL
-    axiom_element_get_child_elements(
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_build(
         axiom_element_t * om_element,
         const axutil_env_t * env,
         axiom_node_t * element_node);
 
-
-
     /**
-     * retrieves the default namespace of this element , if available,
-     * @param om_element pointer to om element
-     * @param env axutil_environment MUST Not be NULL
-     * @param element_node corresponding om element node of this om element
-     * @returns pointer to default namespace if availale , NULL otherwise
+     * checks for the namespace in the context of this element
+     * with the given prefix
+     * @param om_element pointer to om_element
+     * @param env environment MUST not be NULL
+     * @param om_element_node pointer to this element node
+     * @returns pointer to relevent namespace
      */
     AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
-    axiom_element_get_default_namespace(
+    axiom_element_find_namespace_uri(
         axiom_element_t * om_element,
         const axutil_env_t * env,
+        const axis2_char_t * prefix,
         axiom_node_t * element_node);
 
     /**
-     * declared a default namespace explicitly 
-     * @param om_element pointer to om element
+     * Returns the Local name of the element
+     * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param uri namespace uri of the default namespace
-     * @returns the declared namespace
-                                                 */
-    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
-    axiom_element_declare_default_namespace(
+     * @param om_node pointer to this element node
+     *
+     * @return the Local name of the element
+     */
+    AXIS2_EXTERN axutil_string_t *AXIS2_CALL
+    axiom_element_get_localname_str(
         axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axis2_char_t * uri);
+        const axutil_env_t * env);
 
     /**
-     * checks for the namespace in the context of this element 
-     * with the given prefix 
+     * Set the Local name of the element
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param om_element_node pointer to this element node
-     * @returns pointer to relevent namespace 
+     * @param localname  the Local name of the element
+     *
+     * @return
      */
-    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
-    axiom_element_find_namespace_uri(
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_set_localname_str(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        const axis2_char_t * prefix,
-        axiom_node_t * element_node);
+        axutil_string_t * localname);
 
     /**
-     *This will not search the namespace in the scope nor will 
+     *This will not search the namespace in the scope nor will
      * declare in the current element, as in set_namespace. This will
      * just assign the given namespace to the element.
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param om_node pointer to this element node
      * @param om_ns pointer to namespace to be set
-     * @returns 
+     * @returns
      */
     AXIS2_EXTERN axis2_status_t AXIS2_CALL
     axiom_element_set_namespace_with_no_find_in_current_scope(
@@ -566,32 +509,45 @@ extern "C"
         axiom_namespace_t * om_ns);
 
     /**
-     *  Extract attributes , returns a clones hash table of attributes,
-     *  if attributes are associated with a namespace it is also cloned
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
      * @param om_node pointer to this element node
+     * @return satus of the op. AXIS2_SUCCESS on success else AXIS2_FAILURE.
      *
      */
-    AXIS2_EXTERN axutil_hash_t *AXIS2_CALL
-    axiom_element_extract_attributes(
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_declare_namespace_assume_param_ownership(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_node_t * ele_node);
+        axiom_namespace_t * ns);
 
     /**
-     * Returns the attribute value as a string for the given element
+     * unconditionally set the namespace of the element
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param attr_name the attribute name
-     * 
-     * @return the attribute value as a string
+     * @param ns pointer to namespace
+     *                       The namespace ns is assumed to have been declared already.
+     * @returns status code of the op, with error code
+     *                  set to environment's error
      */
-    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
-    axiom_element_get_attribute_value_by_name(
-        axiom_element_t * om_ele,
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_set_namespace_assume_param_ownership(
+        axiom_element_t * om_element,
         const axutil_env_t * env,
-        axis2_char_t * attr_name);
+        axiom_namespace_t * ns);
+
+    /**
+     * declared a default namespace explicitly
+     * @param om_element pointer to om element
+     * @param env environment MUST not be NULL
+     * @param uri namespace uri of the default namespace
+     * @returns the declared namespace
+     */
+    AXIS2_EXTERN axiom_namespace_t *AXIS2_CALL
+    axiom_element_declare_default_namespace(
+        axiom_element_t * om_element,
+        const axutil_env_t * env,
+        axis2_char_t * uri);
 
     /**
      * Create an OM Element and an OM node from given string params
@@ -600,7 +556,7 @@ extern "C"
      * @param localname the locanmae of the element
      * @param ns the namespace of the element
      * @param node the reference ot the created node
-     * @return 
+     * @return
      */
     AXIS2_EXTERN axiom_element_t *AXIS2_CALL
     axiom_element_create_str(
@@ -611,37 +567,10 @@ extern "C"
         axiom_node_t ** node);
 
     /**
-     * Returns the Local name of the element
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * 
-     * @return the Local name of the element
-     */
-    AXIS2_EXTERN axutil_string_t *AXIS2_CALL
-    axiom_element_get_localname_str(
-        axiom_element_t * om_element,
-        const axutil_env_t * env);
-
-    /**
-     * Set the Local name of the element
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param localname  the Local name of the element 
-     * 
-     * @return
-     */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_set_localname_str(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axutil_string_t * localname);
-
-    /**
      * Return whether the element is empty or not
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * 
+     *
      * @return AXIS2_TRUE if empty AXIS2_FALSE if not empty
      */
     AXIS2_EXTERN axis2_bool_t AXIS2_CALL
@@ -650,97 +579,33 @@ extern "C"
         const axutil_env_t * env);
 
     /**
-     * Set whether the element is empty or not
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param is_empty AXIS2_TRUE if empty AXIS2_FALSE if not empty
-     * 
-     * @return VOID
-     */
-    AXIS2_EXTERN void AXIS2_CALL
-    axiom_element_set_is_empty(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axis2_bool_t is_empty);
-
-    /**
-     * Collect all the namespaces with distinct prefixes in 
-     * the parents of the given element.  Effectively this 
-     * is the set of namespaces declared above this element  
-     * that are inscope at this element and might be used   
-     * by it or its children. 
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * @returns pointer to hash of relevent namespaces
-     */
-    AXIS2_EXTERN axutil_hash_t * AXIS2_CALL
-    axiom_element_gather_parent_namespaces(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_node_t * om_node);
-
-    /**
-     * If the provided namespace used by the provided element 
-     * is one of the namespaces from the parent of the root  
-     * root element, redeclares that namespace at the root element
-     * and removes it from the hash of parent namespaces
-     * @param om_element pointer to om_element
-     * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * @param ns pointer to namespace to redeclare
-     * @param root_element pointer to the subtree root element node
-     * @param inscope_namespaces pointer to hash of parent namespaces
-     */
-    AXIS2_EXTERN void AXIS2_CALL
-    axiom_element_use_parent_namespace(
-        axiom_element_t * om_element,
-        const axutil_env_t * env,
-        axiom_node_t * om_node,
-        axiom_namespace_t *ns,
-        axiom_element_t * root_element,
-        axutil_hash_t *inscope_namespaces);
-
-    /**
-     * Examines the subtree beginning at the provided element 
-     * For each element or attribute, if it refers to a namespace   
-     * declared in a parent of the subtree root element, redeclares
-     * that namespace at the level of the subtree root and removes
-     * it from the set of parent namespaces in scope and not yet 
-     * declared
+     * removes an attribute from the element attribute list
+     * user must free this attribute, element free function does not free
+     * attributes that are not is it's attribute list
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     *
-     * @param root_element pointer to the subtree root element node
-     * @param inscope_namespaces pointer to hash of parent namespaces
+     * @param om_attribute attribute to be removed
+     * @return AXIS2_SUCCESS if attribute was found and removed, else
+     *           AXIS2_FAILURE
      */
-    AXIS2_EXTERN void AXIS2_CALL
-    axiom_element_redeclare_parent_namespaces(
+    AXIS2_EXTERN axis2_status_t AXIS2_CALL
+    axiom_element_remove_attribute(
         axiom_element_t * om_element,
         const axutil_env_t * env,
-        axiom_node_t * om_node,
-        axiom_element_t * root_element,
-        axutil_hash_t *inscope_namespaces);
+        axiom_attribute_t * om_attribute);
 
-#if 0
     /**
-     * builds this om_element_node completely, This is only possible
-     * if the om_stax_builder is associated with the om_element_node,
+     * returns the serilized text of this element and its children
      * @param om_element pointer to om_element
      * @param env environment MUST not be NULL
-     * @param om_node pointer to this element node
-     * @param element_node corresponding om element node of this om element
-     * struct
-     * @returns AXIS2_SUCCESS if this element node was successfully completed,
-     * otherwise returns AXIS2_FAILURE
+     * @param element_node the container node this on element is contained
+     * @return a char array of xml , returns NULL on error
      */
-    AXIS2_EXTERN axis2_status_t AXIS2_CALL
-    axiom_element_build(
+    AXIS2_EXTERN axis2_char_t *AXIS2_CALL
+    axiom_element_to_string(
         axiom_element_t * om_element,
         const axutil_env_t * env,
         axiom_node_t * element_node);
-
 #endif
     /** @} */