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 */
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 */
73 javax.xml.stream.Location getLocation();
74
75 /**
76 * A utility function to check if this event is a StartElement.
77 * @see StartElement
78 */
79 public boolean isStartElement();
80
81 /**
82 * A utility function to check if this event is an Attribute.
83 * @see Attribute
84 */
85 public boolean isAttribute();
86
87 /**
88 * A utility function to check if this event is a Namespace.
89 * @see Namespace
90 */
91 public boolean isNamespace();
92
93
94 /**
95 * A utility function to check if this event is a EndElement.
96 * @see EndElement
97 */
98 public boolean isEndElement();
99
100 /**
101 * A utility function to check if this event is an EntityReference.
102 * @see EntityReference
103 */
104 public boolean isEntityReference();
105
106 /**
107 * A utility function to check if this event is a ProcessingInstruction.
108 * @see ProcessingInstruction
109 */
110 public boolean isProcessingInstruction();
111
112 /**
113 * A utility function to check if this event is Characters.
114 * @see Characters
115 */
116 public boolean isCharacters();
117
118 /**
119 * A utility function to check if this event is a StartDocument.
120 * @see StartDocument
121 */
122 public boolean isStartDocument();
123
124 /**
125 * A utility function to check if this event is an EndDocument.
126 * @see EndDocument
127 */
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 */
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 */
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 */
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 */
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 */
172 public void writeAsEncodedUnicode(Writer writer)
173 throws javax.xml.stream.XMLStreamException;
174
175 }