com.ibm.xml.framework
Interface XMLEntityHandler

public abstract interface XMLEntityHandler

This is the interface used for entity events.

Version:

Revision: 47 1.8 src/com/ibm/xml/framework/XMLEntityHandler.java, parser, xml4j2, xml4j2_0_0

See Also:

XMLParser

Method Summary

void	addRecognizer(XMLDeclRecognizer recognizer) Adds a recognizer.
XMLReader	createReader(InputSource source, boolean xmlDecl) Creates a parser reader object from the given input source.
void	endInputSource(InputSource inputSource) End of an input source.
int	expandSystemId(int systemId) Fully expands a given system identified.
EntityResolver	getEntityResolver() Returns the resolver used to resolve external entities.
void	reset(ParserState parserState) Resets the entity handler, usually in response to a new call to XMLParser.parse.
InputSource	resolveEntity(int publicId, int systemId) Performs the entity resolution.
void	setEntityResolver(EntityResolver resolver) Sets the resolver used to resolve external entities.
void	startInputSource(InputSource inputSource) Start of an input source.

Method Detail

reset

public void reset(ParserState parserState)

Resets the entity handler, usually in response to a new call to XMLParser.parse.

Parameters:

parserState - The parser state.

addRecognizer

public void addRecognizer(XMLDeclRecognizer recognizer)

Adds a recognizer.

Parameters:

recognizer - The XML recognizer to add.

setEntityResolver

public void setEntityResolver(EntityResolver resolver)

Sets the resolver used to resolve external entities. The EntityResolver interface supports resolution of public and system identifiers. If the resolver set is also of type com.ibm.xml.framework.Catalog, then catalogs can be loaded in a general manner by calling XMLParser.loadCatalog().

Parameters:

resolver - The new entity resolver. Passing a null value will uninstall the currently installed resolver.

See Also:

Catalog, XMLParser.loadCatalog(org.xml.sax.InputSource)

getEntityResolver

public EntityResolver getEntityResolver()

Returns the resolver used to resolve external entities.

Returns:

The resolver.

See Also:

setEntityResolver(org.xml.sax.EntityResolver)

resolveEntity

public InputSource resolveEntity(int publicId,
                                 int systemId)
                          throws java.lang.Exception

Performs the entity resolution. The most common way to resolve entities is to get the strings represented by the publicId and systemId indexes and ask the installed EntityResolver to resolve the entities.

Parameters:

publidId - The index of the public identifier string in the parser StringPool. If this value is -1, then a system identifier alias is requested; else the system identifier represents the default entity resolution if no public identifier mapping is possible.

systemId - The index of the system identifier string in the parser StringPool.

Returns:

Returns an InputSource of the resolved entity or null if no resolution is possible.

Throws:

java.lang.Exception - If entity resolution fails, this method can throw an exception.

See Also:

getEntityResolver(), StringPool.toString(int)

expandSystemId

public int expandSystemId(int systemId)

Fully expands a given system identified. The system identifier string to be resolved and the fully expanded system identifier string are stored in the parser StringPool.

The following method expands a system identifier given as a java.lang.String.

     public String expandSystemId(XMLParser parser, String systemId) throws Exception {
         StringPool pool = parser.getParserState().getStringPool();

         // expand entity
         int oldIndex = pool.addString(systemId);
         int newIndex = parser.getEntityHandler().expandSystemId(oldIndex);
         systemId = pool.toIndex(newIndex);

         // release string pool resources
         pool.releaseString(oldIndex);
         pool.releaseString(newIndex);

         // return expanded system id
         return systemId;
         }
 

Parameters:

systemId - The index of the system identifier string in the parser StringPool.

Returns:

Returns the index in the StringPool that holds the expanded system identifier. If the given system identifier is already fully expanded, this method can return the original systemId value.

See Also:

StringPool.toString(int)

createReader

public XMLReader createReader(InputSource source,
                              boolean xmlDecl)
                       throws java.lang.Exception

Creates a parser reader object from the given input source.

This is the point in the default implementation where relative system identifiers are expanded. For example, if the current source URI is "http://host/path/file.xml" and the specified input source system identifier is "dtd/file.dtd", then the system identifier, if not already opened, will be set to "http://host/path/dtd/file.dtd".

Parameters:

source - The input source.

xmlDecl - True if the source represents an XML decl.

Returns:

Returns a parser reader object.

Throws:

java.lang.Exception - Throws exception on error.

startInputSource

public void startInputSource(InputSource inputSource)

Start of an input source.

Parameters:

inputSource - The input source that is starting.

endInputSource

public void endInputSource(InputSource inputSource)

End of an input source.

Parameters:

inputSource - The input source that is ended.