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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
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 */
187 public void writeAsEncodedUnicode(Writer writer)
188 throws javax.xml.stream.XMLStreamException;
189
190 }