1 /*
   2  * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.xml.stream.events;
  27 
  28 import javax.xml.namespace.QName;
  29 import javax.xml.namespace.NamespaceContext;
  30 import java.util.Iterator;
  31 
  32 /**
  33  * The StartElement interface provides access to information about
  34  * start elements.  A StartElement is reported for each Start Tag
  35  * in the document.
  36  *
  37  * @version 1.0
  38  * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
  39  * @since 1.6
  40  */
  41 public interface StartElement extends XMLEvent {
  42 
  43   /**
  44    * Get the name of this event
  45    * @return the qualified name of this event
  46    */
  47   public QName getName();
  48 
  49   /**
  50    * Returns an Iterator of non-namespace declared attributes declared on
  51    * this START_ELEMENT,
  52    * returns an empty iterator if there are no attributes.  The
  53    * iterator must contain only implementations of the javax.xml.stream.Attribute
  54    * interface.   Attributes are fundamentally unordered and may not be reported
  55    * in any order.
  56    *
  57    * @return a readonly Iterator over Attribute interfaces, or an
  58    * empty iterator
  59    */
  60   public Iterator<Attribute> getAttributes();
  61 
  62   /**
  63    * Returns an Iterator of namespaces declared on this element.
  64    * This Iterator does not contain previously declared namespaces
  65    * unless they appear on the current START_ELEMENT.
  66    * Therefore this list may contain redeclared namespaces and duplicate namespace
  67    * declarations. Use the getNamespaceContext() method to get the
  68    * current context of namespace declarations.
  69    *
  70    * <p>The iterator must contain only implementations of the
  71    * javax.xml.stream.Namespace interface.
  72    *
  73    * <p>A Namespace isA Attribute.  One
  74    * can iterate over a list of namespaces as a list of attributes.
  75    * However this method returns only the list of namespaces
  76    * declared on this START_ELEMENT and does not
  77    * include the attributes declared on this START_ELEMENT.
  78    *
  79    * Returns an empty iterator if there are no namespaces.
  80    *
  81    * @return a readonly Iterator over Namespace interfaces, or an
  82    * empty iterator
  83    *
  84    */
  85   public Iterator<Namespace> getNamespaces();
  86 
  87   /**
  88    * Returns the attribute referred to by this name
  89    * @param name the qname of the desired name
  90    * @return the attribute corresponding to the name value or null
  91    */
  92   public Attribute getAttributeByName(QName name);
  93 
  94   /**
  95    * Gets a read-only namespace context. If no context is
  96    * available this method will return an empty namespace context.
  97    * The NamespaceContext contains information about all namespaces
  98    * in scope for this StartElement.
  99    *
 100    * @return the current namespace context
 101    */
 102   public NamespaceContext getNamespaceContext();
 103 
 104   /**
 105    * Gets the value that the prefix is bound to in the
 106    * context of this element.  Returns null if
 107    * the prefix is not bound in this context
 108    * @param prefix the prefix to lookup
 109    * @return the uri bound to the prefix or null
 110    */
 111   public String getNamespaceURI(String prefix);
 112 }