You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by ro...@locus.apache.org on 2000/02/16 20:48:57 UTC
cvs commit: xml-xerces/c/src/framework XMLDocumentHandler.hpp XMLElementDecl.hpp
roddey 00/02/16 11:48:57
Modified: c/src/framework XMLDocumentHandler.hpp XMLElementDecl.hpp
Log:
More documentation updates
Revision Changes Path
1.5 +75 -67 xml-xerces/c/src/framework/XMLDocumentHandler.hpp
Index: XMLDocumentHandler.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/XMLDocumentHandler.hpp,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XMLDocumentHandler.hpp 2000/02/15 01:21:30 1.4
+++ XMLDocumentHandler.hpp 2000/02/16 19:48:56 1.5
@@ -56,6 +56,9 @@
/**
* $Log: XMLDocumentHandler.hpp,v $
+ * Revision 1.5 2000/02/16 19:48:56 roddey
+ * More documentation updates
+ *
* Revision 1.4 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -89,11 +92,6 @@
* XML document information up to the parser as it scans through the
* document. The interface is very similar to org.sax.DocumentHandler, but
* has some extra methods required to get all the data out.
- *
- * Some of the methods are designated as 'advanced' callbacks. They are
- * enabled only if the 'setAdvancedCallbacks' flag has been set on the
- * scanner. This scheme is used to avoid overhead when these more advanced
- * events are not needed, such as in a SAX parser.</p>
*/
class XMLPARSER_EXPORT XMLDocumentHandler
{
@@ -110,8 +108,7 @@
/** @name The document handler interface */
//@{
- /**
- * Receive notification of character data.
+ /** Receive notification of character data.
*
* <p>The scanner will call this method to report each chunk of
* character data. The scanner may return all contiguous character
@@ -123,11 +120,11 @@
* <p>The parser must not attempt to read from the array
* outside of the specified range.</p>
*
- * @param chars The content (characters) between markup from the XML
- * document.
- * @param length The number of characters to read from the array.
- * @param cdataSection Indicates that this data is inside a CDATA
- * section.
+ * @param chars The content (characters) between markup from the XML
+ * document.
+ * @param length The number of characters to read from the array.
+ * @param cdataSection Indicates that this data is inside a CDATA
+ * section.
* @see #ignorableWhitespace
* @see Locator
*/
@@ -138,9 +135,11 @@
, const bool cdataSection
) = 0;
- /**
- * Receive notification of comments in the XML content being parsed.
+ /** Receive notification of comments in the XML content being parsed.
*
+ * This scanner will call this method for any comments found in the
+ * content of the document.
+ *
* @param comment The text of the comment.
*/
virtual void docComment
@@ -148,11 +147,14 @@
const XMLCh* const comment
) = 0;
- /**
- * Receive notification of PI's parsed in the XML content.
+ /** Receive notification of PI's parsed in the XML content.
+ *
+ * The scanner will call this method for any PIs it finds within the
+ * content of the document.
*
- * @param target The name of the PI.
- * @param data The body of the PI.
+ * @param target The name of the PI.
+ * @param data The body of the PI. This may be an empty string since
+ * the body is optional.
*/
virtual void docPI
(
@@ -160,23 +162,27 @@
, const XMLCh* const data
) = 0;
- /**
- * Receive notification after the scanner has parsed the end of the
+ /** Receive notification after the scanner has parsed the end of the
* document.
+ *
+ * The scanner will call this method when the current document has been
+ * fully parsed. The handler may use this opportunity to do something with
+ * the data, clean up temporary data, etc...
*/
virtual void endDocument() = 0;
- /**
+ /** Receive notification of the end of an element.
+ *
* This method is called when scanner encounters the end of element tag.
* There will be a corresponding startElement() event for every
* endElement() event, but not necessarily the other way around. For
* empty tags, there is only a startElement() call.
*
- * @param elementDecl The name of the element whose end tag was just
- * parsed.
- * @param uriId The ID of the URI in the URI pool (only valid if
- * name spaces is enabled)
- * @param isRoot Indicates if this is the root element.
+ * @param elementDecl The name of the element whose end tag was just
+ * parsed.
+ * @param uriId The ID of the URI in the URI pool (only valid if
+ * name spaces is enabled)
+ * @param isRoot Indicates if this is the root element.
*/
virtual void endElement
(
@@ -185,19 +191,19 @@
, const bool isRoot
) = 0;
- /**
+ /** Receive notification when a referenced entity's content ends
+ *
* This method is called when scanner encounters the end of an entity
* reference.
*
- * @param entityName The name of the entity reference just scanned.
+ * @param entityName The name of the entity reference just scanned.
*/
virtual void endEntityReference
(
const XMLEntityDecl& entDecl
) = 0;
- /**
- * Receive notification of ignorable whitespace in element content.
+ /** Receive notification of ignorable whitespace in element content.
*
* <p>Validating Parsers must use this method to report each chunk
* of ignorable whitespace (see the W3C XML 1.0 recommendation,
@@ -213,9 +219,9 @@
* <p>The parser must not attempt to read from the array
* outside of the specified range.</p>
*
- * @param chars The whitespace characters from the XML document.
- * @param length The number of characters to read from the array.
- * @param cdataSection Indicates that this data is inside a CDATA
+ * @param chars The whitespace characters from the XML document.
+ * @param length The number of characters to read from the array.
+ * @param cdataSection Indicates that this data is inside a CDATA
* section.
* @see #characters
*/
@@ -226,34 +232,37 @@
, const bool cdataSection
) = 0;
- /**
+ /** Reset the document handler's state, if required
+ *
* This method is used to give the registered document handler a
* chance to reset itself. Its called by the scanner at the start of
* every parse.
*/
virtual void resetDocument() = 0;
- /**
+ /** Receive notification of the start of a new document
+ *
* This method is the first callback called the scanner at the
- * start of every parse.
+ * start of every parse. This is before any content is parsed.
*/
virtual void startDocument() = 0;
- /**
+ /** Receive notification of a new start tag
+ *
* This method is called when scanner encounters the start of an element tag.
* All elements must always have a startElement() tag. Empty tags will
* only have the startElement() tag and no endElement() tag.
- *
- * @param elementDecl The name of the element whose start tag was just
- * parsed.
- * @param uriId The ID of the URI in the URI pool (only valid if
- * name spaces is enabled)
- * @param prefixName The string representing the prefix name
- * @param attrList List of attributes in the element
- * @param attrCount Count of the attributes in the element
- * @param isEmpty Indicates if the element is empty
- * @param isRoot Indicates if this is the root element.
*
+ * @param elementDecl The name of the element whose start tag was just
+ * parsed.
+ * @param uriId The ID of the URI in the URI pool (only valid if
+ * name spaces is enabled)
+ * @param prefixName The string representing the prefix name
+ * @param attrList List of attributes in the element
+ * @param attrCount Count of the attributes in the element
+ * @param isEmpty Indicates if the element is empty, in which case
+ * you should not expect an endElement() event.
+ * @param isRoot Indicates if this is the root element.
*/
virtual void startElement
(
@@ -266,32 +275,31 @@
, const bool isRoot
) = 0;
- /**
- * Receive notification when the scanner hits an entity reference.
+ /** Receive notification when the scanner hits an entity reference.
+ *
* This is currently useful only to DOM parser configurations as SAX
* does not provide any api to return this information.
*
- * @param entityName The name of the entity that was referenced.
+ * @param entityName The name of the entity that was referenced.
*/
virtual void startEntityReference(const XMLEntityDecl& entDecl) = 0;
- /**
- * Receive notification when the scanner hits the XML declaration
- * clause in the XML file. Currently neither DOM nor SAX provide
- * API's to return back this information. This is an advanced
- * callback.
- *
- * @param versionStr The value of the <code>version</code> attribute
- * of the XML decl.
- * @param encodingStr The value of the <code>encoding</code> attribute
- * of the XML decl.
- * @param standaloneStr The value of the <code>standalone</code>
- * attribute of the XML decl.
- * @param autoEncodingStr The encoding string auto-detected by the
- * scanner. In absence of any 'encoding' attribute in the
- * XML decl, the XML standard specifies how a parser can
- * auto-detect. If there is no <code>encodingStr</code>
- * this is what will be used to try to decode the file.
+ /** Receive notification of an XML declaration
+ *
+ * Currently neither DOM nor SAX provide API's to return back this
+ * information.
+ *
+ * @param versionStr The value of the <code>version</code> attribute
+ * of the XML decl.
+ * @param encodingStr The value of the <code>encoding</code> attribute
+ * of the XML decl.
+ * @param standaloneStr The value of the <code>standalone</code>
+ * attribute of the XML decl.
+ * @param autoEncodingStr The encoding string auto-detected by the
+ * scanner. In absence of any 'encoding' attribute in the
+ * XML decl, the XML standard specifies how a parser can
+ * auto-detect. If there is no <code>encodingStr</code>
+ * this is what will be used to try to decode the file.
*/
virtual void XMLDecl
(
1.4 +211 -1 xml-xerces/c/src/framework/XMLElementDecl.hpp
Index: XMLElementDecl.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/XMLElementDecl.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- XMLElementDecl.hpp 2000/02/15 01:21:30 1.3
+++ XMLElementDecl.hpp 2000/02/16 19:48:56 1.4
@@ -56,6 +56,9 @@
/**
* $Log: XMLElementDecl.hpp,v $
+ * Revision 1.4 2000/02/16 19:48:56 roddey
+ * More documentation updates
+ *
* Revision 1.3 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -175,6 +178,35 @@
// -----------------------------------------------------------------------
// The virtual element decl interface
// -----------------------------------------------------------------------
+
+ /** @name Virual ElementDecl interface */
+ //@{
+
+ /** Find an attribute by name or optionally fault it in.
+ *
+ * The derived class should look up the passed attribute in the list of
+ * of attributes for this element. If namespaces are enabled, then it
+ * should use the uriId/baseName pair, else it should use the qName. The
+ * options allow the caller to indicate whether the attribute should be
+ * defaulted in if not found. If it is defaulted in, then wasAdded should
+ * be set, else it should be cleared. If its not found and the caller does
+ * not want defaulting, then return a null pointer.
+ *
+ * @param qName This is the qName of the attribute, i.e. the actual
+ * lexical name found.
+ *
+ * @param uriId This is the id of the URI of the namespace to which
+ * this attribute mapped. Only valid if namespaces are
+ * enabled.
+ *
+ * @param baseName This is the base part of the name, i.e. after any
+ * prefix.
+ *
+ * @param options Indicates the lookup options.
+ *
+ * @param wasAdded Should be set if the attribute is faulted in, else
+ * cleared.
+ */
virtual XMLAttDef* findAttr
(
const XMLCh* const qName
@@ -183,40 +215,218 @@
, const LookupOpts options
, bool& wasAdded
) const = 0;
+
+ /** Get a list of attributes defined for this element.
+ *
+ * The derived class should return a reference to some member object which
+ * implements the XMLAttDefList interface. This object gives the scanner the
+ * ability to look through the attributes defined for this element.
+ *
+ * It is done this way for efficiency, though of course this is not thread
+ * safe. The scanner guarantees that it won't ever call this method in any
+ * nested way, but the outside world must be careful about when it calls
+ * this method, and optimally never would.
+ */
virtual XMLAttDefList& getAttDefList() const = 0;
+
+ /** Get the base name of this element type.
+ *
+ * The derived class should return the base name part of the element's
+ * name. This is the same regardless of whether namespaces are enabled or
+ * not.
+ *
+ * @return A const pointer to the base name of the element decl.
+ */
virtual const XMLCh* getBaseName() const = 0;
+
+ /** The character data options for this element type
+ *
+ * The derived class should return an appropriate character data opts value
+ * which correctly represents its tolerance towards whitespace or character
+ * data inside of its instances. This allows the scanner to do all of the
+ * validation of character data.
+ */
virtual CharDataOpts getCharDataOpts() const = 0;
+
+ /** Get the full name of this element type.
+ *
+ * The derived class should reutrn the full name of the element. If namespaces
+ * are not enabled, then this is the qName. Else it is the {uri}baseName
+ * form. For those validators that always require namespace processing, it
+ * will always be in the latter form because namespace processing will always
+ * be on.
+ */
virtual const XMLCh* getFullName() const = 0;
+
+ /** Indicate whether this element type defined any attributes
+ *
+ * The derived class should return a boolean that indicates whether this
+ * element has any attributes defined for it or not. This is an optimization
+ * that allows the scanner to skip some work if no attributes exist.
+ */
virtual bool hasAttDefs() const = 0;
+
+ /** Reset the flags on the attribute definitions.
+ *
+ * This method is called by the scanner at the beginning of each scan
+ * of a start tag, asking this element decl to reset the 'declared' flag
+ * of each of its attribute defs. This allows the scanner to mark each
+ * one as declared yet or not.
+ */
virtual bool resetDefs() = 0;
+ //@}
+
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
- XMLContentModel* getContentModel();
+
+ /** @name Getter methods */
+ //{@
+
+ /** Get a pointer to the abstract content model
+ *
+ * This method will return a const pointer to the content model object
+ * of this element. This class is a simple abstraction that allows an
+ * element to define and use multiple, specialized content model types
+ * internally but still allow the outside world to do simple stuff with
+ * them.
+ *
+ * @return A const pointer to the element's content model, via the basic
+ * abstract content model type.
+ */
const XMLContentModel* getContentModel() const;
+
+ /** Get a pointer to the abstract content model
+ *
+ * This method is identical to the previous one, except that it is non
+ * const.
+ */
+ XMLContentModel* getContentModel();
+
+ /** Get the create reason for this element type
+ *
+ * This method returns an enumeration which indicates why this element
+ * declaration exists. Elements can be used before they are actually
+ * declared, so they will often be faulted into the pool and marked as
+ * to why they are there.
+ *
+ * @return An enumerated value that indicates the reason why this element
+ * was added to the element decl pool.
+ */
CreateReasons getCreateReason() const;
+
+ /** Get the element decl pool id for this element type
+ *
+ * This method will return the element decl pool id of this element
+ * declaration. This uniquely identifies this element type within the
+ * parse event that it is declared within. This value is assigned by the
+ * validator whose decl pool this object belongs to.
+ *
+ * @return The element decl id of this element declaration.
+ */
unsigned int getId() const;
+
+ /** Indicate whether this element type has been declared yet
+ *
+ * This method returns a boolean that indicates whether this element
+ * has been declared yet. There are a number of reasons why an element
+ * declaration can be faulted in, but eventually it must be declared or
+ * its an error. See the CreateReasons enumeration.
+ *
+ * @return true if this element has been declared, else false.
+ */
bool isDeclared() const;
+ //@}
+
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
+
+ /** @name Setter methods */
+ //{@
+
+ /** Set the content model object for this element type
+ *
+ * This method will adopt the based content model object. This is called
+ * by the actual validator which is parsing its DTD or Schema or whatever
+ * a creating an element decl. It will build what it feels is the correct
+ * content model type object and store it on the element decl object via
+ * this method.
+ *
+ * @param newModelToAdopt This method will adop the passed content model
+ * object. Any previous object is destroyed.
+ */
void setContentModel(XMLContentModel* const newModelToAdopt);
+
+ /** Update the create reason for this element type.
+ *
+ * This method will update the 'create reason' field for this element
+ * decl object. As the validator parses its DTD, Schema, etc... it will
+ * encounter various references to an element declaration, which will
+ * cause the element declaration to either be declared or to be faulted
+ * into the pool in preperation for some future declaration. As it does
+ * so,it will update this field to indicate the current satus of the
+ * decl object.
+ */
void setCreateReason(const CreateReasons newReason);
+
+ /** Set the element decl pool id for this element type
+ *
+ * This method will set the pool id of this element decl. This is called
+ * by the validator which created this object, and will provide this
+ * decl object with a unique id within the parse event that created it.
+ */
void setId(const unsigned int newId);
+ //@}
+
// -----------------------------------------------------------------------
// Miscellaneous methods
// -----------------------------------------------------------------------
+
+ /** @name Miscellenous methods */
+ //{@
+
+ /** Geta formatted string of the content model
+ *
+ * This method is a convenience method which will create a formatted
+ * representation of the content model of the element. It will not always
+ * exactly recreate the original model, since some normalization or
+ * or reformatting may occur. But, it will be a technically accurate
+ * representation of the original content model.
+ *
+ * The format depends upon the validator, since content models are
+ * expressed differently in different structural description languages.
+ *
+ * @param validator The validator which owns this object, and which
+ * therefore has the information required to format
+ * the content model.
+ *
+ * @return A pointer to an internal buffer which contains the formatted
+ * content model. The caller does not own this buffer and should
+ * copy it if it needs to be kept around.
+ */
const XMLCh* getFormattedContentModel
(
const XMLValidator& validator
) const;
+
+ /** Support keyed collections
+ *
+ * This method allows objects of this type be placed into one of the
+ * standard keyed collections. This method will return the full name of
+ * the element, which will vary depending upon the type of the validator.
+ *
+ * @return A const pointer to teh full name of this element type.
+ */
const XMLCh* getKey() const;
+
+ //@}
protected :