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 00:59:08 UTC
cvs commit: xml-xerces/c/src/framework LocalFileInputSource.hpp MemBufInputSource.hpp StdInInputSource.hpp URLInputSource.hpp XMLErrorReporter.hpp XMLValidator.hpp
roddey 00/02/15 15:59:08
Modified: c/src/framework LocalFileInputSource.hpp
MemBufInputSource.hpp StdInInputSource.hpp
URLInputSource.hpp XMLErrorReporter.hpp
XMLValidator.hpp
Log:
More updated documentation of Framework classes.
Revision Changes Path
1.4 +51 -0 xml-xerces/c/src/framework/LocalFileInputSource.hpp
Index: LocalFileInputSource.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/LocalFileInputSource.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- LocalFileInputSource.hpp 2000/02/15 01:21:30 1.3
+++ LocalFileInputSource.hpp 2000/02/15 23:59:06 1.4
@@ -56,6 +56,9 @@
/**
* $Log: LocalFileInputSource.hpp,v $
+ * Revision 1.4 2000/02/15 23:59:06 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.3 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -110,12 +113,47 @@
/** @name Constructors */
//@{
+
+ /**
+ * A local file input source requires a path to the file to load. This
+ * can be provided either as a fully qualified path, a path relative to
+ * the current working directly, or a path relative to a provided base
+ * path.
+ *
+ * The completed path will become the system id of this input source.
+ * The constructors don't take any public id for local files, but you
+ * still set them via the parent class' setPublicId() method of course.
+ *
+ * This constructor takes an explicit base path and a possibly relative
+ * path. If the relative path is seen to be fully qualified, it is used
+ * as is. Otherwise, it is made relative to the passed base path.
+ *
+ * @param basePath The base path from which the passed relative path
+ * will be based, if the relative part is indeed
+ * relative.
+ *
+ * @param relativePath The relative part of the path. It can actually
+ * be fully qualified, in which case it is taken
+ * as is.
+ */
LocalFileInputSource
(
const XMLCh* const basePath
, const XMLCh* const relativePath
);
+ /**
+ * This constructor takes a single parameter which is the fully qualified
+ * or relative path. If it is fully qualified, it is taken as is. If it is
+ * relative, then it is completed relative to the current working directory
+ * (or the equivalent on the local host machine.)
+ *
+ * The completed path will become the system id of this input source.
+ * The constructors don't take any public id for local files, but you
+ * still set them via the parent class' setPublicId() method of course.
+ *
+ * @param filePath The relative or fully qualified path.
+ */
LocalFileInputSource
(
const XMLCh* const filePath
@@ -131,7 +169,20 @@
// -----------------------------------------------------------------------
// Virtual input source interface
// -----------------------------------------------------------------------
+
+ /** @name Virtual methods */
+ //{@
+
+ /**
+ * This method will return a binary input stream derivative that will
+ * parse from the local file indicatedby the system id.
+ *
+ * @return A dynamically allocated binary input stream derivative that
+ * can parse from the file indicated by the system id.
+ */
virtual BinInputStream* makeStream() const;
+
+ //@}
};
#endif
1.4 +69 -0 xml-xerces/c/src/framework/MemBufInputSource.hpp
Index: MemBufInputSource.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/MemBufInputSource.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- MemBufInputSource.hpp 2000/02/15 01:21:30 1.3
+++ MemBufInputSource.hpp 2000/02/15 23:59:06 1.4
@@ -56,6 +56,9 @@
/**
* $Log: MemBufInputSource.hpp,v $
+ * Revision 1.4 2000/02/15 23:59:06 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.3 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -120,6 +123,26 @@
/** @name Constructors */
//@{
+
+ /**
+ * A memory buffer input source is constructed from a buffer of byte
+ * data, and the count of bytes in that buffer. The parser will parse
+ * from this memory buffer until it has eaten the indicated number of
+ * bytes.
+ *
+ * Note that the system id provided serves two purposes. Firstly it is
+ * going to be displayed in error messages as the source of the error.
+ * And secondly, any entities which are refered to from this entity
+ * via relative paths/URLs will be relative to this fake system id.
+ *
+ * @param srcDocBytes The actual data buffer to be parsed from.
+ * @param byteCount The count of bytes (not characters, bytes!)
+ * in the buffer.
+ * @Param bufId A fake system id for the buffer.
+ * @Param adoptBuffer Indicates whether this object should adopt
+ * the buffer (i.e. make a copy of it) or just
+ * use it in place.
+ */
MemBufInputSource
(
const XMLByte* const srcDocBytes
@@ -128,6 +151,10 @@
, const bool adoptBuffer = false
);
+ /**
+ * This constructor is identical to the previous one, except that it takes
+ * the fake system id in local code page form and transcodes it internally.
+ */
MemBufInputSource
(
const XMLByte* const srcDocBytes
@@ -139,6 +166,10 @@
/** @name Destructor */
//@{
+ /**
+ * If the buffer was adopted, the copy made during construction is deleted
+ * at this point.
+ */
~MemBufInputSource();
//@}
@@ -146,13 +177,51 @@
// -----------------------------------------------------------------------
// Virtual input source interface
// -----------------------------------------------------------------------
+
+ /** @name Virtual methods */
+ //{@
+
+ /**
+ * This method will return a binary input stream derivative that will
+ * parse from the memory buffer. If setCopyBufToStream() has been set,
+ * then the stream will make its own copy. Otherwise, it will use the
+ * buffer as is (in which case it must remain valid until the stream
+ * is no longer in use, i.e. the parse completes.)
+ *
+ * @return A dynamically allocated binary input stream derivative that
+ * can parse from the memory buffer.
+ */
BinInputStream* makeStream() const;
+ //@}
+
// -----------------------------------------------------------------------
// Setter methods
// -----------------------------------------------------------------------
+
+ /** @name Setter methods */
+
+ //{@
+
+ /**
+ * By default, for safety's sake, each newly created stream from this
+ * input source will make its own copy of the buffer to stream from. This
+ * avoids having to deal with aliasing of the buffer for simple work. But,
+ * for higher performance applications or for large buffers, this is
+ * obviously not optimal.
+ *
+ * In such cases, you can call this method to turn off that default
+ * action. Once turned off, the streams will just get a pointer to the
+ * buffer and parse directly from that. In this case, you must insure that
+ * the buffer remains valid for as long as any parse events are still
+ * using it.
+ *
+ * @param newState The new boolean flag state to set.
+ */
void setCopyBufToStream(const bool newState);
+
+ //@}
private :
1.4 +24 -1 xml-xerces/c/src/framework/StdInInputSource.hpp
Index: StdInInputSource.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/StdInInputSource.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- StdInInputSource.hpp 2000/02/15 01:21:30 1.3
+++ StdInInputSource.hpp 2000/02/15 23:59:06 1.4
@@ -56,6 +56,9 @@
/**
* $Log: StdInInputSource.hpp,v $
+ * Revision 1.4 2000/02/15 23:59:06 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.3 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -75,7 +78,6 @@
*/
-
#if !defined(STDININPUTSOURCE_HPP)
#define STDININPUTSOURCE_HPP
@@ -103,6 +105,13 @@
/** @name Constructor */
//@{
+
+ /**
+ * Since the standard input is a canned source, the constructor is very
+ * simple. It just uses local platform services to open up the standard
+ * input source as file, a new handleof which it gives to each new stream
+ * it creates.
+ */
StdInInputSource();
//@}
@@ -115,7 +124,21 @@
// -----------------------------------------------------------------------
// Virtual input source interface
// -----------------------------------------------------------------------
+
+
+ /** @name Virtual methods */
+ //{@
+
+ /**
+ * This method will return a binary input stream derivative that will
+ * parse from the standard input of the local host.
+ *
+ * @return A dynamically allocated binary input stream derivative that
+ * can parse from the standardinput.
+ */
BinInputStream* makeStream() const;
+
+ //@}
};
inline StdInInputSource::StdInInputSource() :
1.6 +99 -0 xml-xerces/c/src/framework/URLInputSource.hpp
Index: URLInputSource.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/URLInputSource.hpp,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- URLInputSource.hpp 2000/02/15 01:21:30 1.5
+++ URLInputSource.hpp 2000/02/15 23:59:07 1.6
@@ -56,6 +56,9 @@
/**
* $Log: URLInputSource.hpp,v $
+ * Revision 1.6 2000/02/15 23:59:07 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.5 2000/02/15 01:21:30 roddey
* Some initial documentation improvements. More to come...
*
@@ -103,6 +106,10 @@
* As with all InputSource derivatives. The primary objective of an input
* source is to create an input stream via which the parser can spool in
* data from the referenced source.
+ *
+ * Note that the parse system does not necessarily support URL based XML
+ * entities out of the box. Support for socket based access is optional and
+ * controlled by the per-platform support.
*/
class XMLPARSER_EXPORT URLInputSource : public InputSource
{
@@ -113,29 +120,97 @@
/** @name Constructors */
//@{
+
+ /**
+ * This constructor accepts an already built URL. It is assumed that
+ * it is correct and it will be used as is. In this case, no public id
+ * accepted, but it can still be set via the parent class' setPublicId()
+ * method.
+ *
+ * @param urlId The URL which holds the system id of the entity
+ * to parse.
+ */
URLInputSource(const XMLURL& urlId);
+
+
+ /**
+ * This constructor takes a base system id URL and a possibly relative
+ * system id. The relative part is parsed and, if it is indeed relative,
+ * it will be made relative to the passed base id. Otherwise, it will be
+ * taken as is.
+ *
+ * @param baseId The base system id URL which provides the base
+ * for any relative id part.
+ *
+ * @param systemId The possibly relative system id URL. If its relative
+ * its based on baseId, else its taken as is.
+ */
URLInputSource
(
const XMLCh* const baseId
, const XMLCh* const systemId
);
+
+ /**
+ * This constructor is indentical to the previous one, except that it also
+ * allows you to set a public id if you want to.
+ *
+ * @param baseId The base system id URL which provides the base
+ * for any relative id part.
+ *
+ * @param systemId The possibly relative system id URL. If its relative
+ * its based on baseId, else its taken as is.
+ *
+ * @param publicId The optional public id to set. This is just passed
+ * on to the parent class for storage.
+ */
URLInputSource
(
const XMLCh* const baseId
, const XMLCh* const systemId
, const XMLCh* const publicId
);
+
+
+ /**
+ * This constructor is identical to the second constructor above, except that
+ * it accepts the relative system id part as a local code page string and
+ * just transcodes it internally, as a convenience.
+ *
+ * @param baseId The base system id URL which provides the base
+ * for any relative id part.
+ *
+ * @param systemId The possibly relative system id URL. If its relative
+ * its based on baseId, else its taken as is.
+ */
URLInputSource
(
const XMLCh* const baseId
, const char* const systemId
);
+
+ /**
+ * This constructor is identical to the third constructor above, except that
+ * it accepts the relative and public ids as local code page strings and just
+ * transcodes them internally, as a convenience.
+ *
+ * @param baseId The base system id URL which provides the base
+ * for any relative id part.
+ *
+ * @param systemId The possibly relative system id URL. If its relative
+ * its based on baseId, else its taken as is.
+ *
+ * @param publicId The optional public id to set. This is just passed
+ * on to the parent class for storage.
+ * on to the parent class for storage.
+ */
URLInputSource
(
const XMLCh* const baseId
, const char* const systemId
, const char* const publicId
);
+
//@}
/** @name Destructor */
@@ -147,13 +222,37 @@
// -----------------------------------------------------------------------
// Virtual input source interface
// -----------------------------------------------------------------------
+
+ /** @name Virtual methods */
+ //{@
+
+ /**
+ * This method will return a binary input stream derivative that will
+ * parse from the source refered to by the URL system id.
+ */
BinInputStream* makeStream() const;
+ //@}
+
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
+
+ /** @name Getter methods */
+ //{@
+
+ /**
+ * This method will return a const reference to the URL member which
+ * contains the system id in pre-parsed URL form. If you just want the
+ * string format, call getSystemId() on the parent class.
+ *
+ * @return A const reference to a URL object that contains the current
+ * system id set for this input source.
+ */
const XMLURL& urlSrc() const;
+
+ //@}
private :
1.4 +52 -3 xml-xerces/c/src/framework/XMLErrorReporter.hpp
Index: XMLErrorReporter.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/XMLErrorReporter.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- XMLErrorReporter.hpp 2000/02/15 01:21:31 1.3
+++ XMLErrorReporter.hpp 2000/02/15 23:59:07 1.4
@@ -56,6 +56,9 @@
/**
* $Log: XMLErrorReporter.hpp,v $
+ * Revision 1.4 2000/02/15 23:59:07 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.3 2000/02/15 01:21:31 roddey
* Some initial documentation improvements. More to come...
*
@@ -80,9 +83,10 @@
/**
* This abstract class defines a callback mechanism for the scanner. By
- * creating a derivate of this class and plugging an instance of that class
- * into the scanner, the scanner will call back on the object's methods
- * to report error events.
+ * creating a class that implements this interface and plugging an instance
+ * of that class into the scanner, the scanner will call back on the object's
+ * virtual methods to report error events. This class is also used with the
+ * validator, to allow it to report errors.
*
* This class is primarily for use by those writing their own parser classes.
* If you use the standard parser classes, DOMParser and SAXParser, you won't
@@ -120,6 +124,44 @@
// -----------------------------------------------------------------------
// The error handler interface
// -----------------------------------------------------------------------
+
+ /** @name Error Handler interface */
+ //{@
+
+ /**
+ * This method is called back on by the scanner or validator (or any other
+ * internal parser component which might need to report an error in the
+ * future.) It contains all the information that the client code might
+ * need to report or log the error.
+ *
+ * @param errCode The error code of the error being reported. What
+ * this means is dependent on the domain it is from.
+ *
+ * @param errDomain The domain from which the error occured. The domain
+ * is a means of providing a hierarchical layering to
+ * the error system, so that a single set of error id
+ * numbers don't have to be split up.
+ *
+ * @param type The error type, which is defined mostly by XML which
+ * categorizes errors into warning, errors and validity
+ * constraints.
+ *
+ * @param errorText The actual text of the error. This is translatable,
+ * so can possibly be in the local language if a
+ * translation has been provided.
+ *
+ * @param sysetmId The system id of the entity where the error occured,
+ * fully qualified.
+ *
+ * @param publicId The optional public id of the entity were the error
+ * occured. It can be an empty string if non was provided.
+ *
+ * @param lineNum The line number within the source XML of the error.
+ *
+ * @param colNum The column number within the source XML of the error.
+ * Because of the parsing style, this is usually just
+ * after the actual offending text.
+ */
virtual void error
(
const unsigned int errCode
@@ -132,7 +174,14 @@
, const unsigned int colNum
) = 0;
+ /**
+ * This method is called by the scanner before a new parse event is
+ * about to start. It gives the error handler a chance to reset its
+ * internal state.
+ */
virtual void resetErrors() = 0;
+
+ //@}
protected :
1.4 +282 -0 xml-xerces/c/src/framework/XMLValidator.hpp
Index: XMLValidator.hpp
===================================================================
RCS file: /home/cvs/xml-xerces/c/src/framework/XMLValidator.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- XMLValidator.hpp 2000/02/15 01:21:31 1.3
+++ XMLValidator.hpp 2000/02/15 23:59:07 1.4
@@ -56,6 +56,9 @@
/**
* $Log: XMLValidator.hpp,v $
+ * Revision 1.4 2000/02/15 23:59:07 roddey
+ * More updated documentation of Framework classes.
+ *
* Revision 1.3 2000/02/15 01:21:31 roddey
* Some initial documentation improvements. More to come...
*
@@ -135,6 +138,11 @@
/** @name Destructor */
//@{
+
+ /**
+ * The derived class should clean up its allocated data, then this class
+ * will do the same for data allocated at this level.
+ */
virtual ~XMLValidator()
{
}
@@ -144,12 +152,61 @@
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
+
+ /** @name Getter Methods */
+ //{@
+
+ /**
+ * When an attribute name has no prefix, unlike elements, it is not mapped
+ * to the global namespace. So, in order to have something to map it to
+ * for practical purposes, a id for an empty URL is created and used for
+ * such names.
+ *
+ * @return The URL pool id of the URL for an empty URL "".
+ */
unsigned int getEmptyNamespaceId() const;
+
+ /**
+ * When namespaces are enabled, any elements whose names have no prefix
+ * are mapped to a global namespace. This is the URL id for the URL
+ * to which those names are mapped. It has no official standard text,
+ * but the parser must use some id here.
+ *
+ * @return The URL pool id of the URL for the global namespace.
+ */
unsigned int getGlobalNamespaceId() const;
+
+ /**
+ * When a prefix is found that has not been mapped, an error is issued.
+ * However, if the parser has been instructed not to stop on the first
+ * fatal error, it needs to be able to continue. To do so, it will map
+ * that prefix tot his magic unknown namespace id.
+ *
+ * @return The URL pool id of the URL for the unknown prefix
+ * namespace.
+ */
unsigned int getUnknownNamespaceId() const;
+
+ /**
+ * The prefix 'xml' is a magic prefix, defined by the XML spec and
+ * requiring no prior definition. This method returns the id for the
+ * intrinsically defined URL for this prefix.
+ *
+ * @return The URL pool id of the URL for the 'xml' prefix.
+ */
unsigned int getXMLNamespaceId() const;
+
+ /**
+ * The prefix 'xmlns' is a magic prefix, defined by the namespace spec
+ * and requiring no prior definition. This method returns the id for the
+ * intrinsically defined URL for this prefix.
+ *
+ * @return The URL pool id of the URL for the 'xmlns' prefix.
+ */
unsigned int getXMLNSNamespaceId() const;
+ //@}
+
// -----------------------------------------------------------------------
// Setter methods
@@ -157,6 +214,23 @@
// setScannerInfo() is called by the scanner to tell the validator
// about the stuff it needs to have access to.
// -----------------------------------------------------------------------
+
+ /** @name Setter methods */
+ //{@
+
+ /**
+ * @param owningScanner This is a pointer to the scanner to which the
+ * validator belongs. The validator will often
+ * need to query state data from the scanner.
+ *
+ * @param readerMgr This is a pointer to the reader manager that is
+ * being used by the scanner.
+ *
+ * @param bufMgr This is the buffer manager of the scanner. This
+ * is provided as a convenience so that the validator
+ * doesn't have to create its own buffer manager
+ * during the parse process.
+ */
void setScannerInfo
(
XMLScanner* const owningScanner
@@ -164,20 +238,60 @@
, XMLBufferMgr* const bufMgr
);
+ /**
+ * This method is called to set an error reporter on the validator via
+ * which it will report any errors it sees during parsing or validation.
+ * This is generally called by the owning scanner.
+ *
+ * @param errorReporter A pointer to the error reporter to use. This
+ * is not adopted, just referenced so the caller
+ * remains responsible for its cleanup, if any.
+ */
void setErrorReporter
(
XMLErrorReporter* const errorReporter
);
+ //@}
+
// -----------------------------------------------------------------------
// The virtual validator interface
// -----------------------------------------------------------------------
+
+ /** @name Virtual validator interface */
+ //{@
+
+ /**
+ * The derived class should look for the passed URI (case sensitive) in
+ * its URI pool. If the URI does not exist, then it should be added to the
+ * pool. The new or existing pool id should be returned.
+ */
virtual int addOrFindNSId
(
const XMLCh* const uriText
) = 0;
+ /**
+ * The derived class should look up its declaration of the passed element
+ * from its element pool. It should then use the content model description
+ * contained in that element declaration to validate that the passed list
+ * of child elements are valid for that content model. The count can be
+ * zero, indicating no child elements.
+ *
+ * Note that whitespace and text content are not validated here. Those are
+ * handled by the scanner. So only element ids are provided here.
+ *
+ * @param elemId The pool id of the element whose content is to be
+ * checked.
+ *
+ * @param childIds An array of element ids which represent the elements
+ * found within the parent element, i.e. the content
+ * to be validated.
+ *
+ * @param childCount The number of elements in the childIds array. It can
+ * be zero if the element had none.
+ */
virtual int checkContent
(
const unsigned int elemId
@@ -185,17 +299,43 @@
, const unsigned int childCount
) = 0;
+ /**
+ * For those validators that contrain the possible root elements of a
+ * document to only particular elements, they should use this call to
+ * validate that the passed root element id is a legal root element.
+ */
virtual bool checkRootElement
(
const unsigned int elemId
) = 0;
+ /**
+ * The derived class should fault in the passed XMLAttr value. It should
+ * use the passeed attribute definition (which is passed via the base
+ * type so it must often be downcast to the appropriate type for the
+ * derived validator class), to fill in the passed attribute. This is done
+ * as a performance enhancement since the derived class has more direct
+ * access to the information.
+ */
virtual void faultInAttr
(
XMLAttr& toFill
, const XMLAttDef& attDef
) const = 0;
+ /**
+ * The derived class should look up an element in its element declaration
+ * pool and return a pointer to it. The name should be looked up either via
+ * the qName field (if namespaces are off) or via the uriID/baseName combo
+ * (if namespaces are on.)
+ *
+ * The options allow the caller to indicate how the validator should react
+ * if the element exists or not. If the element does not exist, the option
+ * can indicate that it should be faulted it. If it does not exist and
+ * faulting in is not requested, a null pointer should be returned. The
+ * wasAdded flag should be set if the declaration was faulted in, else it
+ * should be cleared.
+ */
virtual const XMLElementDecl* findElemDecl
(
const unsigned int uriId
@@ -205,6 +345,10 @@
, bool& wasAdded
) const = 0;
+ /*
+ * This method is identical to the previous one, except that it is a non-
+ * const version.
+ */
virtual XMLElementDecl* findElemDecl
(
const unsigned int uriId
@@ -214,18 +358,50 @@
, bool& wasAdded
) = 0;
+ /**
+ * The derived class should look the passed entity declaration name in its
+ * entity pool and return a pointer to the declaration object. If the
+ * entity is not in the pool, it should return a null pointer.
+ *
+ * @param entName The name of the entity to look up. Entity names can
+ * not be namespace based, so its always just a single
+ * unqualified name.
+ *
+ * @param isPE Indicates whether the name represents a parameter
+ * entity or a general entity. The validator should
+ * look at the correct pool for the entity type.
+ */
virtual const XMLEntityDecl* findEntityDecl
(
const XMLCh* const entName
, const bool isPE
) const = 0;
+ /**
+ * This method is identical to the previous one, except that it is non-
+ * const.
+ *
+ * @param entName The name of the entity to look up. Entity names can
+ * not be namespace based, so its always just a single
+ * unqualified name.
+ *
+ * @param isPE Indicates whether the name represents a parameter
+ * entity or a general entity. The validator should
+ * look at the correct pool for the entity type.
+ */
virtual XMLEntityDecl* findEntityDecl
(
const XMLCh* const entName
, const bool isPE
) = 0;
+ /**
+ * The derived class should find the indicate element in its element
+ * declaration pool. If namespaces are on, then it should use the uriId
+ * and base name. Otherwise, it should use the qName. It should return
+ * the element decl pool id for the decl found. If the element is not
+ * not found, it should return the value XMLElementDecl::fgInvalidElemId;
+ */
virtual unsigned int findElemId
(
const unsigned int uriId
@@ -233,61 +409,166 @@
, const XMLCh* const qName
) const = 0;
+ /**
+ * The derived class should look up the passed notation name in its
+ * notation decl pool. If the name is not found, it should return a null
+ * pointer. If it is found, it should return a pointer to the declaration
+ * object.
+ */
virtual const XMLNotationDecl* findNotationDecl
(
const XMLCh* const notName
) const = 0;
+ /**
+ * This method is identical to the previous method except that it is non-
+ * const.
+ */
virtual XMLNotationDecl* findNotationDecl
(
const XMLCh* const notName
) = 0;
+ /**
+ * The derived class should look up the passed namespace name (prefix) in
+ * its namespace name pool and return the id. If not found, it should
+ * return zero, which is never a valid pool id.
+ */
virtual unsigned int findNSId
(
const XMLCh* const nsName
) const = 0;
+ /**
+ * The derived class should return the element from its element decl pool
+ * which has the indicated element id. Given that these ids are gotten from
+ * the validator itself, it should always be valid. If not, then a major
+ * internal error has occured.
+ */
virtual const XMLElementDecl* getElemDecl
(
const unsigned int elemId
) const = 0;
+ /**
+ * This method is identical to the previous method, except that it is a
+ * non-const version.
+ */
virtual XMLElementDecl* getElemDecl
(
const unsigned int elemId
) = 0;
+ /**
+ * The derived class should find the passed URI id in its URI pool and
+ * copy the text of that URI into the passed buffer. Since these ids are
+ * obtained from the validator itself, they should always be valid. If
+ * not, then a major internal error has occured.
+ */
virtual bool getURIText
(
const unsigned int uriId
, XMLBuffer& uriBufToFill
) const = 0;
+ /**
+ * This method is called by the scanner after the parse has completed. It
+ * gives the validator a chance to check certain things that can only be
+ * checked after the whole document has been parsed, such as referential
+ * integrity of ID/IDREF pairs and so forth. The validator should just
+ * issue errors for any problems it finds.
+ */
virtual void postParseValidation() = 0;
+ /**
+ * This method is called by the scanner before a new document is about
+ * to start. It gives the validator a change to reset itself in preperation
+ * for another validation pass.
+ */
virtual void reset() = 0;
+ /**
+ * The derived class should return a boolean that indicates whether it
+ * requires namespace processing or not. Some do and some allow it to be
+ * optional. This flag is used to control whether the client code's
+ * requests to disable namespace processing can be honored or not.
+ */
virtual bool requiresNamespaces() const = 0;
+ /**
+ * The derived class should apply any rules to the passed attribute value
+ * that are above and beyond those defined by XML 1.0. The scanner itself
+ * will impose XML 1.0 rules, based on the type of the attribute. This
+ * will generally be used to check things such as range checks and other
+ * datatype related validation.
+ *
+ * If the value breaks any rules as defined by the derived class, it
+ * should just issue errors as usual.
+ */
virtual void validateAttrValue
(
const XMLAttDef& attDef
, const XMLCh* const attrValue
) = 0;
+ //@}
// -----------------------------------------------------------------------
// Virtual DTD handler interface. If handlesDTD() returns true, then
// scanDTD() will be called when a DOCTYPE is seen.
// -----------------------------------------------------------------------
+
+ /** @name Virtual DTD handler interface */
+ //{@
+
+ /**
+ * This method allows the scanner to ask the validator if it handles
+ * DTDs or not.
+ */
virtual bool handlesDTD() const = 0;
+
+ /**
+ * This method is called by the scanner when it is time for the validator
+ * to parse the DTD. At the time of this call, the parser has parsed up to
+ * the [ of the DOCTYPE line. This call should parse to the ]> that ends
+ * the DOCTYPE line, and any external subset referenced.
+ *
+ * @param reuseValidator Indicates whether the current state of the
+ * validator should be kept. If the DTD validator
+ * sees any internal subset, it should consider
+ * it an error for this to be true. Otherwise, it
+ * just ignores any external subset and returns
+ * with the state unchanged.
+ */
virtual void scanDTD(const bool reuseValidator) = 0;
+ //@}
+
// -----------------------------------------------------------------------
// Error emitter methods
// -----------------------------------------------------------------------
+
+ /** @name Error emittor methods */
+ //{@
+
+ /**
+ * This call is a convenience by which validators can emit errors. Most
+ * of the grunt work of loading the text, getting the current source
+ * location, ect... is handled here.
+ *
+ * If the loaded text has replacement parameters, then text strings can be
+ * passed. These will be used to replace the tokens {0}, {1}, {2}, and {3}
+ * in the order passed. So text1 will replace {0}, text2 will replace {1},
+ * and so forth.
+ *
+ * @param toEmit The error code to emit. it must be one of the defined
+ * validator error codes.
+ *
+ * @param textX Up to four replacement parameters. They can be provided
+ * as either XMLCh strings, or local code page strings which
+ * will be transcoded internally.
+ */
void emitError(const XML4CValid::Codes toEmit);
void emitError
(
@@ -306,6 +587,7 @@
, const char* const text4 = 0
);
+ //@}
protected :