Hi folks,
Since there hasn't been much response to the revised interfaces I
posted on the 9th, I'm assuming no one has huge problems with
them. I'm appending them to this message just in case. The main
point of this message is to propose a way forward that takes into
account the need to get a production version of Xerces2 out the
door with a stable XNI as its base.
I'd like to see the XNI changes made before the production-grade
Xerces2 is put out. I think things like writing a default
implementation for grammar caching, and coding up a configuration
to permit grammar preparsing, can wait for a bit. Since
the chances are that a bug or two will get by anyway, perhaps we
can aim to put out a Xerces 2.0.1 at the end of February where
default grammar caching, grammar preparsing configurations and no
doubt bug fixes can be included? What do folks feel about that
idea?
To be more specific about the changes that it seems to me need to be
made before Xerces 2.0.0 comes out:
- XMLResourceDescription needs to be added to the
org.apache.xerces.xni package;
- XMLLocator and XMLEntityResolver need to be updated to extend
this interface;
- XMLGrammarDescription needs to be added somewhere (probably to
xni.parsers, but I'm unsure here);
- XMLGrammarPool needs to be added to the same place as
XMLGrammarDescription
- Properties and accompanying docs need to be updated so they
expect GrammarPools of this type instead of ones from the
current location;
- XSDGrammarDescription and DTDGrammarDescription need to be
added to the appropriate packages under org.apache.xerces.impl.
(Nobody's volunteered to help make DTDGrammarDescription better
yet ... anyone?)
- an XMLGrammarPoolImpl needs to be placed, probably under
org.apache.xerces.impl.validation; this wll eventually be our
default implementation, but would just have no-op methods for
now (something for Configurations to instantiate);
- XSGrammarResolver needs to be renamed XSGrammarBucket to more
accurately reflect its function;
- org.apache.xerces.impl.validation.GrammarPool needs to become
org.apache.xerces.impl.dtd.DTDGrammarBucket for the same
reason;
- Lots of code needs to be updated to use the new names.
Once Xerces2.0.0 comes out we can then discuss in more detail
just what the default grammar-caching implementation should
look like etc. But if we get all this done beforehand--and I
think it's possible to do it, and do it well, if we start
soon--we'll be off to a very good start on this front.
Anyway, here are those interfaces again FYI. I think we need to
start doing this soon, to make sure everything gets done right;
so could folks provide feedback by the end of Wednesday? I'll
undertake to try and make the needed changes before the end of
the week if no one has any serious objections.
// The Grammar Pool interface
public interface XMLGrammarPool {
// we are trying to make this XMLGrammarPool work for all kinds of
// grammars, so we have a parameter "grammarType" for each of the methods.
// It could be "schema", "dtd, etc., or it could be recast into an
// integer.
// retrieve the initial known set of grammars. this method is
// called by a validator before the validation starts. the application
// can provide an initial set of grammars available to the current
// validation attempt.
public Grammar[] retrieveInitialGrammarSet(String grammarType);
// return the final set of grammars that the validator ended up
// with.
// This method is called after the
// validation finishes. The application may then choose to cache some
// of the returned grammars.
public void cacheGrammars(String grammarType, Grammar[] grammars);
// This method requests that the application retrieve a grammar
// corresponding to the given GrammarDescription from its cache.
// If it cannot do so it must return null; the parser will then
// call the EntityResolver. An application must not call its
// EntityResolver itself from this method.
public Grammar retrieveGrammar(XMLGrammarDescription desc);
} // XMLGrammarPool
// This represents the basic physical description of the location of any
// XML resource (a Schema grammar, a DTD, a general entity etc.)
public interface XMLResourceDescription {
/** Returns the public identifier. */
public String getPublicId();
/** Returns the system identifier. */
public String getSystemId();
/** Returns the base system identifier. */
public String getBaseSystemId();
} // XMLResourceDescription
// This interface describes basic attributes of XML grammars--their
// physical location and their type.
public interface XMLGrammarDescription extends XMLResourceDescription {
// returns the type of the grammar (e.g., DTD or XSD).
public String getGrammarType();
} // XMLGrammarDescription
// All information specific to dTD grammars.
public class XMLDTDDescription implements XMLGrammarDescription {
// used to indicate whether it's an internal or external DTD
public final static int INTERNAL_DTD = 0;
public final static int EXTERNAL_DTD = 1;
public int getDTDType();
// this returns the name of the root element if this is a DOCTYPE
// entity, or the name of the entity if it's a standard entity
// declaration.
public String getEntityName();
}
// All information specific to XML Schema grammars.
public class XSDDescription implements XMLGrammarDescription {
// used to indicate what triggered the call
// we don't include xsi:schemaLocation/noNamespaceSchemaLocation
// because we'll defer the loading of schema documents until
// a component from that namespace is referenced from the instance
public final static int CONTEXT_INCLUDE = 0;
public final static int CONTEXT_REDEFINE = 1;
public final static int CONTEXT_IMPORT = 2;
public final static int CONTEXT_ELEMENT = 3;
public final static int CONTEXT_ATTRIBUTE = 4;
public final static int CONTEXT_XSITYPE = 5;
public int getContextType();
// for include and redefine, the namespace will be the target
// namespace of the enclosing document. (or empty string?)
public String getTargetNamespace();
// for import and xsi:location attributes, it's possible to have
// multiple hints for one namespace. so it's an array whose first
// element will derive from the noNamespaceSchemaLocation or
// schemaLocation property as the case of the targetNamespace may
// be:
public String[] getLocationHints();
// If it's triggered by the document, the name of the
// triggering component: element, attribute or xsi:type
public QName getTriggeringComponent();
// More information about "other location hint":
// everything about the enclosing element
public QName getEnclosingElementName();
public XMLAttributes getAttributes();
}
/**
* This interface is used to resolve external parsed entities. The
* application can register an object that implements this interface
* with the parser configuration in order to intercept entities and
* resolve them explicitly. If the registered entity resolver cannot
* resolve the entity, it should return <code>null</code> so that the
* parser will try to resolve the entity using a default mechanism.
*
* @see XMLParserConfiguration
*
* @author Andy Clark, IBM
*
* @version $Id: XMLEntityResolver.java,v 1.2 2001/08/23 00:35:37 lehors Exp $
*/
public interface XMLEntityResolver {
//
// XMLEntityResolver methods
//
/**
* Resolves an external parsed entity. If the entity cannot be
* resolved, this method should return null.
*
* @param desc: contains a description for the type of entity
* (grammar, abstract schema) being sought.
* @throws XNIException Thrown on general error.
* @throws IOException Thrown if resolved entity stream cannot be
* opened or some other i/o error occurs.
*/
public XMLInputSource resolveEntity(XMLResourceDescription desc)
throws XNIException, IOException;
} // interface XMLEntityResolver
/**
* Location information.
* <p>In addition to storing information as to the physical location of
* a resource, provides a means for pointing to individual
* characters in the resource.</p>
*
* @author Andy Clark, IBM
*
* @version $Id: XMLLocator.java,v 1.2 2001/08/23 00:35:36 lehors Exp $
*/
public interface XMLLocator extends XMLResourceDescription {
//
// XMLLocator methods
//
/** Returns the line number. */
public int getLineNumber();
/** Returns the column number. */
public int getColumnNumber();
} // interface XMLLocator
Cheers,
Neil
Neil Graham
XML Parser Development
IBM Toronto Lab
Phone: 905-413-3519, T/L 969-3519
E-mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
