com.sun.msv.reader
Class GrammarReader

java.lang.Object
  |
  +--org.xml.sax.helpers.XMLFilterImpl
        |
        +--com.sun.msv.reader.GrammarReader

All Implemented Interfaces:

ContentHandler, DTDHandler, EntityResolver, ErrorHandler, IDContextProvider, ValidationContext, XMLFilter, XMLReader

Direct Known Subclasses:

RELAXReader, TREXBaseReader, XMLSchemaReader

public abstract class GrammarReader

extends XMLFilterImpl

implements IDContextProvider

base implementation of grammar readers that read grammar from SAX2 stream. GrammarReader class can be used as a ContentHandler that parses a grammar. So the typical usage is

 
 GrammarReader reader = new RELAXGrammarReader(...);
 XMLReader parser = .... // create a new XMLReader here
 
 parser.setContentHandler(reader);
 parser.parse(whateverYouLike);
 return reader.grammar;  // obtain parsed grammar.
 

Or you may want to use several pre-defined static "parse" methods for ease of use.

Author:

Kohsuke KAWAGUCHI

Inner Class Summary

static interface	GrammarReader.BackPatch
class	GrammarReader.BackwardReferenceMap memorizes what declarations are referenced from where.
class	GrammarReader.ChainPrefixResolver
static interface	GrammarReader.PrefixResolver namespace prefix to URI conversion map.

Field Summary

GrammarReader.BackwardReferenceMap	backwardReference keeps track of all backward references to every ReferenceExp.
static GrammarReader.PrefixResolver	basePrefixResolver The namespace prefix resolver that only resolves "xml" prefix.
GrammarReaderController	controller this object receives errors and warnings
static String	ERR_BAD_ATTRIBUTE_VALUE
static String	ERR_BAD_TYPE
static String	ERR_CHARACTERS
static String	ERR_CONFLICTING_ATTRIBUTES
static String	ERR_DATATYPE_ALREADY_DEFINED
static String	ERR_DISALLOWED_ATTRIBUTE
static String	ERR_ILLEGAL_FINAL_VALUE
static String	ERR_IO_EXCEPTION
static String	ERR_MALPLACED_ELEMENT
static String	ERR_MISSING_ATTRIBUTE
static String	ERR_MISSING_ATTRIBUTE_2
static String	ERR_MISSING_CHILD_EXPRESSION
static String	ERR_MISSING_CHILD_TYPE
static String	ERR_MISSING_TOPLEVEL
static String	ERR_MORE_THAN_ONE_CHILD_EXPRESSION
static String	ERR_MORE_THAN_ONE_CHILD_TYPE
static String	ERR_RECURSIVE_DATATYPE
static String	ERR_RECURSIVE_INCLUDE
static String	ERR_RUNAWAY_EXPRESSION
static String	ERR_SAX_EXCEPTION
static String	ERR_UNDEFINED_DATATYPE
static String	ERR_XMLPARSERFACTORY_EXCEPTION
boolean	hadError this flag is set to true if reportError method is called.
Locator	locator document Locator that is given by XML reader
javax.xml.parsers.SAXParserFactory	parserFactory Reader may create another SAXParser from this factory
ExpressionPool	pool this object must be used to create a new expression
GrammarReader.PrefixResolver	prefixResolver
static String	WRN_DEPRECATED_TYPENAME
static String	WRN_MAYBE_WRONG_NAMESPACE

Method Summary

void	addBackPatchJob(GrammarReader.BackPatch job)
String	combineURL(String baseURL, String relativeURL) converts the relative URL to the absolute one by using the specified base URL.
abstract State	createExpressionChildState(State parent, StartTagInfo tag) this method must be implemented by the derived class to create language-default expresion state.
void	detectUndefinedOnes(ReferenceContainer container, String errMsg) detects undefined ReferenceExp and reports it as an error.
void	endPrefixMapping(String prefix)
Datatype	getBackwardCompatibleType(String typeName) tries to obtain a DataType object by resolving obsolete names.
State	getCurrentState() gets current State object.
Locator	getDeclaredLocationOf(Object o)
abstract Grammar	getResultAsGrammar() gets the parsed AGM.
boolean	isNotation(String notationName) checks if a notation is declared with the specified name.
boolean	isUnparsedEntity(String entityName) checks if an unparsed entity is declared with the specified name.
boolean	onID(String uri, String local, Object token) this method is called when another ID is found to check whether this ID is already used or not.
void	onIDREF(String uri, String local, Object token) this method is called when an IDREF is found.
void	parse(InputSource source) parses a grammar from the specified source
void	parse(String source) parses a grammar from the specified source
void	popState() pops the previous state from the stack
void	pushState(State newState, State parentState, StartTagInfo startTag) pushs the current state into the stack and sets new one
void	reportError(Exception nestedException, String propertyName)
void	reportError(Exception nestedException, String propertyName, Object arg1)
void	reportError(Locator[] locs, String propertyName, Object[] args)
void	reportError(String propertyName)
void	reportError(String propertyName, Object arg1)
void	reportError(String propertyName, Object[] args, Exception nestedException, Locator[] errorLocations) reports an error to the controller
void	reportError(String propertyName, Object arg1, Object arg2)
void	reportError(String propertyName, Object arg1, Object arg2, Object arg3)
void	reportWarning(String propertyName, Object arg1)
void	reportWarning(String propertyName, Object[] args, Locator[] locations) reports a warning to the controller
void	reportWarning(String propertyName, Object arg1, Object arg2)
abstract Datatype	resolveDataType(String typeName) gets DataType object from type name.
InputSource	resolveLocation(State sourceState, String url) obtains InputSource for the specified url.
String	resolveNamespacePrefix(String prefix) Resolves a namespace prefix to the corresponding namespace URI.
void	setDeclaredLocationOf(Object o)
void	setDocumentLocator(Locator loc)
String[]	splitQName(String qName) calls processName method of NamespaceSupport.
void	startPrefixMapping(String prefix, String uri)
void	switchSource(State sourceState, String url, State newState) switchs InputSource to the specified URL and parses it by the specified state.

Methods inherited from class org.xml.sax.helpers.XMLFilterImpl

characters, endDocument, endElement, error, fatalError, getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getParent, getProperty, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setParent, setProperty, skippedEntity, startDocument, startElement, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

locator

public Locator locator

document Locator that is given by XML reader

controller

public final GrammarReaderController controller

this object receives errors and warnings

parserFactory

public final javax.xml.parsers.SAXParserFactory parserFactory

Reader may create another SAXParser from this factory

pool

public final ExpressionPool pool

this object must be used to create a new expression

basePrefixResolver

public static final GrammarReader.PrefixResolver basePrefixResolver

The namespace prefix resolver that only resolves "xml" prefix. This class should be used as the base resolver.

prefixResolver

public GrammarReader.PrefixResolver prefixResolver

backwardReference

public final GrammarReader.BackwardReferenceMap backwardReference

keeps track of all backward references to every ReferenceExp. this map should be used to report the source of error of undefined-something.

hadError

public boolean hadError

this flag is set to true if reportError method is called. Derived classes must check this flag to determine whether the parsing was successful or not.

ERR_MALPLACED_ELEMENT

public static final String ERR_MALPLACED_ELEMENT

ERR_IO_EXCEPTION

public static final String ERR_IO_EXCEPTION

ERR_SAX_EXCEPTION

public static final String ERR_SAX_EXCEPTION

ERR_XMLPARSERFACTORY_EXCEPTION

public static final String ERR_XMLPARSERFACTORY_EXCEPTION

ERR_CHARACTERS

public static final String ERR_CHARACTERS

ERR_DISALLOWED_ATTRIBUTE

public static final String ERR_DISALLOWED_ATTRIBUTE

ERR_MISSING_ATTRIBUTE

public static final String ERR_MISSING_ATTRIBUTE

ERR_BAD_ATTRIBUTE_VALUE

public static final String ERR_BAD_ATTRIBUTE_VALUE

ERR_MISSING_ATTRIBUTE_2

public static final String ERR_MISSING_ATTRIBUTE_2

ERR_CONFLICTING_ATTRIBUTES

public static final String ERR_CONFLICTING_ATTRIBUTES

ERR_RECURSIVE_INCLUDE

public static final String ERR_RECURSIVE_INCLUDE

ERR_UNDEFINED_DATATYPE

public static final String ERR_UNDEFINED_DATATYPE

ERR_DATATYPE_ALREADY_DEFINED

public static final String ERR_DATATYPE_ALREADY_DEFINED

ERR_MISSING_CHILD_EXPRESSION

public static final String ERR_MISSING_CHILD_EXPRESSION

ERR_MORE_THAN_ONE_CHILD_EXPRESSION

public static final String ERR_MORE_THAN_ONE_CHILD_EXPRESSION

ERR_MORE_THAN_ONE_CHILD_TYPE

public static final String ERR_MORE_THAN_ONE_CHILD_TYPE

ERR_MISSING_CHILD_TYPE

public static final String ERR_MISSING_CHILD_TYPE

ERR_ILLEGAL_FINAL_VALUE

public static final String ERR_ILLEGAL_FINAL_VALUE

ERR_RUNAWAY_EXPRESSION

public static final String ERR_RUNAWAY_EXPRESSION

ERR_MISSING_TOPLEVEL

public static final String ERR_MISSING_TOPLEVEL

WRN_MAYBE_WRONG_NAMESPACE

public static final String WRN_MAYBE_WRONG_NAMESPACE

WRN_DEPRECATED_TYPENAME

public static final String WRN_DEPRECATED_TYPENAME

ERR_BAD_TYPE

public static final String ERR_BAD_TYPE

ERR_RECURSIVE_DATATYPE

public static final String ERR_RECURSIVE_DATATYPE

Method Detail

getResultAsGrammar

public abstract Grammar getResultAsGrammar()

gets the parsed AGM. Should any error happens, this method returns null. derived classes should implement type-safe getGrammar method, along with this method.

startPrefixMapping

public void startPrefixMapping(String prefix,
                               String uri)
                        throws SAXException

Overrides:

startPrefixMapping in class XMLFilterImpl

endPrefixMapping

public void endPrefixMapping(String prefix)
                      throws SAXException

Overrides:

endPrefixMapping in class XMLFilterImpl

splitQName

public final String[] splitQName(String qName)

calls processName method of NamespaceSupport. Therefore this method returns null if it fails to process QName.

resolveDataType

public abstract Datatype resolveDataType(String typeName)

gets DataType object from type name. If undefined type name is specified, this method is responsible to report an error, and recover.

Parameters:

typeName - For RELAX, this is unqualified type name. For TREX, this is a QName.

getBackwardCompatibleType

public Datatype getBackwardCompatibleType(String typeName)

tries to obtain a DataType object by resolving obsolete names. this method is useful for backward compatibility purpose.

resolveLocation

public final InputSource resolveLocation(State sourceState,
                                         String url)

obtains InputSource for the specified url. Also this method allows GrammarReaderController to redirect or prohibit inclusion.

Parameters:

sourceState - The base URI of this state is used to resolve the resource.

Returns:

return null if an error occurs.

combineURL

public final String combineURL(String baseURL,
                               String relativeURL)

converts the relative URL to the absolute one by using the specified base URL.

switchSource

public void switchSource(State sourceState,
                         String url,
                         State newState)

switchs InputSource to the specified URL and parses it by the specified state. derived classes can use this method to realize semantics of 'include'.

Parameters:

sourceState - this state is used to resolve the URL.

newState - this state will parse top-level of new XML source. this state receives document element by its createChildState method.

parse

public final void parse(String source)

parses a grammar from the specified source

Overrides:

parse in class XMLFilterImpl

parse

public final void parse(InputSource source)

parses a grammar from the specified source

Overrides:

parse in class XMLFilterImpl

setDeclaredLocationOf

public void setDeclaredLocationOf(Object o)

getDeclaredLocationOf

public Locator getDeclaredLocationOf(Object o)

detectUndefinedOnes

public void detectUndefinedOnes(ReferenceContainer container,
                                String errMsg)

detects undefined ReferenceExp and reports it as an error. this method is used in the final wrap-up process of parsing.

pushState

public void pushState(State newState,
                      State parentState,
                      StartTagInfo startTag)

pushs the current state into the stack and sets new one

popState

public void popState()

pops the previous state from the stack

getCurrentState

public final State getCurrentState()

gets current State object.

createExpressionChildState

public abstract State createExpressionChildState(State parent,
                                                 StartTagInfo tag)

this method must be implemented by the derived class to create language-default expresion state.

Returns:

null if the start tag is an error.

setDocumentLocator

public void setDocumentLocator(Locator loc)

Overrides:

setDocumentLocator in class XMLFilterImpl

resolveNamespacePrefix

public String resolveNamespacePrefix(String prefix)

Description copied from interface: ValidationContext

Resolves a namespace prefix to the corresponding namespace URI. This method is used for validating QName, for example.

If the prefix is "" (empty string), it indicates unprefixed value. The callee should resolved it as if it sees an unprefixed element, rather than unprefixed attribute.

If the prefix is "xml", then the callee must resolve this prefix into "http://www.w3.org/XML/1998/namespace", as defined in the XML Namespace rec.

Specified by:

resolveNamespacePrefix in interface ValidationContext

Following copied from interface: org.relaxng.datatype.ValidationContext

Returns:

namespace URI of this prefix. If the specified prefix is not declared, the implementation must return null.

isUnparsedEntity

public boolean isUnparsedEntity(String entityName)

Description copied from interface: ValidationContext

checks if an unparsed entity is declared with the specified name.

Specified by:

isUnparsedEntity in interface ValidationContext

Following copied from interface: org.relaxng.datatype.ValidationContext

Returns:

true if DTD has an unparsed entity declaration for the specified name. false if otherwise.

isNotation

public boolean isNotation(String notationName)

Description copied from interface: ValidationContext

checks if a notation is declared with the specified name.

Specified by:

isNotation in interface ValidationContext

Following copied from interface: org.relaxng.datatype.ValidationContext

Returns:

true if DTD has a notation declaration with the specified name. false if otherwise.

onID

public boolean onID(String uri,
                    String local,
                    Object token)

Description copied from interface: IDContextProvider

this method is called when another ID is found to check whether this ID is already used or not. It is the callee's responsibility that stores ID and checks doubly defined ID.

Specified by:

onID in interface IDContextProvider

Following copied from interface: com.sun.msv.grammar.IDContextProvider

Parameters:

symbolSpaceName - token has to be unique within the same symbol space, but two tokens can have the same name if they reside in different symbol spaces.

Returns:

true if there is no preceding ID of the same name; false if this name is already declared as ID.

onIDREF

public void onIDREF(String uri,
                    String local,
                    Object token)

Description copied from interface: IDContextProvider

this method is called when an IDREF is found. It is the callee's responsibility to store it and checks the existance of corresponding IDs later. Note that due to the forward reference, it is not possible to perform this check when IDREF is found. It must be done separately after parsing the entire document.

Specified by:

onIDREF in interface IDContextProvider

addBackPatchJob

public void addBackPatchJob(GrammarReader.BackPatch job)

reportError

public final void reportError(String propertyName)

reportError

public final void reportError(String propertyName,
                              Object arg1)

reportError

public final void reportError(String propertyName,
                              Object arg1,
                              Object arg2)

reportError

public final void reportError(String propertyName,
                              Object arg1,
                              Object arg2,
                              Object arg3)

reportError

public final void reportError(Exception nestedException,
                              String propertyName)

reportError

public final void reportError(Exception nestedException,
                              String propertyName,
                              Object arg1)

reportError

public final void reportError(Locator[] locs,
                              String propertyName,
                              Object[] args)

reportWarning

public final void reportWarning(String propertyName,
                                Object arg1)

reportWarning

public final void reportWarning(String propertyName,
                                Object arg1,
                                Object arg2)

reportError

public final void reportError(String propertyName,
                              Object[] args,
                              Exception nestedException,
                              Locator[] errorLocations)

reports an error to the controller

reportWarning

public final void reportWarning(String propertyName,
                                Object[] args,
                                Locator[] locations)

reports a warning to the controller