All Frameworks Class Hierarchy This Framework Indexes Previous Next

XMLParserItf CATSAXDefaultHandler

Usage: you can derive this class.

public class CATSAXDefaultHandler

Default base class for SAX2 event handlers.

This class is available as a convenience base class for SAX2 applications: it provides default implementations for all of the callbacks in the four core SAX2 handler classes:

Application writers can extend this class when they need to implement only part of an interface; parser writers can instantiate this class to provide default handlers when the application has not supplied its own.

See also:: , , ,

Constructor and Destructor Index

o CATSAXDefaultHandler(): Constructor
o ~CATSAXDefaultHandler(): Destructor

Method Index

o Characters(CATUnicodeString&): Receives notification of character data.
o EndDocument(): Receives notification of the end of a document.
o EndElement(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&): Receives notification of the end of an element.
o EndPrefixMapping(CATUnicodeString&): Receives notification of the end of the scope of a prefix-URI Namespace mapping.
o Error(CATSAXParseException*): Receives notification of a recoverable error.
o FatalError(CATSAXParseException*): Receives notification of a non-recoverable error.
o IgnorableWhiteSpace(CATUnicodeString&): Receives notification of ignorable whitespace in element content.
o NotationDecl(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&): Receives notification of a notation declaration event.
o ProcessingInstruction(CATUnicodeString&,CATUnicodeString&): Receives notification of a processing instruction.
o ResolveEntity(CATUnicodeString&,CATUnicodeString&,CATISAXInputSource_var&): Allows the application to resolve external entities.
o SetDocumentLocator(CATISAXLocator_var&): Receives an object for locating the origin of SAX content events.
o SkippedEntity(CATUnicodeString&): Receives notification of a skipped entity.
o StartDocument(): Receives notification of the beginning of a document.
o StartElement(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&,CATISAXAttributes_var&): Receives notification of the beginning of an element.
o StartPrefixMapping(CATUnicodeString&,CATUnicodeString&): Receives notification of the beginning of the scope of a prefix-URI Namespace mapping.
o UnparsedEntityDecl(CATUnicodeString&,CATUnicodeString&,CATUnicodeString&,CATUnicodeString&): Receives notification of an unparsed entity declaration event.
o Warning(CATSAXParseException*): Receives notification of a warning.

Constructor and Destructor

o CATSAXDefaultHandler

public CATSAXDefaultHandler(

)

Constructor

o ~CATSAXDefaultHandler

public virtual ~CATSAXDefaultHandler(

)

Destructor

Methods

o Characters

public virtual Characters( const iCharacters)

Receives notification of character data.

The will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the provides useful information.

Note that some parsers will report whitespace using the method rather than this one (validating parsers must do so).

Parameters:

iCharacters: The characters from the XML document.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o EndDocument

public virtual EndDocument(

)

Receives notification of the end of a document.

The SAX parser will invoke this method only once, and it will be the last method invoked during the parse. The parser shall not invoke this method until it has either abandoned parsing (because of an unrecoverable error) or reached the end of input.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o EndElement

public virtual EndElement(	const	`iURI`,
	const	`iLocalName`,
	const	`iQualifiedName`)

Receives notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding event for every event (even when the element is empty).

For information on the names, see .

Parameters:

iURI: The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
iLocalName: The local name (without prefix), or the empty string if Namespace processing is not being performed.
iQualifiedName: The qualified name (with prefix), or the empty string if qualified names are not available.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o EndPrefixMapping

public virtual EndPrefixMapping( const iPrefix)

Receives notification of the end of the scope of a prefix-URI Namespace mapping.

Parameters:

iPrefix: The prefix that was being mapped.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o Error

public virtual Error( iException)

Receives notification of a recoverable error.

This corresponds to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a validating parser would use this callback to report the violation of a validity constraint. The default behaviour is to take no action.

The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end. If the application cannot do so, then the parser should report a fatal error even if the XML 1.0 recommendation does not require it to do so.

Parameters:

iException: The error information encapsulated in a SAX parse exception.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o FatalError

public virtual FatalError( iException)

Receives notification of a non-recoverable error.

This corresponds to the definition of "fatal error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a parser would use this callback to report the violation of a well-formedness constraint.

The application must assume that the document is unusable after the parser has invoked this method, and should continue (if at all) only for the sake of collecting addition error messages: in fact, SAX parsers are free to stop reporting any other events once this method has been invoked.

Parameters:

iException: The error information encapsulated in a SAX parse exception.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o IgnorableWhiteSpace

public virtual IgnorableWhiteSpace( const iCharacters)

Receives notification of ignorable whitespace in element content.

Validating s must use this method to report each chunk of ignorable whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the provides useful information.

Parameters:

iCharacters: The characters from the XML document.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o NotationDecl

public virtual NotationDecl(	const	`iName`,
	const	`iPublicId`,
	const	`iSystemId`)

Receives notification of a notation declaration event.

It is up to the application to record the notation for later reference, if necessary.

At least one of publicId and systemId must be non-empty.

If a system identifier is present, and it is a URL, the SAX parser must resolve it fully before passing it to the application.

Parameters:

iName: The notation name.
iPublicId: The notation's public identifier (can be an empty
iSystemId: The notation's system identifier (can be an empty

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o ProcessingInstruction

public virtual ProcessingInstruction(	const	`iTarget`,
	const	`iData`)

Receives notification of a processing instruction.

The will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

Parameters:

iTarget: The processing instruction target.
iData: The processing instruction data (can be an empty

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

o ResolveEntity

public virtual ResolveEntity(	const	`iPublicId`,
	const	`iSystemId`,
		`oInputSource`)

Allows the application to resolve external entities.

The will call this method before opening any external entity except the top-level document entity (including the external DTD subset, external entities referenced within the DTD, and external entities referenced within the document element): the application may request that the parser resolve the entity itself, that it use an alternative URI, or that it use an entirely different input source.

Application writers can use this method to redirect external system identifiers to secure and/or local URIs, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box).

If the system identifier is a URL, the SAX parser must resolve it fully before reporting it to the application.

Parameters:

iPublicId: The public identifier of the external entity being referenced (can be an empty
iSystemId: The system identifier of the external entity being referenced.
oInputSource: An InputSource object describing the new input source, or NULL to request that the parser open a regular URI connection to the system identifier.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2001	If an I/O error occurs, possibly the result of creating a new the method can raise this error.

See also:

o SetDocumentLocator

public virtual SetDocumentLocator( const iLocator)

Receives an object for locating the origin of SAX content events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application's business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation of the events in this interface. The application should not attempt to use it at any other time.

Parameters:

iLocator: An object that can return the location of any SAX document event.

See also:

o SkippedEntity

public virtual SkippedEntity( const iName)

Receives notification of a skipped entity.

The will invoke this method once for each entity skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities and the http://xml.org/sax/features/external-parameter-entities properties.

Parameters:

iName: The name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]".

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

o StartDocument

public virtual StartDocument(

)

Receives notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other methods in this interface or in (except for ).

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o StartElement

public virtual StartElement(	const	`iURI`,
	const	`iLocalName`,
	const	`iQualifiedName`,
	const	`iAttributes`)

Receives notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding event for every event (even when the element is empty).

All of the element content will be reported, in order, before the corresponding event .

This event allows up to three name components for each element:

the Namespace URI;
the local name; and
the qualified (prefixed) name.

Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes properties:

the Namespace URI and local name are required when the namespaces property is TRUE (the default), and are optional when the namespaces property is FALSE (if one is specified, both must be);
the qualified name is required when the namespace-prefixes property is TRUE, and is optional when the namespace-prefixes property is FALSE (the default).

Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted. The attribute list will contain attributes used for Namespace declarations (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes property is TRUE (it is FALSE by default, and support for a TRUE value is optional).

Parameters:

iURI: The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
iLocalName: The local name (without prefix), or the empty string if Namespace processing is not being performed.
iQualifiedName: The qualified name (with prefix), or the empty string if qualified names are not available.
iAttributes: The attributes attached to the element. If there are no attributes, it shall be an empty

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o StartPrefixMapping

public virtual StartPrefixMapping(	const	`iPrefix`,
	const	`iURI`)

Receives notification of the beginning of the scope of a prefix-URI Namespace mapping.

The information from this event is not necessary for normal Namespace processing: the will automatically replace prefixes for element and attribute names when the http://xml.org/sax/features/namespaces feature is TRUE (the default).

There are cases, however, when applications need to use prefixes in character data or in attribute values, where they cannot safely be expanded automatically; the / events supply the information to the application to expand prefixes in those contexts itself, if necessary.

Note that / events are not guaranteed to be properly nested relative to each-other: all events will occur before the corresponding event, and all events will occur after the corresponding event, but their order is not otherwise guaranteed.

There should never be / events for the "xml" prefix, since it is predeclared and immutable.

Parameters:

iPrefix: The Namespace prefix being declared.
iURI: The Namespace URI the prefix is mapped to.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o UnparsedEntityDecl

public virtual UnparsedEntityDecl(	const	`iName`,
	const	`iPublicId`,
	const	`iSystemId`,
	const	`iNotationName`)

Receives notification of an unparsed entity declaration event.

Note that the notation name corresponds to a notation reported by the event. It is up to the application to record the entity for later reference, if necessary.

If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

Parameters:

iName: The unparsed entity's name.
iPublicId: The entity's public identifier (can be an empty
iSystemId: The entity's system identifier (it must always have one).
iNotationName: name The name of the associated notation.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

o Warning

public virtual Warning( iException)

Receives notification of a warning.

SAX parsers will use this method to report conditions that are not errors or fatal errors as defined by the XML 1.0 recommendation. The default behaviour is to take no action.

The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end.

Parameters:

iException: The warning information encapsulated in a SAX parse exception.

Errors Returned:

Error Class	Error Id	Description
	XMLParserERR_2000	The method can raise a CATSAXException
	XMLParserERR_2002	The method can raise a CATSAXParseException

See also:

This object is included in the file: CATSAXDefaultHandler.h
If needed, your Imakefile.mk should include the module: CatXmlItfBase

XMLParserItf writeClassCharacteristic(); CATSAXDefaultHandler

Constructor and Destructor Index

Method Index

Constructor and Destructor

Methods

XMLParserItf CATSAXDefaultHandler