1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 *
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
27 */
28
29 package javax.xml.stream.events;
30
31 import java.io.Writer;
32 import javax.xml.namespace.QName;
33 /**
34 * This is the base event interface for handling markup events.
35 * Events are value objects that are used to communicate the
36 * XML 1.0 InfoSet to the Application. Events may be cached
37 * and referenced after the parse has completed.
38 *
39 * @version 1.0
40 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
41 * @see javax.xml.stream.XMLEventReader
42 * @see Characters
43 * @see ProcessingInstruction
44 * @see StartElement
45 * @see EndElement
46 * @see StartDocument
47 * @see EndDocument
48 * @see EntityReference
49 * @see EntityDeclaration
50 * @see NotationDeclaration
51 * @since 1.6
52 */
53 public interface XMLEvent extends javax.xml.stream.XMLStreamConstants {
54
55 /**
56 * Returns an integer code for this event.
57 * @see #START_ELEMENT
58 * @see #END_ELEMENT
59 * @see #CHARACTERS
60 * @see #ATTRIBUTE
61 * @see #NAMESPACE
62 * @see #PROCESSING_INSTRUCTION
63 * @see #COMMENT
64 * @see #START_DOCUMENT
65 * @see #END_DOCUMENT
66 * @see #DTD
67 */
68 public int getEventType();
69
70 /**
71 * Return the location of this event. The Location
72 * returned from this method is non-volatile and
73 * will retain its information.
74 * @see javax.xml.stream.Location
75 */
76 javax.xml.stream.Location getLocation();
77
78 /**
79 * A utility function to check if this event is a StartElement.
80 * @see StartElement
81 */
82 public boolean isStartElement();
83
84 /**
85 * A utility function to check if this event is an Attribute.
86 * @see Attribute
87 */
88 public boolean isAttribute();
89
90 /**
91 * A utility function to check if this event is a Namespace.
92 * @see Namespace
93 */
94 public boolean isNamespace();
95
96
97 /**
98 * A utility function to check if this event is a EndElement.
99 * @see EndElement
100 */
101 public boolean isEndElement();
102
103 /**
104 * A utility function to check if this event is an EntityReference.
105 * @see EntityReference
106 */
107 public boolean isEntityReference();
108
109 /**
110 * A utility function to check if this event is a ProcessingInstruction.
111 * @see ProcessingInstruction
112 */
113 public boolean isProcessingInstruction();
114
115 /**
116 * A utility function to check if this event is Characters.
117 * @see Characters
118 */
119 public boolean isCharacters();
120
121 /**
122 * A utility function to check if this event is a StartDocument.
123 * @see StartDocument
124 */
125 public boolean isStartDocument();
126
127 /**
128 * A utility function to check if this event is an EndDocument.
129 * @see EndDocument
130 */
131 public boolean isEndDocument();
132
133 /**
134 * Returns this event as a start element event, may result in
135 * a class cast exception if this event is not a start element.
136 */
137 public StartElement asStartElement();
138
139 /**
140 * Returns this event as an end element event, may result in
141 * a class cast exception if this event is not a end element.
142 */
143 public EndElement asEndElement();
144
145 /**
146 * Returns this event as Characters, may result in
147 * a class cast exception if this event is not Characters.
148 */
149 public Characters asCharacters();
150
151 /**
152 * This method is provided for implementations to provide
153 * optional type information about the associated event.
154 * It is optional and will return null if no information
155 * is available.
156 */
157 public QName getSchemaType();
158
159 /**
160 * This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters.
161 * No indentation or whitespace should be outputted.
162 *
163 * Any user defined event type SHALL have this method
164 * called when being written to on an output stream.
165 * Built in Event types MUST implement this method,
166 * but implementations MAY choose not call these methods
167 * for optimizations reasons when writing out built in
168 * Events to an output stream.
169 * The output generated MUST be equivalent in terms of the
170 * infoset expressed.
171 *
172 * @param writer The writer that will output the data
173 * @throws javax.xml.stream.XMLStreamException if there is a fatal error writing the event
174 */
175 public void writeAsEncodedUnicode(Writer writer)
176 throws javax.xml.stream.XMLStreamException;
177
178 }