001: package javax.xml.stream.events;
002:
003: import java.io.Writer;
004: import javax.xml.namespace.QName;
005:
006: /**
007: * This is the base event interface for handling markup events.
008: * Events are value objects that are used to communicate the
009: * XML 1.0 InfoSet to the Application. Events may be cached
010: * and referenced after the parse has completed.
011: *
012: * @version 1.0
013: * @author Copyright (c) 2003 by BEA Systems. All Rights Reserved.
014: * @see javax.xml.stream.XMLEventReader
015: * @see Characters
016: * @see ProcessingInstruction
017: * @see StartElement
018: * @see EndElement
019: * @see StartDocument
020: * @see EndDocument
021: * @see EntityReference
022: * @see EntityDeclaration
023: * @see NotationDeclaration
024: */
025: public interface XMLEvent extends javax.xml.stream.XMLStreamConstants {
026:
027: /**
028: * Returns an integer code for this event.
029: * @see #START_ELEMENT
030: * @see #END_ELEMENT
031: * @see #CHARACTERS
032: * @see #ATTRIBUTE
033: * @see #NAMESPACE
034: * @see #PROCESSING_INSTRUCTION
035: * @see #COMMENT
036: * @see #START_DOCUMENT
037: * @see #END_DOCUMENT
038: * @see #DTD
039: */
040: public int getEventType();
041:
042: /**
043: * Return the location of this event. The Location
044: * returned from this method is non-volatile and
045: * will retain its information.
046: * @see javax.xml.stream.Location
047: */
048: javax.xml.stream.Location getLocation();
049:
050: /**
051: * A utility function to check if this event is a StartElement.
052: * @see StartElement
053: */
054: public boolean isStartElement();
055:
056: /**
057: * A utility function to check if this event is an Attribute.
058: * @see Attribute
059: */
060: public boolean isAttribute();
061:
062: /**
063: * A utility function to check if this event is a Namespace.
064: * @see Namespace
065: */
066: public boolean isNamespace();
067:
068: /**
069: * A utility function to check if this event is a EndElement.
070: * @see EndElement
071: */
072: public boolean isEndElement();
073:
074: /**
075: * A utility function to check if this event is an EntityReference.
076: * @see EntityReference
077: */
078: public boolean isEntityReference();
079:
080: /**
081: * A utility function to check if this event is a ProcessingInstruction.
082: * @see ProcessingInstruction
083: */
084: public boolean isProcessingInstruction();
085:
086: /**
087: * A utility function to check if this event is Characters.
088: * @see Characters
089: */
090: public boolean isCharacters();
091:
092: /**
093: * A utility function to check if this event is a StartDocument.
094: * @see StartDocument
095: */
096: public boolean isStartDocument();
097:
098: /**
099: * A utility function to check if this event is an EndDocument.
100: * @see EndDocument
101: */
102: public boolean isEndDocument();
103:
104: /**
105: * Returns this event as a start element event, may result in
106: * a class cast exception if this event is not a start element.
107: */
108: public StartElement asStartElement();
109:
110: /**
111: * Returns this event as an end element event, may result in
112: * a class cast exception if this event is not a end element.
113: */
114: public EndElement asEndElement();
115:
116: /**
117: * Returns this event as Characters, may result in
118: * a class cast exception if this event is not Characters.
119: */
120: public Characters asCharacters();
121:
122: /**
123: * This method is provided for implementations to provide
124: * optional type information about the associated event.
125: * It is optional and will return null if no information
126: * is available.
127: */
128: public QName getSchemaType();
129:
130: /**
131: * This method will write the XMLEvent as per the XML 1.0 specification as Unicode characters.
132: * No indentation or whitespace should be outputted.
133: *
134: * Any user defined event type SHALL have this method
135: * called when being written to on an output stream.
136: * Built in Event types MUST implement this method,
137: * but implementations MAY choose not call these methods
138: * for optimizations reasons when writing out built in
139: * Events to an output stream.
140: * The output generated MUST be equivalent in terms of the
141: * infoset expressed.
142: *
143: * @param writer The writer that will output the data
144: * @throws XMLStreamException if there is a fatal error writing the event
145: */
146: public void writeAsEncodedUnicode(Writer writer)
147: throws javax.xml.stream.XMLStreamException;
148:
149: }
|