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 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 * @see #START_ELEMENT 55 * @see #END_ELEMENT 56 * @see #CHARACTERS 57 * @see #ATTRIBUTE 58 * @see #NAMESPACE 59 * @see #PROCESSING_INSTRUCTION 60 * @see #COMMENT 61 * @see #START_DOCUMENT 62 * @see #END_DOCUMENT 63 * @see #DTD 64 */ getEventType()65 public int getEventType(); 66 67 /** 68 * Return the location of this event. The Location 69 * returned from this method is non-volatile and 70 * will retain its information. 71 * @see javax.xml.stream.Location 72 */ getLocation()73 javax.xml.stream.Location getLocation(); 74 75 /** 76 * A utility function to check if this event is a StartElement. 77 * @see StartElement 78 */ isStartElement()79 public boolean isStartElement(); 80 81 /** 82 * A utility function to check if this event is an Attribute. 83 * @see Attribute 84 */ isAttribute()85 public boolean isAttribute(); 86 87 /** 88 * A utility function to check if this event is a Namespace. 89 * @see Namespace 90 */ isNamespace()91 public boolean isNamespace(); 92 93 94 /** 95 * A utility function to check if this event is a EndElement. 96 * @see EndElement 97 */ isEndElement()98 public boolean isEndElement(); 99 100 /** 101 * A utility function to check if this event is an EntityReference. 102 * @see EntityReference 103 */ isEntityReference()104 public boolean isEntityReference(); 105 106 /** 107 * A utility function to check if this event is a ProcessingInstruction. 108 * @see ProcessingInstruction 109 */ isProcessingInstruction()110 public boolean isProcessingInstruction(); 111 112 /** 113 * A utility function to check if this event is Characters. 114 * @see Characters 115 */ isCharacters()116 public boolean isCharacters(); 117 118 /** 119 * A utility function to check if this event is a StartDocument. 120 * @see StartDocument 121 */ isStartDocument()122 public boolean isStartDocument(); 123 124 /** 125 * A utility function to check if this event is an EndDocument. 126 * @see EndDocument 127 */ isEndDocument()128 public boolean isEndDocument(); 129 130 /** 131 * Returns this event as a start element event, may result in 132 * a class cast exception if this event is not a start element. 133 */ asStartElement()134 public StartElement asStartElement(); 135 136 /** 137 * Returns this event as an end element event, may result in 138 * a class cast exception if this event is not a end element. 139 */ asEndElement()140 public EndElement asEndElement(); 141 142 /** 143 * Returns this event as Characters, may result in 144 * a class cast exception if this event is not Characters. 145 */ asCharacters()146 public Characters asCharacters(); 147 148 /** 149 * This method is provided for implementations to provide 150 * optional type information about the associated event. 151 * It is optional and will return null if no information 152 * is available. 153 */ getSchemaType()154 public QName getSchemaType(); 155 156 /** 157 * This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters. 158 * No indentation or whitespace should be outputted. 159 * 160 * Any user defined event type SHALL have this method 161 * called when being written to on an output stream. 162 * Built in Event types MUST implement this method, 163 * but implementations MAY choose not call these methods 164 * for optimizations reasons when writing out built in 165 * Events to an output stream. 166 * The output generated MUST be equivalent in terms of the 167 * infoset expressed. 168 * 169 * @param writer The writer that will output the data 170 * @throws javax.xml.stream.XMLStreamException if there is a fatal error writing the event 171 */ writeAsEncodedUnicode(Writer writer)172 public void writeAsEncodedUnicode(Writer writer) 173 throws javax.xml.stream.XMLStreamException; 174 175 } 176