public class

XMLEntityManager

extends Object
implements XMLComponent XMLEntityResolver
java.lang.Object
   ↳ org.apache.xerces.impl.XMLEntityManager

Class Overview

The entity manager handles the registration of general and parameter entities; resolves entities; and starts entities. The entity manager is a central component in a standard parser configuration and this class works directly with the entity scanner to manage the underlying xni.

This component requires the following features and properties from the component manager that uses it:

  • http://xml.org/sax/features/validation
  • http://xml.org/sax/features/external-general-entities
  • http://xml.org/sax/features/external-parameter-entities
  • http://apache.org/xml/features/allow-java-encodings
  • http://apache.org/xml/properties/internal/symbol-table
  • http://apache.org/xml/properties/internal/error-reporter
  • http://apache.org/xml/properties/internal/entity-resolver
@xerces.internal

Summary

Nested Classes
class XMLEntityManager.Entity Entity information.@xerces.internal 
class XMLEntityManager.ExternalEntity External entity.@xerces.internal 
class XMLEntityManager.InternalEntity Internal entity.@xerces.internal 
class XMLEntityManager.RewindableInputStream This class wraps the byte inputstreams we're presented with. 
class XMLEntityManager.ScannedEntity Entity state.@xerces.internal 
Constants
String ALLOW_JAVA_ENCODINGS Feature identifier: allow Java encodings.
String BUFFER_SIZE property identifier: buffer size.
int DEFAULT_BUFFER_SIZE Default buffer size (2048).
int DEFAULT_INTERNAL_BUFFER_SIZE Default internal entity buffer size (512).
int DEFAULT_XMLDECL_BUFFER_SIZE Default buffer size before we've finished with the XMLDecl:
String ENTITY_RESOLVER Property identifier: entity resolver.
String ERROR_REPORTER Property identifier: error reporter.
String EXTERNAL_GENERAL_ENTITIES Feature identifier: external general entities.
String EXTERNAL_PARAMETER_ENTITIES Feature identifier: external parameter entities.
String PARSER_SETTINGS
String SECURITY_MANAGER property identifier: security manager.
String STANDARD_URI_CONFORMANT Feature identifier: standard uri conformant
String SYMBOL_TABLE Property identifier: symbol table.
String VALIDATION Feature identifier: validation.
String VALIDATION_MANAGER
String WARN_ON_DUPLICATE_ENTITYDEF Feature identifier: warn on duplicate EntityDef
Fields
protected boolean fAllowJavaEncodings Allow Java encoding names.
protected int fBufferSize Buffer size.
protected XMLEntityManager.ScannedEntity fCurrentEntity Current entity.
protected Hashtable fDeclaredEntities Shared declared entities.
protected Hashtable fEntities Entities.
protected int fEntityExpansionCount
protected int fEntityExpansionLimit
protected XMLEntityHandler fEntityHandler Entity handler.
protected XMLEntityResolver fEntityResolver Entity resolver.
protected XMLEntityScanner fEntityScanner Current entity scanner.
protected Stack fEntityStack Entity stack.
protected XMLErrorReporter fErrorReporter Error reporter.
protected boolean fExternalGeneralEntities External general entities.
protected boolean fExternalParameterEntities External parameter entities.
protected boolean fInExternalSubset
protected Stack fReaderStack
protected SecurityManager fSecurityManager
protected boolean fStandalone True if the document entity is standalone.
protected boolean fStrictURI standard uri conformant (strict uri).
protected SymbolTable fSymbolTable Symbol table.
protected boolean fValidation Validation.
protected ValidationManager fValidationManager Validation manager.
protected boolean fWarnDuplicateEntityDef warn on duplicate Entity declaration.
protected XMLEntityScanner fXML10EntityScanner XML 1.0 entity scanner.
protected XMLEntityScanner fXML11EntityScanner XML 1.1 entity scanner.
Public Constructors
XMLEntityManager()
Default constructor.
XMLEntityManager(XMLEntityManager entityManager)
Constructs an entity manager that shares the specified entity declarations during each parse.
Public Methods
static void absolutizeAgainstUserDir(URI uri)
Absolutizes a URI using the current value of the "user.dir" property as the base URI.
void addExternalEntity(String name, String publicId, String literalSystemId, String baseSystemId)
Adds an external entity declaration.
void addInternalEntity(String name, String text)
Adds an internal entity declaration.
void addUnparsedEntity(String name, String publicId, String systemId, String baseSystemId, String notation)
Adds an unparsed entity declaration.
void closeReaders()
Close all opened InputStreams and Readers opened by this parser.
static OutputStream createOutputStream(String uri)
void endExternalSubset()
static String expandSystemId(String systemId, String baseSystemId, boolean strict)
Expands a system id and returns the system id as a URI, if it can be expanded.
XMLEntityManager.ScannedEntity getCurrentEntity()
XMLResourceIdentifier getCurrentResourceIdentifier()
XMLEntityScanner getEntityScanner()
Returns the entity scanner.
Boolean getFeatureDefault(String featureId)
Returns the default state for a feature, or null if this component does not want to report a default value for this feature.
Object getPropertyDefault(String propertyId)
Returns the default state for a property, or null if this component does not want to report a default value for this property.
String[] getRecognizedFeatures()
Returns a list of feature identifiers that are recognized by this component.
String[] getRecognizedProperties()
Returns a list of property identifiers that are recognized by this component.
boolean isDeclaredEntity(String entityName)
Checks whether an entity given by name is declared.
boolean isEntityDeclInExternalSubset(String entityName)
Checks whether the declaration of an entity given by name is // in the external subset.
boolean isExternalEntity(String entityName)
Checks whether an entity given by name is external.
boolean isStandalone()
Returns true if the document entity is standalone.
boolean isUnparsedEntity(String entityName)
Checks whether an entity given by name is unparsed.
void reset(XMLComponentManager componentManager)
Resets the component.
void reset()
XMLInputSource resolveEntity(XMLResourceIdentifier resourceIdentifier)
Resolves the specified public and system identifiers.
void setEntityHandler(XMLEntityHandler entityHandler)
Sets the entity handler.
void setFeature(String featureId, boolean state)
Sets the state of a feature.
static void setInstanceFollowRedirects(HttpURLConnection urlCon, boolean followRedirects)
Attempt to set whether redirects will be followed for an HttpURLConnection.
void setProperty(String propertyId, Object value)
Sets the value of a property.
void setScannerVersion(short version)
void setStandalone(boolean standalone)
Sets whether the document entity is standalone.
String setupCurrentEntity(String name, XMLInputSource xmlInputSource, boolean literal, boolean isExternal)
This method uses the passed-in XMLInputSource to make fCurrentEntity usable for reading.
void startDTDEntity(XMLInputSource xmlInputSource)
Starts the DTD entity.
void startDocumentEntity(XMLInputSource xmlInputSource)
Starts the document entity.
void startEntity(String name, XMLInputSource xmlInputSource, boolean literal, boolean isExternal)
Starts an entity.
void startEntity(String entityName, boolean literal)
Starts a named entity.
void startExternalSubset()
Protected Methods
Reader createReader(InputStream inputStream, String encoding, Boolean isBigEndian)
Creates a reader capable of reading the given input stream in the specified encoding.
static String fixURI(String str)
Fixes a platform dependent filename to standard URI form.
Object[] getEncodingName(byte[] b4, int count)
Returns the IANA encoding name that is auto-detected from the bytes specified, with the endian-ness of that encoding where appropriate.
[Expand]
Inherited Methods
From class java.lang.Object
From interface org.apache.xerces.xni.parser.XMLComponent
From interface org.apache.xerces.xni.parser.XMLEntityResolver

Constants

protected static final String ALLOW_JAVA_ENCODINGS

Feature identifier: allow Java encodings.

Constant Value: "http://apache.org/xml/features/allow-java-encodings"

protected static final String BUFFER_SIZE

property identifier: buffer size.

Constant Value: "http://apache.org/xml/properties/input-buffer-size"

public static final int DEFAULT_BUFFER_SIZE

Default buffer size (2048).

Constant Value: 2048 (0x00000800)

public static final int DEFAULT_INTERNAL_BUFFER_SIZE

Default internal entity buffer size (512).

Constant Value: 512 (0x00000200)

public static final int DEFAULT_XMLDECL_BUFFER_SIZE

Default buffer size before we've finished with the XMLDecl:

Constant Value: 64 (0x00000040)

protected static final String ENTITY_RESOLVER

Property identifier: entity resolver.

Constant Value: "http://apache.org/xml/properties/internal/entity-resolver"

protected static final String ERROR_REPORTER

Property identifier: error reporter.

Constant Value: "http://apache.org/xml/properties/internal/error-reporter"

protected static final String EXTERNAL_GENERAL_ENTITIES

Feature identifier: external general entities.

Constant Value: "http://xml.org/sax/features/external-general-entities"

protected static final String EXTERNAL_PARAMETER_ENTITIES

Feature identifier: external parameter entities.

Constant Value: "http://xml.org/sax/features/external-parameter-entities"

protected static final String PARSER_SETTINGS

Constant Value: "http://apache.org/xml/features/internal/parser-settings"

protected static final String SECURITY_MANAGER

property identifier: security manager.

Constant Value: "http://apache.org/xml/properties/security-manager"

protected static final String STANDARD_URI_CONFORMANT

Feature identifier: standard uri conformant

Constant Value: "http://apache.org/xml/features/standard-uri-conformant"

protected static final String SYMBOL_TABLE

Property identifier: symbol table.

Constant Value: "http://apache.org/xml/properties/internal/symbol-table"

protected static final String VALIDATION

Feature identifier: validation.

Constant Value: "http://xml.org/sax/features/validation"

protected static final String VALIDATION_MANAGER

Constant Value: "http://apache.org/xml/properties/internal/validation-manager"

protected static final String WARN_ON_DUPLICATE_ENTITYDEF

Feature identifier: warn on duplicate EntityDef

Constant Value: "http://apache.org/xml/features/warn-on-duplicate-entitydef"

Fields

protected boolean fAllowJavaEncodings

Allow Java encoding names. This feature identifier is: http://apache.org/xml/features/allow-java-encodings

protected int fBufferSize

Buffer size. We get this value from a property. The default size is used if the input buffer size property is not specified. REVISIT: do we need a property for internal entity buffer size?

protected XMLEntityManager.ScannedEntity fCurrentEntity

Current entity.

protected Hashtable fDeclaredEntities

Shared declared entities.

protected Hashtable fEntities

Entities.

protected int fEntityExpansionCount

protected int fEntityExpansionLimit

protected XMLEntityHandler fEntityHandler

Entity handler.

protected XMLEntityResolver fEntityResolver

Entity resolver. This property identifier is: http://apache.org/xml/properties/internal/entity-resolver

protected XMLEntityScanner fEntityScanner

Current entity scanner.

protected Stack fEntityStack

Entity stack.

protected XMLErrorReporter fErrorReporter

Error reporter. This property identifier is: http://apache.org/xml/properties/internal/error-reporter

protected boolean fExternalGeneralEntities

External general entities. This feature identifier is: http://xml.org/sax/features/external-general-entities

protected boolean fExternalParameterEntities

External parameter entities. This feature identifier is: http://xml.org/sax/features/external-parameter-entities

protected boolean fInExternalSubset

protected Stack fReaderStack

protected SecurityManager fSecurityManager

protected boolean fStandalone

True if the document entity is standalone. This should really only be set by the document source (e.g. XMLDocumentScanner).

protected boolean fStrictURI

standard uri conformant (strict uri). http://apache.org/xml/features/standard-uri-conformant

protected SymbolTable fSymbolTable

Symbol table. This property identifier is: http://apache.org/xml/properties/internal/symbol-table

protected boolean fValidation

Validation. This feature identifier is: http://xml.org/sax/features/validation

protected ValidationManager fValidationManager

Validation manager. This property identifier is: http://apache.org/xml/properties/internal/validation-manager

protected boolean fWarnDuplicateEntityDef

warn on duplicate Entity declaration. http://apache.org/xml/features/warn-on-duplicate-entitydef

protected XMLEntityScanner fXML10EntityScanner

XML 1.0 entity scanner.

protected XMLEntityScanner fXML11EntityScanner

XML 1.1 entity scanner.

Public Constructors

public XMLEntityManager ()

Default constructor.

public XMLEntityManager (XMLEntityManager entityManager)

Constructs an entity manager that shares the specified entity declarations during each parse.

REVISIT: We might want to think about the "right" way to expose the list of declared entities. For now, the knowledge how to access the entity declarations is implicit.

Public Methods

public static void absolutizeAgainstUserDir (URI uri)

Absolutizes a URI using the current value of the "user.dir" property as the base URI. If the URI is already absolute, this is a no-op.

Parameters
uri the URI to absolutize

public void addExternalEntity (String name, String publicId, String literalSystemId, String baseSystemId)

Adds an external entity declaration.

Note: This method ignores subsequent entity declarations.

Note: The name should be a unique symbol. The SymbolTable can be used for this purpose.

Parameters
name The name of the entity.
publicId The public identifier of the entity.
literalSystemId The system identifier of the entity.
baseSystemId The base system identifier of the entity. This is the system identifier of the entity where the entity being added and is used to expand the system identifier when the system identifier is a relative URI. When null the system identifier of the first external entity on the stack is used instead.
Throws
IOException
See Also

public void addInternalEntity (String name, String text)

Adds an internal entity declaration.

Note: This method ignores subsequent entity declarations.

Note: The name should be a unique symbol. The SymbolTable can be used for this purpose.

Parameters
name The name of the entity.
text The text of the entity.
See Also

public void addUnparsedEntity (String name, String publicId, String systemId, String baseSystemId, String notation)

Adds an unparsed entity declaration.

Note: This method ignores subsequent entity declarations.

Note: The name should be a unique symbol. The SymbolTable can be used for this purpose.

Parameters
name The name of the entity.
publicId The public identifier of the entity.
systemId The system identifier of the entity.
notation The name of the notation.
See Also

public void closeReaders ()

Close all opened InputStreams and Readers opened by this parser.

public static OutputStream createOutputStream (String uri)

Throws
IOException

public void endExternalSubset ()

public static String expandSystemId (String systemId, String baseSystemId, boolean strict)

Expands a system id and returns the system id as a URI, if it can be expanded. A return value of null means that the identifier is already expanded. An exception thrown indicates a failure to expand the id.

Parameters
systemId The systemId to be expanded.
Returns
  • Returns the URI string representing the expanded system identifier. A null value indicates that the given system identifier is already expanded.

public XMLEntityManager.ScannedEntity getCurrentEntity ()

public XMLResourceIdentifier getCurrentResourceIdentifier ()

public XMLEntityScanner getEntityScanner ()

Returns the entity scanner.

public Boolean getFeatureDefault (String featureId)

Returns the default state for a feature, or null if this component does not want to report a default value for this feature.

Parameters
featureId The feature identifier.

public Object getPropertyDefault (String propertyId)

Returns the default state for a property, or null if this component does not want to report a default value for this property.

Parameters
propertyId The property identifier.

public String[] getRecognizedFeatures ()

Returns a list of feature identifiers that are recognized by this component. This method may return null if no features are recognized by this component.

public String[] getRecognizedProperties ()

Returns a list of property identifiers that are recognized by this component. This method may return null if no properties are recognized by this component.

public boolean isDeclaredEntity (String entityName)

Checks whether an entity given by name is declared.

Parameters
entityName The name of the entity to check.
Returns
  • True if the entity is declared, false otherwise.

public boolean isEntityDeclInExternalSubset (String entityName)

Checks whether the declaration of an entity given by name is // in the external subset.

Parameters
entityName The name of the entity to check.
Returns
  • True if the entity was declared in the external subset, false otherwise (including when the entity is not declared).

public boolean isExternalEntity (String entityName)

Checks whether an entity given by name is external.

Parameters
entityName The name of the entity to check.
Returns
  • True if the entity is external, false otherwise (including when the entity is not declared).

public boolean isStandalone ()

Returns true if the document entity is standalone.

public boolean isUnparsedEntity (String entityName)

Checks whether an entity given by name is unparsed.

Parameters
entityName The name of the entity to check.
Returns
  • True if the entity is unparsed, false otherwise (including when the entity is not declared).

public void reset (XMLComponentManager componentManager)

Resets the component. The component can query the component manager about any features and properties that affect the operation of the component.

Parameters
componentManager The component manager.
Throws
Thrown by component on initialization error. For example, if a feature or property is required for the operation of the component, the component manager may throw a SAXNotRecognizedException or a SAXNotSupportedException.
XMLConfigurationException

public void reset ()

public XMLInputSource resolveEntity (XMLResourceIdentifier resourceIdentifier)

Resolves the specified public and system identifiers. This method first attempts to resolve the entity based on the EntityResolver registered by the application. If no entity resolver is registered or if the registered entity handler is unable to resolve the entity, then default entity resolution will occur.

Parameters
resourceIdentifier The XMLResourceIdentifier for the resource to resolve.
Returns
  • Returns an input source that wraps the resolved entity. This method will never return null.
Throws
IOException Thrown on i/o error.
XNIException Thrown by entity resolver to signal an error.

public void setEntityHandler (XMLEntityHandler entityHandler)

Sets the entity handler. When an entity starts and ends, the entity handler is notified of the change.

Parameters
entityHandler The new entity handler.

public void setFeature (String featureId, boolean state)

Sets the state of a feature. This method is called by the component manager any time after reset when a feature changes state.

Note: Components should silently ignore features that do not affect the operation of the component.

Parameters
featureId The feature identifier.
state The state of the feature.
Throws
The component should not throw this exception.
The component should not throw this exception.
XMLConfigurationException

public static void setInstanceFollowRedirects (HttpURLConnection urlCon, boolean followRedirects)

Attempt to set whether redirects will be followed for an HttpURLConnection. This may fail on earlier JDKs which do not support setting this preference.

public void setProperty (String propertyId, Object value)

Sets the value of a property. This method is called by the component manager any time after reset when a property changes value.

Note: Components should silently ignore properties that do not affect the operation of the component.

Parameters
propertyId The property identifier.
value The value of the property.
Throws
The component should not throw this exception.
The component should not throw this exception.
XMLConfigurationException

public void setScannerVersion (short version)

public void setStandalone (boolean standalone)

Sets whether the document entity is standalone.

Parameters
standalone True if document entity is standalone.

public String setupCurrentEntity (String name, XMLInputSource xmlInputSource, boolean literal, boolean isExternal)

This method uses the passed-in XMLInputSource to make fCurrentEntity usable for reading.

Parameters
name name of the entity (XML is it's the document entity)
xmlInputSource the input source, with sufficient information to begin scanning characters.
literal True if this entity is started within a literal value.
isExternal whether this entity should be treated as an internal or external entity.
Returns
  • the encoding of the new entity or null if a character stream was employed
Throws
IOException if anything can't be read XNIException If any parser-specific goes wrong.
XNIException

public void startDTDEntity (XMLInputSource xmlInputSource)

Starts the DTD entity. The DTD entity has the "[dtd]" pseudo-name.

Parameters
xmlInputSource The input source of the DTD entity.
Throws
IOException Thrown on i/o error.
XNIException Thrown by entity handler to signal an error.

public void startDocumentEntity (XMLInputSource xmlInputSource)

Starts the document entity. The document entity has the "[xml]" pseudo-name.

Parameters
xmlInputSource The input source of the document entity.
Throws
IOException Thrown on i/o error.
XNIException Thrown by entity handler to signal an error.

public void startEntity (String name, XMLInputSource xmlInputSource, boolean literal, boolean isExternal)

Starts an entity.

This method can be used to insert an application defined XML entity stream into the parsing stream.

Parameters
name The name of the entity.
xmlInputSource The input source of the entity.
literal True if this entity is started within a literal value.
isExternal whether this entity should be treated as an internal or external entity.
Throws
IOException Thrown on i/o error.
XNIException Thrown by entity handler to signal an error.

public void startEntity (String entityName, boolean literal)

Starts a named entity.

Parameters
entityName The name of the entity to start.
literal True if this entity is started within a literal value.
Throws
IOException Thrown on i/o error.
XNIException Thrown by entity handler to signal an error.

public void startExternalSubset ()

Protected Methods

protected Reader createReader (InputStream inputStream, String encoding, Boolean isBigEndian)

Creates a reader capable of reading the given input stream in the specified encoding.

Parameters
inputStream The input stream.
encoding The encoding name that the input stream is encoded using. If the user has specified that Java encoding names are allowed, then the encoding name may be a Java encoding name; otherwise, it is an ianaEncoding name.
isBigEndian For encodings (like uCS-4), whose names cannot specify a byte order, this tells whether the order is bigEndian. null menas unknown or not relevant.
Returns
  • Returns a reader.
Throws
IOException

protected static String fixURI (String str)

Fixes a platform dependent filename to standard URI form.

Parameters
str The string to fix.
Returns
  • Returns the fixed URI string.

protected Object[] getEncodingName (byte[] b4, int count)

Returns the IANA encoding name that is auto-detected from the bytes specified, with the endian-ness of that encoding where appropriate.

Parameters
b4 The first four bytes of the input.
count The number of bytes actually read.
Returns
  • a 2-element array: the first element, an IANA-encoding string, the second element a Boolean which is true iff the document is big endian, false if it's little-endian, and null if the distinction isn't relevant.