1 /*
   2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   3  *
   4  * This code is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 only, as
   6  * published by the Free Software Foundation.  Oracle designates this
   7  * particular file as subject to the "Classpath" exception as provided
   8  * by Oracle in the LICENSE file that accompanied this code.
   9  *
  10  * This code is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * version 2 for more details (a copy is included in the LICENSE file that
  14  * accompanied this code).
  15  *
  16  * You should have received a copy of the GNU General Public License version
  17  * 2 along with this work; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 /*
  25  * Copyright (c) 2015 World Wide Web Consortium,
  26  *
  27  * (Massachusetts Institute of Technology, European Research Consortium for
  28  * Informatics and Mathematics, Keio University, Beihang). All Rights Reserved.
  29  * This work is distributed under the W3C(r) Software License [1] in the hope that
  30  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
  31  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  32  *
  33  * [1] http://www.w3.org/Consortium/Legal/copyright-software
  34  */
  35 
  36 package org.w3c.dom;
  37 
  38 /**
  39  * The {@code ElementTraversal} interface is a set of read-only attributes
  40  * which allow an author to easily navigate between elements in a document.
  41  * <p>
  42  * In conforming implementations of Element Traversal, all objects that
  43  * implement {@link Element} must also implement the {@code ElementTraversal}
  44  * interface. Four of the methods,
  45  * {@link #getFirstElementChild}, {@link #getLastElementChild},
  46  * {@link #getPreviousElementSibling}, and {@link #getNextElementSibling},
  47  * each provides a live reference to another element with the defined
  48  * relationship to the current element, if the related element exists. The
  49  * fifth method, {@link #getChildElementCount}, exposes the number of child
  50  * elements of an element, for preprocessing before navigation.
  51  *
  52  * @see
  53  * <a href='http://www.w3.org/TR/ElementTraversal/'><cite>Element Traversal Specification</cite></a>
  54  *
  55  * @since 9
  56  */
  57 public interface ElementTraversal {
  58 
  59     /**
  60      * Returns a reference to the first child node of the element which is of
  61      * the {@link Element} type.
  62      *
  63      * @return a reference to an element child, {@code null} if the element has
  64      * no child of the {@link Element} type.
  65      */
  66     Element getFirstElementChild();
  67 
  68     /**
  69      * Returns a reference to the last child node of the element which is of
  70      * the {@link Element} type.
  71      *
  72      * @return a reference to an element child, {@code null} if the element has
  73      * no child of the {@link Element} type.
  74      */
  75     Element getLastElementChild();
  76 
  77     /**
  78      * Returns a reference to the sibling node of the element which most immediately
  79      * precedes the element in document order, and which is of the {@link Element} type.
  80      *
  81      * @return a reference to an element child, {@code null} if the element has
  82      * no sibling node of the {@link Element} type that comes before this one.
  83      */
  84     Element getPreviousElementSibling();
  85 
  86     /**
  87      * Returns a reference to the sibling node of the element which most immediately
  88      * follows the element in document order, and which is of the {@link Element} type.
  89      *
  90      * @return a reference to an element child, {@code null} if the element has
  91      * no sibling node of the {@link Element} type that comes after this one.
  92      */
  93     Element getNextElementSibling();
  94 
  95     /**
  96      * Returns the current number of child nodes of the element which are of
  97      * the {@link Element} type.
  98      *
  99      * @return the number of element children, or {@code 0} if the element has
 100      * no element children.
 101      */
 102     int getChildElementCount();
 103 }