Package org.geotools.xml

Class DocumentFactory

Object

DocumentFactory

public class DocumentFactory
extends Object

This is the main entry point into the XSI parsing routines.

Example Use:

     Object x = DocumentFactory.getInstance(new URI("MyInstanceDocumentURI");
 

A selection of the hints available to configure parsing:

• VALIDATION_HINT - Boolean.FALSE to disable validation
• DocumentHandler.DEFAULT_NAMESPACE_HINT_KEY - Schema for parsing and validation
• XMLHandlerHints.FLOW_HANDLER_HINT
• XMLHandlerHints.NAMESPACE_MAPPING - Map<String,URL> namespace mapping
• XMLHandlerHints.ENTITY_RESOLVER - control entry resolution
• DISABLE_EXTERNAL_ENTITIES - Boolean.TRUE to disable entity resolution
• XMLHandlerHints.SAX_PARSER_FACTORY - supply factory used by getParser(Map)

Author:

dzwiers, Refractions Research, Inc. http://www.refractions.net

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DISABLE_EXTERNAL_ENTITIES	When this hint is contained and set to Boolean.TRUE (the default value), external entities will be disabled.
static final String	ENABLE_DTD	When this hint is contained and set to Boolean.TRUE, parsing and validation supports use of DTD.
static final String	LOG_LEVEL
static final String	VALIDATION_HINT	When this hint is contained and set to Boolean.FALSE, element ordering will not be validated.

Constructor Summary

Constructors

Constructor	Description
DocumentFactory()

Method Summary

Modifier and Type	Method	Description
static Object	getInstance(InputStream is, Map<String,Object> hints, Level defaultLevel)	Parses the instance data provided.
static Object	getInstance(URI desiredDocument, Map<String,Object> hints)	Calls getInstance(URI,Level) with Level.WARNING.
static Object	getInstance(URI desiredDocument, Map<String,Object> hints, Level defaultLevel)	Parses the instance data provided.
static <T> T	hint(Class<T> type, Map<String,Object> hints, String key, T defaultValue)	Safely check hints for provided key.
static boolean	hint(Map<String,Object> hints, String key, boolean defaultValue)	Safely check hints for provided key.

Methods inherited from class Object

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

Field Details

VALIDATION_HINT

public static final String VALIDATION_HINT

When this hint is contained and set to Boolean.FALSE, element ordering will not be validated. This key may also affect data validation within the parse routines.

The inherent safety of the resulting objects is weakened by turning this param to false.

See Also:

• Constant Field Values

DISABLE_EXTERNAL_ENTITIES

public static final String DISABLE_EXTERNAL_ENTITIES

When this hint is contained and set to Boolean.TRUE (the default value), external entities will be disabled.

This setting is used to alleviate XXE attacks, preventing both VALIDATION_HINT and XMLHandlerHints.ENTITY_RESOLVER from being effective.

See Also:

• Constant Field Values

ENABLE_DTD

public static final String ENABLE_DTD

When this hint is contained and set to Boolean.TRUE, parsing and validation supports use of DTD.

A few standards such as SLD1.0 and WMS1.1 make use of DTD support and require this hint to be set to true.

See Also:

• Constant Field Values

LOG_LEVEL

public static final String LOG_LEVEL

See Also:

• Constant Field Values

Constructor Details

DocumentFactory

public DocumentFactory()

Method Details

getInstance

public static Object getInstance(URI desiredDocument,
 Map<String,Object> hints)
                          throws SAXException

Calls getInstance(URI,Level) with Level.WARNING.

Parameters:

hints - May be null.

Returns:

Object

Throws:

SAXException

See Also:

• getInstance(URI, Map, Level)

getInstance

public static Object getInstance(URI desiredDocument,
 Map<String,Object> hints,
 Level defaultLevel)
                          throws SAXException

Parses the instance data provided. This method assumes that the XML document is fully described using XML Schemas. Failure to be fully described as Schemas will result in errors, as opposed to a vid parse.

Parameters:

hints - May be null.

Returns:

Object

Throws:

SAXException

getInstance

public static Object getInstance(InputStream is,
 Map<String,Object> hints,
 Level defaultLevel)
                          throws SAXException

Parses the instance data provided. This method assumes that the XML document is fully described using XML Schemas. Failure to be fully described as Schemas will result in errors, as opposed to a vid parse.

Parameters:

is - InputStream to parse, will be closed by this method.

hints - DocumentFactory parsing hints

defaultLevel - Log level to use for logging during parsing, may be null (defaults to Level.WARNING).

Returns:

Parsed

Throws:

SAXException - If an error occurs during parsing, or if the provided InputStream cannot be read.

hint

public static <T> T hint(Class<T> type,
 Map<String,Object> hints,
 String key,
 T defaultValue)

Safely check hints for provided key.

Parameters:

hints - Map of hints, may be if not provided.

key - Key to look up hint value

defaultValue - Default value returned if value is not available, or not a Boolean.

Returns:

Value of hint if available and a Boolean, otherwise defaultValue.

hint

public static boolean hint(Map<String,Object> hints,
 String key,
 boolean defaultValue)

Safely check hints for provided key.

Parameters:

hints - Map of hints, may be if not provided.

key - Key to look up hint value

defaultValue - Default value returned if value is not available, or not a Boolean.

Returns:

Value of hint if available and a Boolean, otherwise defaultValue.