1 /* 2 * Copyright (c) 2009, 2020, 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 java.io.Writer; 29 import javax.xml.namespace.QName; 30 /** 31 * This is the base event interface for handling markup events. 32 * Events are value objects that are used to communicate the 33 * XML 1.0 InfoSet to the Application. Events may be cached 34 * and referenced after the parse has completed. 35 * 36 * @version 1.0 37 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 38 * @see javax.xml.stream.XMLEventReader 39 * @see Characters 40 * @see ProcessingInstruction 41 * @see StartElement 42 * @see EndElement 43 * @see StartDocument 44 * @see EndDocument 45 * @see EntityReference 46 * @see EntityDeclaration 47 * @see NotationDeclaration 48 * @since 1.6 49 */ 50 public interface XMLEvent extends javax.xml.stream.XMLStreamConstants { 51 52 /** 53 * Returns an integer code for this event. 54 * @return the event type 55 * @see #START_ELEMENT 56 * @see #END_ELEMENT 57 * @see #CHARACTERS 58 * @see #ATTRIBUTE 59 * @see #NAMESPACE 60 * @see #PROCESSING_INSTRUCTION 61 * @see #COMMENT 62 * @see #START_DOCUMENT 63 * @see #END_DOCUMENT 64 * @see #DTD 65 */ getEventType()66 public int getEventType(); 67 68 /** 69 * Return the location of this event. The Location 70 * returned from this method is non-volatile and 71 * will retain its information. 72 * @return the location of the event 73 * @see javax.xml.stream.Location 74 */ getLocation()75 javax.xml.stream.Location getLocation(); 76 77 /** 78 * A utility function to check if this event is a StartElement. 79 * @return true if the event is {@code StartElement}, false otherwise 80 * @see StartElement 81 */ isStartElement()82 public boolean isStartElement(); 83 84 /** 85 * A utility function to check if this event is an Attribute. 86 * @return true if the event is {@code Attribute}, false otherwise 87 * @see Attribute 88 */ isAttribute()89 public boolean isAttribute(); 90 91 /** 92 * A utility function to check if this event is a Namespace. 93 * @return true if the event is {@code Namespace}, false otherwise 94 * @see Namespace 95 */ isNamespace()96 public boolean isNamespace(); 97 98 99 /** 100 * A utility function to check if this event is a EndElement. 101 * @return true if the event is {@code EndElement}, false otherwise 102 * @see EndElement 103 */ isEndElement()104 public boolean isEndElement(); 105 106 /** 107 * A utility function to check if this event is an EntityReference. 108 * @return true if the event is {@code EntityReference}, false otherwise 109 * @see EntityReference 110 */ isEntityReference()111 public boolean isEntityReference(); 112 113 /** 114 * A utility function to check if this event is a ProcessingInstruction. 115 * @return true if the event is {@code ProcessingInstruction}, false otherwise 116 * @see ProcessingInstruction 117 */ isProcessingInstruction()118 public boolean isProcessingInstruction(); 119 120 /** 121 * A utility function to check if this event is Characters. 122 * @return true if the event is {@code Characters}, false otherwise 123 * @see Characters 124 */ isCharacters()125 public boolean isCharacters(); 126 127 /** 128 * A utility function to check if this event is a StartDocument. 129 * @return true if the event is {@code StartDocument}, false otherwise 130 * @see StartDocument 131 */ isStartDocument()132 public boolean isStartDocument(); 133 134 /** 135 * A utility function to check if this event is an EndDocument. 136 * @return true if the event is {@code EndDocument}, false otherwise 137 * @see EndDocument 138 */ isEndDocument()139 public boolean isEndDocument(); 140 141 /** 142 * Returns this event as a start element event, may result in 143 * a class cast exception if this event is not a start element. 144 * @return a {@code StartElement} event 145 */ asStartElement()146 public StartElement asStartElement(); 147 148 /** 149 * Returns this event as an end element event, may result in 150 * a class cast exception if this event is not a end element. 151 * @return a {@code EndElement} event 152 */ asEndElement()153 public EndElement asEndElement(); 154 155 /** 156 * Returns this event as Characters, may result in 157 * a class cast exception if this event is not Characters. 158 * @return a {@code Characters} event 159 */ asCharacters()160 public Characters asCharacters(); 161 162 /** 163 * This method is provided for implementations to provide 164 * optional type information about the associated event. 165 * It is optional and will return null if no information 166 * is available. 167 * @return the type of the event, null if not available 168 */ getSchemaType()169 public QName getSchemaType(); 170 171 /** 172 * This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters. 173 * No indentation or whitespace should be outputted. 174 * 175 * Any user defined event type SHALL have this method 176 * called when being written to on an output stream. 177 * Built in Event types MUST implement this method, 178 * but implementations MAY choose not call these methods 179 * for optimizations reasons when writing out built in 180 * Events to an output stream. 181 * The output generated MUST be equivalent in terms of the 182 * infoset expressed. 183 * 184 * @param writer The writer that will output the data 185 * @throws javax.xml.stream.XMLStreamException if there is a fatal error writing the event 186 */ writeAsEncodedUnicode(Writer writer)187 public void writeAsEncodedUnicode(Writer writer) 188 throws javax.xml.stream.XMLStreamException; 189 190 } 191