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
26package javax.xml.stream.events;
27
28import java.io.Writer;
29import 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 */
50public 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}
176