1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 #ifndef DOMTreeWalker_HEADER_GUARD_

    18 #define DOMTreeWalker_HEADER_GUARD_

    19 

    20 /*

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

    22  * contributor license agreements.  See the NOTICE file distributed with

    23  * this work for additional information regarding copyright ownership.

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

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

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

    27  * 

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

    29  * 

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

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

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

    33  * See the License for the specific language governing permissions and

    34  * limitations under the License.

    35  */

    36 

    37 /*

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

    39  */

    40 

    41 #include <xercesc/dom/DOMNode.hpp>

    42 #include <xercesc/dom/DOMNodeFilter.hpp>

    43 

    44 XERCES_CPP_NAMESPACE_BEGIN

    45 

    46 

    47 /**

    48  * <code>DOMTreeWalker</code> objects are used to navigate a document tree or

    49  * subtree using the view of the document defined by their

    50  * <code>whatToShow</code> flags and filter (if any). Any function which

    51  * performs navigation using a <code>DOMTreeWalker</code> will automatically

    52  * support any view defined by a <code>DOMTreeWalker</code>.

    53  * <p>Omitting nodes from the logical view of a subtree can result in a

    54  * structure that is substantially different from the same subtree in the

    55  * complete, unfiltered document. Nodes that are siblings in the

    56  * <code>DOMTreeWalker</code> view may be children of different, widely

    57  * separated nodes in the original view. For instance, consider a

    58  * <code>DOMNodeFilter</code> that skips all nodes except for DOMText nodes and

    59  * the root node of a document. In the logical view that results, all text

    60  * nodes will be siblings and appear as direct children of the root node, no

    61  * matter how deeply nested the structure of the original document.

    62  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.

    63  *

    64  * @since DOM Level 2

    65  */

    66 class CDOM_EXPORT DOMTreeWalker {

    67 protected:

    68     // -----------------------------------------------------------------------

    69     //  Hidden constructors

    70     // -----------------------------------------------------------------------

    71     /** @name Hidden constructors */

    72     //@{    

    73     DOMTreeWalker() {}

    74     DOMTreeWalker(const DOMTreeWalker &) {}

    75     //@}

    76 

    77 private:

    78     // -----------------------------------------------------------------------

    79     // Unimplemented constructors and operators

    80     // -----------------------------------------------------------------------

    81     /** @name Unimplemented constructors and operators */

    82     //@{

    83     DOMTreeWalker & operator = (const DOMTreeWalker &);

    84     //@}

    85 

    86 public:

    87     // -----------------------------------------------------------------------

    88     //  All constructors are hidden, just the destructor is available

    89     // -----------------------------------------------------------------------

    90     /** @name Destructor */

    91     //@{

    92     /**

    93      * Destructor

    94      *

    95      */

    96     virtual ~DOMTreeWalker() {};

    97     //@}

    98 

    99     // -----------------------------------------------------------------------

   100     //  Virtual DOMTreeWalker interface

   101     // -----------------------------------------------------------------------

   102     /** @name Functions introduced in DOM Level 2 */

   103     //@{

   104     // -----------------------------------------------------------------------

   105     //  Getter methods

   106     // -----------------------------------------------------------------------

   107 

   108     /**

   109      * The <code>root</code> node of the <code>DOMTreeWalker</code>, as specified

   110      * when it was created.

   111      *

   112      * @since DOM Level 2

   113      */

   114     virtual DOMNode*          getRoot() = 0;

   115     /**

   116      * This attribute determines which node types are presented via the

   117      * <code>DOMTreeWalker</code>. The available set of constants is defined in

   118      * the <code>DOMNodeFilter</code> interface.  Nodes not accepted by

   119      * <code>whatToShow</code> will be skipped, but their children may still

   120      * be considered. Note that this skip takes precedence over the filter,

   121      * if any.

   122      *

   123      * @since DOM Level 2

   124      */

   125     virtual unsigned long   	getWhatToShow()= 0;

   126 

   127     /**

   128      * Return The filter used to screen nodes.

   129      *

   130      * @since DOM Level 2

   131      */

   132     virtual DOMNodeFilter*	   getFilter()= 0;

   133 

   134     /**

   135      * The value of this flag determines whether the children of entity

   136      * reference nodes are visible to the <code>DOMTreeWalker</code>. If false,

   137      * these children  and their descendants will be rejected. Note that

   138      * this rejection takes precedence over <code>whatToShow</code> and the

   139      * filter, if any.

   140      * <br> To produce a view of the document that has entity references

   141      * expanded and does not expose the entity reference node itself, use

   142      * the <code>whatToShow</code> flags to hide the entity reference node

   143      * and set <code>expandEntityReferences</code> to true when creating the

   144      * <code>DOMTreeWalker</code>. To produce a view of the document that has

   145      * entity reference nodes but no entity expansion, use the

   146      * <code>whatToShow</code> flags to show the entity reference node and

   147      * set <code>expandEntityReferences</code> to false.

   148      *

   149      * @since DOM Level 2

   150      */

   151     virtual bool              getExpandEntityReferences()= 0;

   152 

   153     /**

   154      * Return the node at which the DOMTreeWalker is currently positioned.

   155      *

   156      * @since DOM Level 2

   157      */

   158     virtual DOMNode*          getCurrentNode()= 0;

   159 

   160     // -----------------------------------------------------------------------

   161     //  Query methods

   162     // -----------------------------------------------------------------------

   163     /**

   164      * Moves to and returns the closest visible ancestor node of the current

   165      * node. If the search for <code>parentNode</code> attempts to step

   166      * upward from the <code>DOMTreeWalker</code>'s <code>root</code> node, or

   167      * if it fails to find a visible ancestor node, this method retains the

   168      * current position and returns <code>null</code>.

   169      * @return The new parent node, or <code>null</code> if the current node

   170      *   has no parent  in the <code>DOMTreeWalker</code>'s logical view.

   171      *

   172      * @since DOM Level 2

   173      */

   174     virtual DOMNode*          parentNode()= 0;

   175 

   176     /**

   177      * Moves the <code>DOMTreeWalker</code> to the first visible child of the

   178      * current node, and returns the new node. If the current node has no

   179      * visible children, returns <code>null</code>, and retains the current

   180      * node.

   181      * @return The new node, or <code>null</code> if the current node has no

   182      *   visible children  in the <code>DOMTreeWalker</code>'s logical view.

   183      *

   184      * @since DOM Level 2

   185      */

   186     virtual DOMNode*          firstChild()= 0;

   187 

   188     /**

   189      * Moves the <code>DOMTreeWalker</code> to the last visible child of the

   190      * current node, and returns the new node. If the current node has no

   191      * visible children, returns <code>null</code>, and retains the current

   192      * node.

   193      * @return The new node, or <code>null</code> if the current node has no

   194      *   children  in the <code>DOMTreeWalker</code>'s logical view.

   195      *

   196      * @since DOM Level 2

   197      */

   198     virtual DOMNode*          lastChild()= 0;

   199 

   200     /**

   201      * Moves the <code>DOMTreeWalker</code> to the previous sibling of the

   202      * current node, and returns the new node. If the current node has no

   203      * visible previous sibling, returns <code>null</code>, and retains the

   204      * current node.

   205      * @return The new node, or <code>null</code> if the current node has no

   206      *   previous sibling.  in the <code>DOMTreeWalker</code>'s logical view.

   207      *

   208      * @since DOM Level 2

   209      */

   210     virtual DOMNode*          previousSibling()= 0;

   211 

   212     /**

   213      * Moves the <code>DOMTreeWalker</code> to the next sibling of the current

   214      * node, and returns the new node. If the current node has no visible

   215      * next sibling, returns <code>null</code>, and retains the current node.

   216      * @return The new node, or <code>null</code> if the current node has no

   217      *   next sibling.  in the <code>DOMTreeWalker</code>'s logical view.

   218      *

   219      * @since DOM Level 2

   220      */

   221     virtual DOMNode*          nextSibling()= 0;

   222 

   223     /**

   224      * Moves the <code>DOMTreeWalker</code> to the previous visible node in

   225      * document order relative to the current node, and returns the new

   226      * node. If the current node has no previous node,  or if the search for

   227      * <code>previousNode</code> attempts to step upward from the

   228      * <code>DOMTreeWalker</code>'s <code>root</code> node,  returns

   229      * <code>null</code>, and retains the current node.

   230      * @return The new node, or <code>null</code> if the current node has no

   231      *   previous node  in the <code>DOMTreeWalker</code>'s logical view.

   232      *

   233      * @since DOM Level 2

   234      */

   235     virtual DOMNode*          previousNode()= 0;

   236 

   237     /**

   238      * Moves the <code>DOMTreeWalker</code> to the next visible node in document

   239      * order relative to the current node, and returns the new node. If the

   240      * current node has no next node, or if the search for nextNode attempts

   241      * to step upward from the <code>DOMTreeWalker</code>'s <code>root</code>

   242      * node, returns <code>null</code>, and retains the current node.

   243      * @return The new node, or <code>null</code> if the current node has no

   244      *   next node  in the <code>DOMTreeWalker</code>'s logical view.

   245      *

   246      * @since DOM Level 2

   247      */

   248     virtual DOMNode*          nextNode()= 0;

   249 

   250     // -----------------------------------------------------------------------

   251     //  Setter methods

   252     // -----------------------------------------------------------------------

   253     /**

   254      * The node at which the <code>DOMTreeWalker</code> is currently positioned.

   255      * <br>Alterations to the DOM tree may cause the current node to no longer

   256      * be accepted by the <code>DOMTreeWalker</code>'s associated filter.

   257      * <code>currentNode</code> may also be explicitly set to any node,

   258      * whether or not it is within the subtree specified by the

   259      * <code>root</code> node or would be accepted by the filter and

   260      * <code>whatToShow</code> flags. Further traversal occurs relative to

   261      * <code>currentNode</code> even if it is not part of the current view,

   262      * by applying the filters in the requested direction; if no traversal

   263      * is possible, <code>currentNode</code> is not changed.

   264      * @exception DOMException

   265      *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set

   266      *   <code>currentNode</code> to <code>null</code>.

   267      *

   268      * @since DOM Level 2

   269      */

   270     virtual void              setCurrentNode(DOMNode* currentNode)= 0;

   271     //@}

   272 

   273     // -----------------------------------------------------------------------

   274     //  Non-standard Extension

   275     // -----------------------------------------------------------------------

   276     /** @name Non-standard Extension */

   277     //@{

   278     /**

   279      * Called to indicate that this TreeWalker is no longer in use

   280      * and that the implementation may relinquish any resources associated with it.

   281      *

   282      * Access to a released object will lead to unexpected result.

   283      */

   284     virtual void              release() = 0;

   285     //@}

   286 };

   287 

   288 #define GetDOMTreeWalkerMemoryManager GET_INDIRECT_MM(fCurrentNode)

   289 

   290 XERCES_CPP_NAMESPACE_END

   291 

   292 #endif