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