5 Package Parser APIs for C++

Parser Datatypes

Table 5-1 summarizes the datatypes of the Parser package.

ParserExceptionCode

Parser implementation of exceptions.

CPXML2743Definition

typedef enum ParserExceptionCode {
   PARSER_UNDEFINED_ERR = 0,
   PARSER_VALIDATION_ERR = 1, 
   PARSER_VALIDATOR_ERR = 2, 
   PARSER_BAD_ISOURCE_ERR = 3, 
   PARSER_CONTEXT_ERR = 4,
   PARSER_PARAMETER_ERR = 5, 
   PARSER_PARSE_ERR = 6, 
   PARSER_SAXHANDLER_SET_ERR = 7, 
   PARSER_VALIDATOR_SET_ERR = 8 } 
ParserExceptionCode;

DOMParserIdType

Defines parser identifiers.

CPXML2745Definition

typedef enum DOMParserIdType {      DOMParCXml         = 1    } DOMParserIdType;
ypedef enum CompareHowCode {
   START_TO_START = 0,
   START_TO_END = 1, 
   END_TO_END = 2, 
   END_TO_START = 3 }
CompareHowCode;

SAXParserIdType

Defines parser identifiers.

CPXML2747Definition

typedef enum SAXParserIdType {
   SAXParCXml = 1 } 
SAXParserIdType;

SchValidatorIdType

Defines validator identifiers.These identifiers are used as parameters to the XML tools factory when a particular validator object has to be created.

CPXML2749Definition

typedef enum SchValidatorIdType {
   SchValCXml        = 1
} SchValidatorIdType;

DOMParser Interface

Table 5-2 summarizes the methods available through the DOMParser interface.

getContext()

Each parser object is allocated and executed in a particular Oracle XML context. This member function returns a pointer to this context.

CPXML2752Syntax

virtual Context* getContext() const = 0;

CPXML2753Returns

(Context*) pointer to parser's context

getParserId()

CPXML2755Syntax

virtual DOMParserIdType getParserId() const = 0;

CPXML2756Returns

(DOMParserIdType) Parser Id

parse()

Parses the document and returns the tree root node

CPXML2758Syntax

virtual DocumentRef< Node>* parse(
   InputSource* isrc_ptr,
   boolean DTDvalidate = FALSE,
   DocumentTypeRef< Node>* dtd_ptr = NULL,
   boolean no_mod = FALSE,
   DOMImplementation< Node>* impl_ptr = NULL)
throw (ParserException) = 0;

isrc_ptr

DTDvalidate

dtd_ptr

no_mod

impl_ptr

CPXML2759Returns

(DocumentRef) document tree

parseDTD()

Parse DTD document.

CPXML2761Syntax

virtual DocumentRef< Node>* parseDTD(
   InputSource* isrc_ptr,
   boolean no_mod = FALSE,
   DOMImplementation< Node>* impl_ptr = NULL)
throw (ParserException) = 0;

isrc_ptr

no_mod

impl_ptr

CPXML2762Returns

(DocumentRef) DTD document tree

parseSchVal()

Parses and validates the document. Sets the validator if the corresponding parameter is not NULL.

CPXML2764Syntax

virtual DocumentRef< Node>* parseSchVal(
   InputSource* src_par,
   boolean no_mod = FALSE,
   DOMImplementation< Node>* impl_ptr = NULL,
   SchemaValidator< Node>* tor_ptr = NULL)
throw (ParserException) = 0;

isrc_ptr

no_mod

impl_ptr

tor_ptr

CPXML2765Returns

(DocumentRef) document tree

setValidator()

Sets the validator for all validations except when another one is given in parseSchVal

CPXML2767Syntax

virtual void setValidator(
SchemaValidator< Node>* tor_ptr) = 0;

tor_ptr

GParser Interface

Table 5-3 summarizes the methods available through the GParser interface.

SetWarnDuplicateEntity()

Specifies if entities that are declared more than once will cause warnings to be issued.

CPXML2770Syntax

void setWarnDuplicateEntity(
   boolean par_bool);

par_bool

getBaseURI()

Returns the base URI for the document. Usually only documents loaded from a URI will automatically have a base URI. Documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, but a base URI may have been set for them using setBaseURI, for the purposes of resolving relative URIs in inclusion.

CPXML2772Syntax

oratext* getBaseURI() const;

CPXML2773Returns

(oratext *) current document's base URI [or NULL]

getDiscardWhitespaces()

Checks if formatting whitespaces between elements, such as newlines and indentation in input documents are discarded. By default, all input characters are preserved.

CPXML2775Syntax

boolean getDiscardWhitespaces() const;

CPXML2776Returns

(boolean) TRUE if whitespace between elements are discarded

getExpandCharRefs()

Checks if character references are expanded in the DOM data. By default, character references are replaced by the character they represent. However, when a document is saved those characters entities do not reappear. To ensure they remain through load and save, they should not be expanded.

CPXML2778Syntax

boolean getExpandCharRefs() const;

CPXML2779Returns

(boolean) TRUE if character references are expanded

getSchemaLocation()

Gets schema location for this document. It is used to figure out the optimal layout when loading documents into a database.

CPXML2781Syntax

oratext* getSchemaLocation() const;

CPXML2782Returns

(oratext*) schema location

getStopOnWarning()

When TRUE is returned, warnings are treated the same as errors and cause parsing, validation, and so on, to stop immediately. By default, warnings are issued but the processing continues.

CPXML2784Syntax

boolean getStopOnWarning() const;

CPXML2785Returns

(boolean) TRUE if document processing stops on warnings

getWarnDuplicateEntity()

Get if entities which are declared more than once will cause warnings to be issued.

CPXML2787Syntax

boolean getWarnDuplicateEntity() const;

CPXML2788Returns

(boolean) TRUE if multiple entity declarations cause a warning

setBaseURI()

Sets the base URI for the document. Usually only documents that were loaded from a URI will automatically have a base URI. Documents loaded from other sources (stdin, buffer, and so on) will not naturally have a base URI, but a base URI may have been set for them using setBaseURI, for the purposes of resolving relative URIs in inclusion.

CPXML2790Syntax

void setBaseURI( oratext* par);

par

setDiscardWhitespaces()

Sets if formatting whitespaces between elements (newlines and indentation) in input documents are discarded. By default, ALL input characters are preserved.

CPXML2792Syntax

void setDiscardWhitespaces(
   boolean par_bool);

par_bool

setExpandCharRefs()

Sets if character references should be expanded in the DOM data. Ordinarily, character references are replaced by the character they represent. However, when a document is saved those characters entities do not reappear. To ensure they remain through load and save is to not expand them.

CPXML2794Syntax

void setExpandCharRefs( 
   boolean par_bool);

par_bool

setSchemaLocation()

Sets schema location for this document. It is used to figure out the optimal layout when loading documents into a database.

CPXML2796Syntax

void setSchemaLocation(
   oratext* par);

par

setStopOnWarning()

When TRUE is set, warnings are treated the same as errors and cause parsing, validation, and so on, to stop immediately. By default, warnings are issued but the processing continues.

CPXML2798Syntax

void setStopOnWarning( 
   boolean par_bool);

par_bool

ParserException Interface

Table 5-4 summarizes the methods available through the ParserException interface.

getCode()

Virtual member function inherited from XmlException.

CPXML2801Syntax

virtual unsigned getCode() const = 0;

CPXML2802Returns

(unsigned) numeric error code (0 on success)

getMesLang()

Virtual member function inherited from XmlException.

CPXML2804Syntax

virtual oratext* getMesLang() const = 0;

CPXML2805Returns

(oratext*) Current language (encoding) of error messages

getMessage()

Virtual member function inherited from XmlException.

CPXML2807Syntax

virtual oratext* getMessage() const = 0;

CPXML2808Returns

(oratext *) Error message

getParserCode()

This is a virtual member function that defines a prototype for implementation defined member functions returning parser and validator exception codes, defined in ParserExceptionCode, of the exceptional situations during execution.

CPXML2810Syntax

virtual ParserExceptionCode getParserCode() const = 0;

CPXML2811Returns

(ParserExceptionCode) exception code

SAXHandler Interface

Table 5-5 summarizes the methods available through the SAXHandler interface.

CDATA()

This event handles CDATA, as distinct from Text. The data will be in the data encoding, and the returned length is in characters, not bytes. This is an Oracle extension.

CPXML2814Syntax

virtual void CDATA( 
   oratext* data,
   ub4 size) = 0;

data

size

XMLDecl()

This event marks an XML declaration (XMLDecl). The startDocument event is always first; this event will be the second event. The encoding flag says whether an encoding was specified. For the standalone flag, -1 will be returned if it was not specified, otherwise 0 for FALSE, 1 for TRUE. This member function is an Oracle extension.

CPXML2816Syntax

virtual void XMLDecl( 
   oratext* version,
   boolean is_encoding,
   sword standalone) = 0;

version

is_encoding

standalone

attributeDecl()

This event marks an attribute declaration in the DTD. It is an Oracle extension; not in SAX standard

CPXML2818Syntax

virtual void attributeDecl(
   oratext* attr_name,
   oratext *name, 
   oratext *content) = 0;

attr_name

name

content

characters()

This event marks character data.

CPXML2820Syntax

virtual void characters(
   oratext* ch,
   ub4 size) = 0;

ch

size

comment()

This event marks a comment in the XML document. The comment's data will be in the data encoding. It is an Oracle extension, not in SAX standard.

CPXML2822Syntax

virtual void comment(
   oratext* data) = 0;

data

elementDecl()

This event marks an element declaration in the DTD. It is an Oracle extension; not in SAX standard.

CPXML2824Syntax

virtual void elementDecl( 
   oratext *name, 
   oratext *content) = 0;

name

content

endDocument()

Receive notification of the end of the document.

CPXML2826Syntax

virtual void endDocument() = 0;

endElement()

This event marks the end of an element. The name is the tagName of the element (which may be a qualified name for namespace-aware elements) and is in the data encoding.

CPXML2828Syntax

virtual void endElement( oratext* name) = 0;

notationDecl()

The even marks the declaration of a notation in the DTD. The notation's name, public ID, and system ID will all be in the data encoding. Both IDs are optional and may be NULL.

CPXML2830Syntax

virtual void notationDecl(
   oratext* name,
   oratext* public_id,
   oratext* system_id) = 0;

name

public_id

sysem_id

parsedEntityDecl()

Marks a parsed entity declaration in the DTD. The parsed entity's name, public ID, system ID, and notation name will all be in the data encoding. This is an Oracle extension.

CPXML2832Syntax

virtual void parsedEntityDecl(
   oratext* name,
   oratext* value,
   oratext* public_id,
   oratext* system_id,
   boolean general) = 0;

name

value

public_id

sysem_id

general

processingInstruction()

This event marks a processing instruction. The PI's target and data will be in the data encoding. There is always a target, but the data may be NULL.

CPXML2834Syntax

virtual void processingInstruction( 
   oratext* target,
   oratext* data) = 0;

target

data

startDocument()

Receive notification of the start of document.

CPXML2836Syntax

virtual void startDocument() = 0;

startElement()

This event marks the start of an element.

CPXML2838Syntax

virtual void startElement( 
   oratext* name,
   NodeListRef< Node>* attrs_ptr) = 0;

name

attrs_ptr

startElementNS()

This event marks the start of an element. Note this is the new SAX 2 namespace-aware version. The element's qualified name, local name, and namespace URI will be in the data encoding, as are all the attribute parts.

CPXML2840Syntax

virtual void startElementNS(
   oratext* qname,
   oratext* local,
   oratext* ns_URI,
   NodeListRef< Node>* attrs_ptr) = 0;

qname

local

ns_URI

attrs_ref

unparsedEntityDecl()

Marks an unparsed entity declaration in the DTD. The unparsed entity's name, public ID, system ID, and notation name will all be in the data encoding.

CPXML2842Syntax

virtual void unparsedEntityDecl(
   oratext* name,
   oratext* public_id,
   oratext* system_id,
   oratext* notation_name) = 0;
};

name

public_id

sysem_id

notation_name

whitespace()

This event marks ignorable whitespace data such as newlines, and indentation between lines.

CPXML2844Syntax

virtual void whitespace(
   oratext* data,
   ub4 size) = 0;

data

size

SAXParser Interface

Table 5-6 summarizes the methods available through the SAXParser interface.

getContext()

Each parser object is allocated and executed in a particular Oracle XML context. This member function returns a pointer to this context.

CPXML2847Syntax

virtual Context* getContext() const = 0;

CPXML2848Returns

(Context*) pointer to parser's context

getParserId()

Returns the parser id.

CPXML2850Syntax

virtual SAXParserIdType getParserId() const = 0;

CPXML2851Returns

(SAXParserIdType) Parser Id

parse()

Parses a document.

CPXML2853Syntax

virtual void parse( 
   InputSource* src_ptr,
   boolean DTDvalidate = FALSE,
   SAXHandlerRoot* hdlr_ptr = NULL)
throw (ParserException) = 0;

src_ptr

DTDValidate

hdlr_ptr

parseDTD()

Parses a DTD.

CPXML2855Syntax

virtual void parseDTD( 
   InputSource* src_ptr,
   SAXHandlerRoot* hdlr_ptr = NULL)
throw (ParserException) = 0;

src_ptr

hdlr_ptr

setSAXHandler()

Sets SAX handler for all parser invocations except when another SAX handler is specified in the parser call.

CPXML2857Syntax

virtual void setSAXHandler(
   SAXHandlerRoot* hdlr_ptr) = 0;

hdlr_ptr

SchemaValidator Interface

Table 5-7 summarizes the methods available through the SchemaValidator interface.

getSchemaList()

Return only the size of loaded schema list documents if "list" is NULL. If "list" is not NULL, a list of URL pointers is returned in the user-provided pointer buffer. Note that its user's responsibility to provide a buffer with big enough size.

CPXML2860Syntax

virtual ub4 getSchemaList(
   oratext **list) const = 0;

list

CPXML2861Returns

(ub4) list size and list of loaded schemas (I/O parameter)

getValidatorId()

Get the validator identifier corresponding to the implementation of this validator object.

CPXML2863Syntax

virtual SchValidatorIdType getValidatorId() const = 0;

CPXML2864Returns

(SchValidatorIdType) validator identifier

loadSchema()

Load up a schema document to be used in the next validation session. Throws an exception in the case of an error.

CPXML2866Syntax

virtual void loadSchema( 
   oratext* schema_URI)
throw (ParserException) = 0;

schema_URI

unloadSchema()

Unload a schema document and all its descendants (included or imported in a nested manner from the validator. All previously loaded schema documents will remain loaded until they are unloaded. To unload all loaded schema documents, set schema_URI to be NULL. Throws an exception in the case of an error.

CPXML2868Syntax

virtual void unloadSchema(
   oratext* schema_URI)
throw (ParserException) = 0;

schema_URI