A parser pool that enables caching of grammars. The caching parser pool is constructed with a specific symbol table and grammar pool that has already been populated with the grammars used by the application.

Once the caching parser pool is constructed, specific parser instances are created by calling the appropriate factory method on the parser pool.

Note

There is a performance penalty for using a caching parser pool due to thread safety. Access to the symbol table and grammar pool must be synchronized to ensure the safe operation of the symbol table and grammar pool.

Note

If performance is critical, then another mechanism needs to be used instead of the caching parser pool. One approach would be to create parser instances that do not share these structures. Instead, each instance would get its own copy to use while parsing. This avoids the synchronization overhead at the expense of more memory and the time required to copy the structures for each new parser instance. And even when a parser instance is re-used, there is a potential for a memory leak due to new symbols being added to the symbol table over time. In other words, always take caution to make sure that your application is thread-safe and avoids leaking memory.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static class	CachingParserPool.ShadowedGrammarPool Shadowed grammar pool.
public static class	CachingParserPool.SynchronizedGrammarPool Synchronized grammar pool.

Field Summary

Modifier and Type	Field and Description
public static final boolean	DEFAULT_SHADOW_GRAMMAR_POOL Default shadow grammar pool (false).
public static final boolean	DEFAULT_SHADOW_SYMBOL_TABLE Default shadow symbol table (false).
protected boolean	fShadowGrammarPool Shadow the grammar pool for new parser instances.
protected boolean	fShadowSymbolTable Shadow the symbol table for new parser instances.
protected XMLGrammarPool	fSynchronizedGrammarPool Grammar pool.
protected SymbolTable	fSynchronizedSymbolTable Symbol table.

Constructor Summary

Access	Constructor and Description
public	CachingParserPool() Default constructor.
public	CachingParserPool(SymbolTable The symbol table. symbolTable, XMLGrammarPool The grammar pool. grammarPool) Constructs a caching parser pool with the specified symbol table and grammar pool.

Method Summary

Modifier and Type	Method and Description
public DOMParser	createDOMParser() Creates a new DOM parser.
public SAXParser	createSAXParser() Deprecated as a consequence of `SAXParser` being deprecated. Creates a new SAX parser.
public SymbolTable	getSymbolTable() Returns the symbol table.
public XMLGrammarPool	getXMLGrammarPool() Returns the grammar pool.
public void	setShadowSymbolTable(boolean If true, new parser instances use shadow copies of the main symbol table and are not allowed to add new symbols to the main symbol table. New symbols are added to the shadow symbol table and are local to the parser instance. If false, new parser instances are allowed to add new symbols to the main symbol table. shadow) Sets whether new parser instance receive shadow copies of the main symbol table.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

DEFAULT_SHADOW_GRAMMAR_POOL	back to summary
public static final boolean DEFAULT_SHADOW_GRAMMAR_POOL Default shadow grammar pool (false).

DEFAULT_SHADOW_SYMBOL_TABLE	back to summary
public static final boolean DEFAULT_SHADOW_SYMBOL_TABLE Default shadow symbol table (false).

fShadowGrammarPool	back to summary
protected boolean fShadowGrammarPool Shadow the grammar pool for new parser instances. If true, new parser instances use shadow copies of the main grammar pool and are not allowed to add new grammars to the main grammar pool. New grammars are added to the shadow grammar pool and are local to the parser instance.

fShadowSymbolTable	back to summary
protected boolean fShadowSymbolTable Shadow the symbol table for new parser instances. If true, new parser instances use shadow copies of the main symbol table and are not allowed to add new symbols to the main symbol table. New symbols are added to the shadow symbol table and are local to the parser instance.

fSynchronizedGrammarPool	back to summary
protected XMLGrammarPool fSynchronizedGrammarPool Grammar pool. The grammar pool that the caching parser pool is constructed with is automatically wrapped in a synchronized version for thread-safety.

fSynchronizedSymbolTable	back to summary
protected SymbolTable fSynchronizedSymbolTable Symbol table. The symbol table that the caching parser pool is constructed with is automatically wrapped in a synchronized version for thread-safety.

Constructor Detail

CachingParserPool	back to summary
public CachingParserPool() Default constructor.

CachingParserPool	back to summary
public CachingParserPool(SymbolTable symbolTable, XMLGrammarPool grammarPool) Constructs a caching parser pool with the specified symbol table and grammar pool. Parameters symbolTable:SymbolTable The symbol table. grammarPool:XMLGrammarPool The grammar pool.

CachingParserPool

back to summary

public CachingParserPool(SymbolTable symbolTable, XMLGrammarPool grammarPool)

Constructs a caching parser pool with the specified symbol table and grammar pool.

Parameters

symbolTable:SymbolTable: The symbol table.
grammarPool:XMLGrammarPool: The grammar pool.

Method Detail

createDOMParser	back to summary
public DOMParser createDOMParser() Creates a new DOM parser.

createSAXParser	back to summary
public SAXParser createSAXParser() Deprecated as a consequence of `SAXParser` being deprecated. See corresponding docs for further information. Creates a new SAX parser.

getSymbolTable	back to summary
public SymbolTable getSymbolTable() Returns the symbol table.

getXMLGrammarPool	back to summary
public XMLGrammarPool getXMLGrammarPool() Returns the grammar pool.

setShadowSymbolTable	back to summary
public void setShadowSymbolTable(boolean shadow) Sets whether new parser instance receive shadow copies of the main symbol table. Parameters shadow:boolean If true, new parser instances use shadow copies of the main symbol table and are not allowed to add new symbols to the main symbol table. New symbols are added to the shadow symbol table and are local to the parser instance. If false, new parser instances are allowed to add new symbols to the main symbol table.

setShadowSymbolTable

back to summary

public void setShadowSymbolTable(boolean shadow)

Sets whether new parser instance receive shadow copies of the main symbol table.

Parameters

shadow:boolean: If true, new parser instances use shadow copies of the main symbol table and are not allowed to add new symbols to the main symbol table. New symbols are added to the shadow symbol table and are local to the parser instance. If false, new parser instances are allowed to add new symbols to the main symbol table.

org.apache.xerces.parsers back to summary

public final Class CachingParserPool.ShadowedGrammarPool

Class Inheritance

extends XMLGrammarPoolImpl

java.lang.Object
org.apache.xerces.util.XMLGrammarPoolImpl
org.apache.xerces.parsers.CachingParserPool.ShadowedGrammarPool

Shadowed grammar pool. This class is predicated on the existence of a concrete implementation; so using our own doesn't seem to bad an idea.

Authors: Andy Clark, IBM, Neil Graham, IBM

Field Summary

Modifier and Type	Field and Description
private XMLGrammarPool	fGrammarPool Main grammar pool.

Inherited from org.apache.xerces.util.XMLGrammarPoolImpl:: fGrammarCount fGrammars fPoolIsLocked TABLE_SIZE

Constructor Summary

Access	Constructor and Description
public	ShadowedGrammarPool(XMLGrammarPool grammarPool) Constructs a shadowed grammar pool.

Method Summary

Modifier and Type	Method and Description
public void	cacheGrammars(String The type of the grammars to be cached. grammarType, Grammar[] The Grammars that may be cached (unordered, Grammars previously given to the validator may be included). grammars) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.cacheGrammars. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars. Give the grammarPool the option of caching these grammars.
public boolean	containsGrammar(XMLGrammarDescription The description of the grammar. desc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.containsGrammar. Returns true if the grammar pool contains a grammar associated to the specified description.
public Grammar	getGrammar(XMLGrammarDescription The description of the grammar. desc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.getGrammar. Returns the grammar associated to the specified description.
public Grammar	Returns: Grammar corresponding to gDesc, or null if none exists. retrieveGrammar(XMLGrammarDescription Description of the grammar to be retrieved gDesc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveGrammar. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar. Retrieve a particular grammar.
public Grammar[]	Returns: The initial grammar set the validator may place in its "bucket" retrieveInitialGrammarSet(String Type of the grammars to be retrieved. grammarType) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveInitialGrammarSet. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet. Retrieve the initial set of grammars for the validator to work with.

Inherited from org.apache.xerces.util.XMLGrammarPoolImpl:: clear equals hashCode lockPool putGrammar removeGrammar unlockPool

Field Detail

fGrammarPool	back to summary
private XMLGrammarPool fGrammarPool Main grammar pool.

Constructor Detail

ShadowedGrammarPool	back to summary
public ShadowedGrammarPool(XMLGrammarPool grammarPool) Constructs a shadowed grammar pool.

Method Detail

cacheGrammars	back to summary
public void cacheGrammars(String grammarType, Grammar[] grammars) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.cacheGrammars. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars. Give the grammarPool the option of caching these grammars. This certainly must be synchronized. Parameters grammarType:String The type of the grammars to be cached. grammars:Grammar[] The Grammars that may be cached (unordered, Grammars previously given to the validator may be included).

cacheGrammars

back to summary

public void cacheGrammars(String grammarType, Grammar[] grammars)

Overrides org.apache.xerces.util.XMLGrammarPoolImpl.cacheGrammars.

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars.

Give the grammarPool the option of caching these grammars. This certainly must be synchronized.

Parameters

grammarType:String: The type of the grammars to be cached.
grammars:Grammar[]: The Grammars that may be cached (unordered, Grammars previously given to the validator may be included).

containsGrammar	back to summary
public boolean containsGrammar(XMLGrammarDescription desc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.containsGrammar. Returns true if the grammar pool contains a grammar associated to the specified description. Parameters desc:XMLGrammarDescription The description of the grammar.

containsGrammar

back to summary

public boolean containsGrammar(XMLGrammarDescription desc)

Overrides org.apache.xerces.util.XMLGrammarPoolImpl.containsGrammar.

Returns true if the grammar pool contains a grammar associated to the specified description.

Parameters

desc:XMLGrammarDescription: The description of the grammar.

getGrammar	back to summary
public Grammar getGrammar(XMLGrammarDescription desc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.getGrammar. Returns the grammar associated to the specified description. Parameters desc:XMLGrammarDescription The description of the grammar.

getGrammar

back to summary

public Grammar getGrammar(XMLGrammarDescription desc)

Overrides org.apache.xerces.util.XMLGrammarPoolImpl.getGrammar.

Returns the grammar associated to the specified description.

Parameters

desc:XMLGrammarDescription: The description of the grammar.

retrieveGrammar	back to summary
public Grammar retrieveGrammar(XMLGrammarDescription gDesc) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveGrammar. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar. Retrieve a particular grammar. REVISIT: does this need to be synchronized since it's just reading? Parameters gDesc:XMLGrammarDescription Description of the grammar to be retrieved Returns:Grammar Grammar corresponding to gDesc, or null if none exists.

retrieveGrammar

back to summary

public Grammar retrieveGrammar(XMLGrammarDescription gDesc)

Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveGrammar.

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar.

Retrieve a particular grammar. REVISIT: does this need to be synchronized since it's just reading?

Parameters

gDesc:XMLGrammarDescription: Description of the grammar to be retrieved

Returns:Grammar

Grammar corresponding to gDesc, or null if none exists.

retrieveInitialGrammarSet	back to summary
public Grammar[] retrieveInitialGrammarSet(String grammarType) Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveInitialGrammarSet. Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet. Retrieve the initial set of grammars for the validator to work with. REVISIT: does this need to be synchronized since it's just reading? Parameters grammarType:String Type of the grammars to be retrieved. Returns:Grammar[] The initial grammar set the validator may place in its "bucket"

retrieveInitialGrammarSet

back to summary

public Grammar[] retrieveInitialGrammarSet(String grammarType)

Overrides org.apache.xerces.util.XMLGrammarPoolImpl.retrieveInitialGrammarSet.

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet.

Retrieve the initial set of grammars for the validator to work with. REVISIT: does this need to be synchronized since it's just reading?

Parameters

grammarType:String: Type of the grammars to be retrieved.

Returns:Grammar[]

The initial grammar set the validator may place in its "bucket"

org.apache.xerces.parsers back to summary

public final Class CachingParserPool.SynchronizedGrammarPool

Class Inheritance

extends Object
implements XMLGrammarPool

java.lang.Object
org.apache.xerces.parsers.CachingParserPool.SynchronizedGrammarPool

All Implemented Interfaces

org.apache.xerces.xni.grammars.XMLGrammarPool

Synchronized grammar pool.

Author: Andy Clark, IBM

Field Summary

Modifier and Type	Field and Description
private XMLGrammarPool	fGrammarPool Main grammar pool.

Constructor Summary

Access	Constructor and Description
public	SynchronizedGrammarPool(XMLGrammarPool grammarPool) Constructs a synchronized grammar pool.

Method Summary

Modifier and Type	Method and Description
public void	cacheGrammars(String the type of the grammars being returned; grammarType, Grammar[] an array containing the set of grammars being returned; order is not significant. grammars) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars. return the final set of grammars that the validator ended up with.
public void	clear() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.clear. clear the grammar pool
public void	lockPool() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.lockPool. lock the grammar pool
public Grammar	retrieveGrammar(XMLGrammarDescription The description of the Grammar being requested. gDesc) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar. This method requests that the application retrieve a grammar corresponding to the given GrammarIdentifier from its cache.
public Grammar[]	retrieveInitialGrammarSet(String the type of the grammar, from the `org.apache.xerces.xni.grammars.Grammar` interface. grammarType) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet. retrieve the initial known set of grammars.
public void	unlockPool() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.unlockPool. unlock the grammar pool

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

fGrammarPool	back to summary
private XMLGrammarPool fGrammarPool Main grammar pool.

Constructor Detail

SynchronizedGrammarPool	back to summary
public SynchronizedGrammarPool(XMLGrammarPool grammarPool) Constructs a synchronized grammar pool.

Method Detail

cacheGrammars	back to summary
public void cacheGrammars(String grammarType, Grammar[] grammars) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars. Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars. 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. Parameters grammarType:String the type of the grammars being returned; grammars:Grammar[] an array containing the set of grammars being returned; order is not significant.

cacheGrammars

back to summary

public void cacheGrammars(String grammarType, Grammar[] grammars)

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars.

Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.cacheGrammars.

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.

Parameters

grammarType:String: the type of the grammars being returned;
grammars:Grammar[]: an array containing the set of grammars being returned; order is not significant.

clear	back to summary
public void clear() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.clear. clear the grammar pool

clear

back to summary

public void clear()

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.clear.

clear the grammar pool

lockPool	back to summary
public void lockPool() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.lockPool. lock the grammar pool

lockPool

back to summary

public void lockPool()

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.lockPool.

lock the grammar pool

retrieveGrammar	back to summary
public Grammar retrieveGrammar(XMLGrammarDescription gDesc) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar. Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar. This method requests that the application retrieve a grammar corresponding to the given GrammarIdentifier 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; this may result in infinite recursions. Parameters gDesc:XMLGrammarDescription The description of the Grammar being requested. Returns:Grammar the Grammar corresponding to this description or null if no such Grammar is known.

retrieveGrammar

back to summary

public Grammar retrieveGrammar(XMLGrammarDescription gDesc)

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar.

Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveGrammar.

This method requests that the application retrieve a grammar corresponding to the given GrammarIdentifier 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; this may result in infinite recursions.

Parameters

gDesc:XMLGrammarDescription: The description of the Grammar being requested.

Returns:Grammar

the Grammar corresponding to this description or null if no such Grammar is known.

retrieveInitialGrammarSet back to summary

retrieveInitialGrammarSet	back to summary
public Grammar[] retrieveInitialGrammarSet(String grammarType) Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet. Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet. 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. Parameters grammarType:String the type of the grammar, from the `org.apache.xerces.xni.grammars.Grammar` interface. Returns:Grammar[] the set of grammars the validator may put in its "bucket"

public Grammar[] retrieveInitialGrammarSet(String grammarType)

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet.

Doc from org.apache.xerces.xni.grammars.XMLGrammarPool.retrieveInitialGrammarSet.

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.

Parameters

grammarType:String: the type of the grammar, from the org.apache.xerces.xni.grammars.Grammar interface.

Returns:Grammar[]

the set of grammars the validator may put in its "bucket"

unlockPool	back to summary
public void unlockPool() Implements org.apache.xerces.xni.grammars.XMLGrammarPool.unlockPool. unlock the grammar pool

unlockPool

back to summary

public void unlockPool()

Implements org.apache.xerces.xni.grammars.XMLGrammarPool.unlockPool.

unlock the grammar pool

public Class CachingParserPool

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class CachingParserPool.ShadowedGrammarPool

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Class CachingParserPool.SynchronizedGrammarPool

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail