Using the VA Smalltalk XML DOM parser
VA Smalltalk XML support provides an XML DOM parser to read the XML stream and build a DOM from the stream contents.
AbtXmlDOMParser
The following methods are provided in the AbtXmlDOMParser class:
Class Methods
newNonValidatingParser
Returns a new instance of the parser that uses a new non-validating DTD.
newValidatingParser
Returns a new instance of the parser that uses a new validating DTD.
usingDTD: aDocumentTypeDefinition
Returns a new instance of the parser specifying the DTD to be used for validation.
Instance Methods
decodingEnabled
Returns true if code page conversion should be performed on incoming streams prior to parsing. The default value is true.
decodingEnabled: aBoolean
Sets a boolean attribute, aBoolean, that determines whether code page conversion should be performed on incoming streams. The default value is true.
dtdHandler
Returns the document type definition handler for this parser.
dtdHandler: aDTDHandler
Sets the document type definition handler for this parser.
inputStream
Returns the stream to be parsed.
inputStream: aStream
Sets the stream to be parsed to aStream.
parse: anObject
Parses the incoming XML document and returns the resulting AbtDOMDocument. The parameter, anObject, can be any object that implements the #abtAsXmlInputSource method to convert itself into an AbtXmlInputSource instance. String and Stream instances are handled automatically.
parseDTD:aUriString
Resolves the passed uniform resource identifier (URI), aUriString, parses its contents and returns the result DTD (an instance of AbtDOMDocumentType).
parseURI: aURIString
Resolves the passed uniform resource identifier (URI), aURIString, parses its contents, and returns the resulting DOM.
terminate
Forces an immediate termination of the parser. This method would typically be sent from an exception handler after a fatal error has occurred.
useDTDCache
Returns true if the external DTD resources are to be looked up in an internal cache. The default is true. When this value is false, validating parsers will always parse the external DTD subset. This option does not automatically add DTD resources to the cache. This option determines whether objects existing in the cache are used. Application logic can add DTD objects to the cache using the #addToXmlObjectCache selector of the DTD.
useDTDCache: aBoolean
Sets a boolean attribute, aBoolean, to true if external DTD resources are to be looked up in an internal cache. The default is true. When this value is false, validating parsers will always parse the external DTD subset. This option does not automatically add DTD resources to the cache. This option determines whether objects existing in the cache are used. Application logic can add DTD objects to the cache using the #addToXmlObjectCache selector of the DTD.
validate
Returns true if the parser should perform validation according to the XML specification.
validate: aBoolean
Sets a boolean attribute, aBoolean, that determines whether the parser should perform validation according to the XML specification. The validate attribute must be set prior to sending the #parse: message. Changing the validate attribute after parsing has begun will have no effect on whether or not the parser performs validation.
XML DOM Parser Examples
The following examples use the XML DOM parsing methods.
Create a validating parser and process a local file
To create a validating parser and process a local file, use the newValidatingParser method to create a new instance of the parser that uses a new validating DTD. The following Smalltalk code creates a validating parser and processes the resource.xml file:
| parser |
parser := AbtXmlDOMParser newValidatingParser.
parser parseURI: 'd:\workspce\resource.xml'.
Create a non-validating parser and process a local file
To create a new non-validating parser and process a local file, use the newNonValidatingParser method to create a new instance of the parser that uses a new non-validating DTD. The following Smalltalk code creates a non-validating parser and processes the resource.xml file.
| parser |
parser := AbtXmlDOMParser newNonValidatingParser.
parser parseURI: 'd:\workspce\resource.xml'.
Special cases
When the parser property #decodingEnabled is set to true, the VA Smalltalk code page conversion APIs perform code page conversion on the incoming XML streams. To override the routine that performs code page conversion at runtime, use the following Smalltalk code:
AbtXmlInputSource codePageConverter: MyCodePageConverter.
The #codePageConverter object decodes incoming streams and converts them to the code page of the image. The #codePageConverter object must understand the #convertStream:withEncoding: message.
To perform code page conversion on incoming XML streams, the VA Smalltalk XML support must map the encoding specified in the XML document to its corresponding system code page. For most cases, the default code page mappings are sufficient. However, there may be cases where incoming encodings have no mapping. You can modify code page mapping using the following method:
AbtXmlStreamConverter mapEncoding: 'UTF-8' toCodePage: 65001