Java Doc for XmlParser.java in  » Swing-Library » jEdit » com » microstar » xml » Java Source Code / Java DocumentationJava Source Code and Java Documentation

You need to define a class implementing the XmlHandler interface: an object belonging to this class will receive the callbacks for the events. (As an alternative to implementing the full XmlHandler interface, you can simply extend the HandlerBase convenience class.)

Usage (assuming that MyHandler is your implementation of the XmlHandler interface):

 XmlHandler handler = new MyHandler();
 XmlParser parser = new XmlParser();
 parser.setHandler(handler);
 try {
 parser.parse("http://www.host.com/doc.xml", null);
 } catch (Exception e) {
 [do something interesting]
 }
 

Alternatively, you can use the standard SAX interfaces with the SAXDriver class as your entry point.
author:
   Copyright (c) 1997, 1998 by Microstar Software Ltd.
author:
   Written by David Megginson <dmeggins@microstar.com>
version:
   1.1
See Also:   XmlHandler
See Also:   HandlerBase
See Also:   SAXDriver

The trick here (as suggested in the XML standard) is that any entity not in UTF-8, or in UCS-2 with a byte-order mark, must begin with an XML declaration or an encoding declaration; we simply have to look for "<?XML" in various encodings.

This method has no way to distinguish among 8-bit encodings. Instead, it assumes UTF-8, then (possibly) revises its assumption later in checkEncoding().

All general entities will be expanded.
Parameters:
  name - The name of the associated element.
Parameters:
  aname - The name of the attribute.

The result will always be null unless the content type is CONTENT_ELEMENTS or CONTENT_MIXED.
Parameters:
  name - The element type name.

Ælfred uses this method to create an internalised version of all names and attribute values, so that it can test equality with == instead of String.equals().

If you want to be able to test for equality in the same way, you can use this method to internalise your own strings first:

 String PARA = handler.intern("PARA");
 

Note that this will not return the same results as String.intern().
Parameters:
  s - The string to internalise.

This is much more efficient than constructing a non-internalised string first, and then internalising it.

Note that this will not return the same results as String.intern().
Parameters:
  ch - an array of characters for building the string.
Parameters:
  start - the starting position in the array.
Parameters:
  length - the number of characters to place in the string.

 [1] S ::= (#x20 | #x9 | #xd | #xa)+
 

 [1] document ::= prolog element Misc*
 

This is the top-level parsing function for a single XML document.

 [24] prolog ::= XMLDecl? Misc* (Doctypedecl Misc*)?
 

There are a couple of tricks here.

This method is useful for expanding an internal entity, or for unreading a string of characters.

This method saves all of the global variables associated with the current input source, so that they can be restored when a new input source has finished.

Note that the character will be removed from the input stream on success, but will be put back on failure.

This is simply a convenience method.

Note that the string will be removed from the input stream on success, but will be put back on failure.

Compare what the author has specified in the XML declaration or encoding PI with what we have detected.

This is also important for distinguishing among the various 7- and 8-bit encodings, such as ISO-LATIN-1 (I cannot autodetect those).
Parameters:
  encodingName - The name of the encoding specified by the user.
See Also:   XmlParser.parseXMLDecl
See Also:   XmlParser.parseTextDecl

When readDataChunk() calls this method, the raw bytes are in rawReadBuffer, and the final characters will appear in readBuffer.

This is a direct conversion, with no tricks.
Parameters:
  count - The number of bytes to convert.
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.rawReadBuffer
See Also:   XmlParser.readBuffer

When readDataChunk() calls this method, the raw bytes are in rawReadBuffer, and the final characters will appear in readBuffer.
Parameters:
  count - The number of bytes to convert.
Parameters:
  shift1 - The number of bits to shift byte 1.
Parameters:
  shift2 - The number of bits to shift byte 2
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.rawReadBuffer
See Also:   XmlParser.readBuffer

When readDataChunk() calls this method, the raw bytes are in rawReadBuffer, and the final characters will appear in readBuffer.

Java has 16-bit chars, but this routine will attempt to use surrogates to encoding values between 0x00010000 and 0x000fffff.
Parameters:
  count - The number of bytes to convert.
Parameters:
  shift1 - The number of bits to shift byte 1.
Parameters:
  shift2 - The number of bits to shift byte 2
Parameters:
  shift3 - The number of bits to shift byte 2
Parameters:
  shift4 - The number of bits to shift byte 2
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.rawReadBuffer
See Also:   XmlParser.readBuffer

When readDataChunk() calls this method, the raw bytes are in rawReadBuffer, and the final characters will appear in readBuffer.

The tricky part of this is dealing with UTF-8 multi-byte sequences, but it doesn't seem to slow things down too much.
Parameters:
  count - The number of bytes to convert.
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.rawReadBuffer
See Also:   XmlParser.readBuffer
See Also:   XmlParser.getNextUtf8Byte

The results will be valid only after the DTD (if any) has been parsed. An enumeration of all element types declared for thisdocument (as Strings).
See Also:   XmlParser.getElementContentType
See Also:   XmlParser.getElementContentModel

The trick here (as suggested in the XML standard) is that any entity not in UTF-8, or in UCS-2 with a byte-order mark, must begin with an XML declaration or an encoding declaration; we simply have to look for "<?XML" in various encodings.

This method has no way to distinguish among 8-bit encodings. Instead, it assumes UTF-8, then (possibly) revises its assumption later in checkEncoding(). Any ASCII-derived 8-bit encoding should work, but most will be rejected later by checkEncoding().

I don't currently detect EBCDIC, since I'm concerned that it could also be a valid UTF-8 sequence; I'll have to do more checking later.
See Also:   XmlParser.tryEncoding(byte[],byte,byte,byte,byte)
See Also:   XmlParser.tryEncoding(byte[],byte,byte)
See Also:   XmlParser.checkEncoding
See Also:   XmlParser.read8bitEncodingDeclaration

CRLF becomes LF; CR becomes LF.
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.readBuffer
See Also:   XmlParser.readBufferOverflow

All general entities will be expanded.
Parameters:
  name - The name of the associated element.
Parameters:
  aname - The name of the attribute. The expanded default value, or null if the attribute was#IMPLIED or simply undeclared
See Also:   XmlParser.getAttributeDefaultValue

The result will always be null unless the content type is CONTENT_ELEMENTS or CONTENT_MIXED.
Parameters:
  name - The element type name. The normalised content model, as a string.
See Also:   XmlParser.getElementContentType

Ælfred uses this method to create an internalised version of all names and attribute values, so that it can test equality with == instead of String.equals().

If you want to be able to test for equality in the same way, you can use this method to internalise your own strings first:

 String PARA = handler.intern("PARA");
 

Note that this will not return the same results as String.intern().
Parameters:
  s - The string to internalise. An internalised version of the string.
See Also:   XmlParser.intern(char[],int,int)
See Also:   java.lang.String.intern

This is much more efficient than constructing a non-internalised string first, and then internalising it.

Note that this will not return the same results as String.intern().
Parameters:
  ch - an array of characters for building the string.
Parameters:
  start - the starting position in the array.
Parameters:
  length - the number of characters to place in the string. an internalised string.
See Also:   XmlParser.intern(String)
See Also:   java.lang.String.intern

 [1] S ::= (#x20 | #x9 | #xd | #xa)+
 

You may parse a document more than once, but only one thread may call this method for an object at one time.
Parameters:
  systemId - The URI of the document.
Parameters:
  publicId - The public identifier of the document, or null.
Parameters:
  encoding - The suggested encoding, or null if unknown.
exception:
  java.lang.Exception - Any exception thrown by yourown handlers, or any derivation of java.io.IOExceptionthrown by the parser itself.

The URI that you supply will become the base URI for resolving relative links, but Ælfred will actually read the document from the supplied input stream.

You may parse a document more than once, but only one thread may call this method for an object at one time.
Parameters:
  systemId - The base URI of the document, or null if notknown.
Parameters:
  publicId - The public identifier of the document, or nullif not known.
Parameters:
  stream - A byte input stream.
Parameters:
  encoding - The suggested encoding, or null if unknown.
exception:
  java.lang.Exception - Any exception thrown by yourown handlers, or any derivation of java.io.IOExceptionthrown by the parser itself.

The URI that you supply will become the base URI for resolving relative links, but Ælfred will actually read the document from the supplied input stream.

You may parse a document more than once, but only one thread may call this method for an object at one time.
Parameters:
  systemId - The base URI of the document, or null if notknown.
Parameters:
  publicId - The public identifier of the document, or nullif not known.
Parameters:
  reader - A character stream.
exception:
  java.lang.Exception - Any exception thrown by yourown handlers, or any derivation of java.io.IOExceptionthrown by the parser itself.

 [34] Attribute ::= Name Eq AttValue
 

 [20] CDSect ::= CDStart CData CDEnd
 [21] CDStart ::= '<![CDATA['
 [22] CData ::= (Char* - (Char* ']]>' Char*))
 [23] CDEnd ::= ']]>'
 

(The '<![CDATA[' has already been read.)

Note that this just appends characters to the dataBuffer, without actually generating an event.

 [18] Comment ::= '<!--' ((Char - '-') | ('-' (Char - '-')))* "-->"
 

(The <!-- has already been read.)

 [28] doctypedecl ::= '<!DOCTYPE' S Name (S ExternalID)? S?
 ('[' %markupdecl* ']' S?)? '>'
 

(The <!DOCTYPE has already been read.)

 [1] document ::= prolog element Misc*
 

This is the top-level parsing function for a single XML document. As a minimum, a well-formed document must have a document element, and a valid document must have a prolog as well.

 [33] STag ::= '<' Name (S Attribute)* S? '>' [WFC: unique Att spec]
 [38] element ::= EmptyElement | STag content ETag
 [39] EmptyElement ::= '<' Name (S Attribute)* S? '/>'
 [WFC: unique Att spec]
 

(The '<' has already been read.)

NOTE: this method actually chains onto parseContent(), if necessary, and parseContent() will take care of calling parseETag().

 [29] markupdecl ::= ( %elementdecl | %AttlistDecl | %EntityDecl |
 %NotationDecl | %PI | %S | %Comment |
 InternalPERef )
 [30] InternalPERef ::= PEReference
 [31] extSubset ::= (%markupdecl | %conditionalSect)*
 

 [27] Misc ::= Comment | PI | S
 

 [16] PCData ::= [^<&]*
 

The trick here is that the data stays in the dataBuffer without necessarily being converted to a string right away.

 [19] PI ::= '<?' Name (S (Char* - (Char* '?>' Char*)))? '?>'
 

(The <? has already been read.)

An XML processing instruction must begin with a Name, which is the instruction's target.

 [24] prolog ::= XMLDecl? Misc* (Doctypedecl Misc*)?
 

There are a couple of tricks here. First, it is necessary to declare the XML default attributes after the DTD (if present) has been read. Second, it is not possible to expand general references in attribute value literals until after the entire DTD (if present) has been parsed.

We do not look for the XML declaration here, because it is handled by pushURL().
See Also:   pushURL

 [78] EncodingDecl ::= S 'encoding' Eq QEncoding
 [79] EncodingPI ::= '<?xml' S 'encoding' Eq QEncoding S? '?>'
 [80] QEncoding ::= '"' Encoding '"' | "'" Encoding "'"
 [81] Encoding ::= LatinName
 [82] LatinName ::= [A-Za-z] ([A-Za-z0-9._] | '-')*
 

(The <?xml' and whitespace have already been read.)
See Also:   XmlParser.parseXMLDecl
See Also:   XmlParser.checkEncoding

This is especially useful for scanning marked sections.

This is a a little inefficient right now, since it calls tryRead() for every character.
Parameters:
  delim - The string delimiter
See Also:   XmlParser.tryRead(String,boolean)
See Also:   XmlParser.readCh

 [25] XMLDecl ::= '<?xml' VersionInfo EncodingDecl? SDDecl? S? '?>'
 [26] VersionInfo ::= S 'version' Eq ('"1.0"' | "'1.0'")
 [33] SDDecl ::= S 'standalone' Eq "'" ('yes' | 'no') "'"
 | S 'standalone' Eq '"' ("yes" | "no") '"'
 [78] EncodingDecl ::= S 'encoding' Eq QEncoding
 

([80] to [82] are also significant.)

(The <?xml and whitespace have already been read.)

TODO: validate value of standalone.
See Also:   XmlParser.parseTextDecl
See Also:   XmlParser.checkEncoding

This method restores all of the global variables associated with the current input source.
exception:
  java.io.EOFException - If there are no more entries on the input stack.
See Also:   XmlParser.pushInput
See Also:   XmlParser.sourceType
See Also:   XmlParser.externalEntity
See Also:   XmlParser.readBuffer
See Also:   XmlParser.readBufferPos
See Also:   XmlParser.readBufferLength
See Also:   XmlParser.line
See Also:   XmlParser.encoding

This method is useful for expanding an internal entity, or for unreading a string of characters. It creates a new readBuffer containing the characters in the array, instead of characters converted from an input byte stream.

I've added a couple of optimisations: don't push zero- length strings, and just push back a single character for 1-character strings; this should save some time and memory.
Parameters:
  ch - The char array to push.
See Also:   XmlParser.pushString
See Also:   XmlParser.pushURL
See Also:   XmlParser.readBuffer
See Also:   XmlParser.sourceType
See Also:   XmlParser.pushInput

This method saves all of the global variables associated with the current input source, so that they can be restored when a new input source has finished. It also tests for entity recursion.

The method saves the following global variables onto a stack using a fixed-length array:

1. sourceType
2. externalEntity
3. readBuffer
4. readBufferPos
5. readBufferLength
6. line
7. encoding

It is useful either as the expansion of an internal entity, or for backtracking during the parse.

Call pushCharArray() to do the actual work.
Parameters:
  s - The string to push back onto input.
See Also:   XmlParser.pushCharArray

The source will be either an external text entity, or the DTD external subset.

TO DO: Right now, this method always attempts to autodetect the encoding; in the future, it should allow the caller to request an encoding explicitly, and it should also look at the headers with an HTTP connection.
Parameters:
  url - The java.net.URL object for the entity.
See Also:   XmlHandler.resolveEntity
See Also:   XmlParser.pushString
See Also:   XmlParser.sourceType
See Also:   XmlParser.pushInput
See Also:   XmlParser.detectEncoding
See Also:   XmlParser.sourceType
See Also:   XmlParser.readBuffer

The readDataChunk() method maintains the buffer.

If we hit the end of an entity, try to pop the stack and keep going.

(This approach doesn't really enforce XML's rules about entity boundaries, but this is not currently a validating parser).

This routine also attempts to keep track of the current position in external entities, but it's not entirely accurate. The next available input character.
See Also:   XmlParser.unread(char)
See Also:   XmlParser.unread(String)
See Also:   XmlParser.readDataChunk
See Also:   XmlParser.readBuffer
See Also:   XmlParser.line The next character from the current input source.

This is simply a front-end that fills the rawReadBuffer with bytes, then calls the appropriate encoding handler.
See Also:   XmlParser.encoding
See Also:   XmlParser.rawReadBuffer
See Also:   XmlParser.readBuffer
See Also:   XmlParser.filterCR
See Also:   XmlParser.copyUtf8ReadBuffer
See Also:   XmlParser.copyIso8859_1ReadBuffer
See Also:   XmlParser.copyUcs_2ReadBuffer
See Also:   XmlParser.copyUcs_4ReadBuffer

The system identifier is not required for notations.
Parameters:
  inNotation - Are we in a notation? A two-member String array containing the identifiers.

This is especially useful for scanning comments.

This is a a little inefficient right now, since it calls tryRead() for every character.
Parameters:
  delim - The string delimiter
See Also:   XmlParser.tryRead(String,boolean)
See Also:   XmlParser.readCh

Utility routine for detectEncoding().

Always looks for some part of "Parameters:
  sig - The first four bytes read.
Parameters:
  b1 - The first byte of the signature
Parameters:
  b2 - The second byte of the signature
Parameters:
  b3 - The third byte of the signature
Parameters:
  b4 - The fourth byte of the signature
See Also:   XmlParser.detectEncoding

Looks for a UCS-2 byte-order mark.

Utility routine for detectEncoding().
Parameters:
  sig - The first four bytes read.
Parameters:
  b1 - The first byte of the signature
Parameters:
  b2 - The second byte of the signature
See Also:   XmlParser.detectEncoding

Note that the character will be removed from the input stream on success, but will be put back on failure. Do not attempt to read the character again if the method succeeds.
Parameters:
  delim - The character that should appear next. For ainsensitive match, you must supply this in upper-case. true if the character was successfully read, or false ifit was not.
See Also:   XmlParser.tryRead(String)

This is simply a convenience method.

Note that the string will be removed from the input stream on success, but will be put back on failure. Do not attempt to read the string again if the method succeeds.

This method will push back a character rather than an array whenever possible (probably the majority of cases).

NOTE: This method currently has a hard-coded limit of 100 characters for the delimiter.
Parameters:
  delim - The string that should appear next. true if the string was successfully read, or false ifit was not.
See Also:   XmlParser.tryRead(char)

This is simply a convenience method.

This method will push back a character rather than an array whenever possible (probably the majority of cases). true if whitespace was found.

This method usually pushes the character back onto the readBuffer, while the unread(String) method treats the string as a new internal entity.

I don't think that this would ever be called with readBufferPos = 0, because the methods always reads a character before unreading it, but just in case, I've added a boundary condition.
Parameters:
  c - The character to push back.
See Also:   XmlParser.readCh
See Also:   XmlParser.unread(String)
See Also:   XmlParser.unread(char[])
See Also:   XmlParser.readBuffer

NOTE: you must never push back characters that you haven't actually read: use pushString() instead.
See Also:   XmlParser.readCh
See Also:   XmlParser.unread(char)
See Also:   XmlParser.unread(String)
See Also:   XmlParser.readBuffer
See Also:   XmlParser.pushString