[PROPOSAL - XNI Grammars] add grammar description interfaces to xni.grammars

[sa...@ca.ibm.com]

Hi all,

The XMLGrammarDescription interface in the org.apache.xerces.xni.grammars
package is used to describe a grammar. It's especially useful when
XMLEntityResolver is called for a grammar file, where XMLGrammarDescription
can provide extra information other than just the location of that file.

Xerces currently supports 2 kinds of grammars: DTD and XML Schema, and
there are 2 kinds of grammar description classes. By casting the grammar
description to either of these classes, the user can get information
specific to that grammar type. (The namespace of a schema document, for
example.) Unfortunately, these 2 classes are in the implementation
packages. (Because they were experimental.)

So I would like to propose to add the following 2 interfaces to the
xni.grammars package (please refer to
org.apache.xerces.impl.dtd.XMLDTDDescription and
org.apache.xerces.impl.xs.XSDDescription for more information). With these
2 interfaces, people can cast the grammar description to the proper
interface, instead of having to deal with an implementation class.

public interface XMLDTDDescription extends XMLGrammarDescription {

    // the root element name
    public String getRootName();

} // interface XMLDTDDescription

public interface XMLSchemaDescription extends XMLGrammarDescription {

    // used to indicate what triggered the call
    /**
     * Indicate that the current schema document is <include>d by another
     * schema document.
     */
    public final static short CONTEXT_INCLUDE   = 0;
    /**
     * Indicate that the current schema document is <redefine>d by another
     * schema document.
     */
    public final static short CONTEXT_REDEFINE  = 1;
    /**
     * Indicate that the current schema document is <import>ed by another
     * schema document.
     */
    public final static short CONTEXT_IMPORT    = 2;
    /**
     * Indicate that the current schema document is being preparsed.
     */
    public final static short CONTEXT_PREPARSE  = 3;
    /**
     * Indicate that the parse of the current schema document is triggered
     * by xsi:schemaLocation/noNamespaceSchemaLocation attribute(s) in the
     * instance document. This value is only used if we don't defer the
loading
     * of schema documents.
     */
    public final static short CONTEXT_INSTANCE  = 4;
    /**
     * Indicate that the parse of the current schema document is triggered
by
     * the occurrence of an element whose namespace is the target namespace
     * of this schema document. This value is only used if we do defer the
     * loading of schema documents until a component from that namespace is
     * referenced from the instance.
     */
    public final static short CONTEXT_ELEMENT   = 5;
    /**
     * Indicate that the parse of the current schema document is triggered
by
     * the occurrence of an attribute whose namespace is the target
namespace
     * of this schema document. This value is only used if we do defer the
     * loading of schema documents until a component from that namespace is
     * referenced from the instance.
     */
    public final static short CONTEXT_ATTRIBUTE = 6;
    /**
     * Indicate that the parse of the current schema document is triggered
by
     * the occurrence of an "xsi:type" attribute, whose value (a QName) has
     * the target namespace of this schema document as its namespace.
     * This value is only used if we do defer the loading of schema
documents
     * until a component from that namespace is referenced from the
instance.
     */
    public final static short CONTEXT_XSITYPE   = 7;

    // how the grammar is referenced (one of the above constants)
    public short getContextType();

    // the target namespace of the grammar
    public String getTargetNamespace();

    // all location hints for this grammar
    public String[] getLocationHints();

    // the name of the element/attribute, or the value of "xsi:type"
    public QName getTriggeringComponent();

    // if it's referenced by an attribute or an xsi:type
    // the name of the element that encloses the attribute or xsi:type
    public QName getEnclosingElementName();

    // all attributes on the (enclosing) element
    public XMLAttributes getAttributes();

} // XMLSchemaDescription

Thoughts?

Thanks,
Sandy Gao
Software Developer, IBM Canada
(1-905) 413-3255
sandygao@ca.ibm.com


---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-j-user-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-j-user-help@xml.apache.org