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 }