View Javadoc
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 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 }