org.exolab.castor.util

Class Configuration

java.lang.Object

org.exolab.castor.util.Configuration

Direct Known Subclasses:

LocalConfiguration

public abstract class Configuration
extends java.lang.Object

Provides default configuration for Castor components from the castor.properties configuration file. All Castor features rely on the central configuration file.

The configuration file is loaded from the Java lib directory, the classpath and the Castor JAR. Properties set in the classpath file takes precedence over properties set in the Java library configuration file and properties set in the Castor JAR, allowing for each customization. All three files are named castor.properties.

For example, to change the parser in use, specify that all documents should be printed with identantion or turn debugging on, create a new configuration file in the current directory, instead of modifying the global one.

Version:

$Revision: 6259 $ $Date: 2006-04-25 15:08:23 -0600 (Tue, 25 Apr 2006) $

Author:

Keith Visco, Assaf Arkin

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	Configuration.ConfigValues Inner class to hold values of the configuration
(package private) static class	Configuration.Features
static class	Configuration.Property Names of properties used in the configuration file.

Field Summary

Fields

Modifier and Type	Field and Description
(package private) static java.lang.String	ON_VALUE
(package private) static java.lang.String	TRUE_VALUE

Constructor Summary

Constructors

Constructor and Description
Configuration() Protected default constructor

Method Summary

Modifier and Type	Method and Description
boolean	debug() Returns true if the configuration specifies debugging.
static java.util.Properties	getDefault() Returns the default configuration file.
static boolean	getDefaultDebug() Returns true if the default configuration specified debugging.
static boolean	getDefaultMarshallingValidation() Returns true if the default configuration specifies validation in the marshalling framework.
static OutputFormat	getDefaultOutputFormat() Returns the default OutputFormat for use with a Serializer.
static org.xml.sax.Parser	getDefaultParser() Return an XML document parser implementing the feature list specified in the default configuration file.
static org.xml.sax.Parser	getDefaultParser(java.lang.String features) Returns an XML document parser implementing the requested set of features.
static NodeType	getDefaultPrimitiveNodeType() Returns the NodeType to use for Java primitives.
static java.lang.String	getDefaultProperty(java.lang.String name, java.lang.String defValue) Returns a property from the default configuration file.
static RegExpEvaluator	getDefaultRegExpEvaluator() Returns a new instance of the specified Regular Expression Evaluator, or null if no validator was specified
static Serializer	getDefaultSerializer() Returns a default serializer for producing an XML document.
static org.xml.sax.DocumentHandler	getDefaultSerializer(java.io.OutputStream output) Returns a default serializer for producing an XML document to the designated output stream using the default serialization format.
static org.xml.sax.DocumentHandler	getDefaultSerializer(java.io.Writer output) Returns a default serializer for producing an XML document to the designated output stream using the default serialization format.
static boolean	getDefaultStrictElements() Access to the property specifying whether to apply strictness to elements when unmarshalling.
static XMLNaming	getDefaultXMLNaming() Returns the default naming conventions to use for the XML framework
static org.xml.sax.XMLReader	getDefaultXMLReader() Returns an XML document parser implementing the requested set of features.
static org.xml.sax.XMLReader	getDefaultXMLReader(java.lang.String features) Returns an XML document parser implementing the requested set of features.
abstract OutputFormat	getOutputFormat() Returns the currently configured OutputFormat for use with a Serializer.
org.xml.sax.Parser	getParser() Return an XML parser implementing the feature list specified in the configuration file.
NodeType	getPrimitiveNodeType() Returns the currently configured NodeType to use for Java primitives.
java.util.Properties	getProperties() Returns the current properties from the configuration file(s).
java.lang.String	getProperty(java.lang.String name, java.lang.String defValue) Returns a property from the current configuration.
RegExpEvaluator	getRegExpEvaluator() Returns a new instance of the specified Regular Expression Evaluator, or null if no validator was specified
abstract Serializer	getSerializer() Returns a serializer for producing an XML instance document.
abstract org.xml.sax.DocumentHandler	getSerializer(java.io.OutputStream output) Returns a serializer for producing an XML document to the designated output stream using the default serialization format.
abstract org.xml.sax.DocumentHandler	getSerializer(java.io.Writer output) Returns a serializer for producing an XML instance document to the designated output stream using the default serialization format.
protected static XMLSerializerFactory	getSerializerFactory(java.util.Properties props) Returns the currently configured XMLSerializerFactory instance.
XMLNaming	getXMLNaming() Returns the currently configured naming conventions to use for the XML framework Design note: This method should be overloaded by any sub-classes.
org.xml.sax.XMLReader	getXMLReader() Returns an XML document parser implementing the requested set of features.
protected static void	loadDefaults() Called by getDefault() to load the configuration the first time.
static java.util.Properties	loadProperties(java.lang.String resourceName, java.lang.String fileName) Load the configuration will not complain about inability to load configuration file from one of the default directories, but if it cannot find the JAR's configuration file, will throw a run time exception.
boolean	marshallingValidation() Returns true if the current configuration (user-supplied or default) specifies validation in the marshalling framework.
protected static void	setFeaturesOnXmlReader(java.lang.String features, boolean validation, boolean namespaces, org.xml.sax.XMLReader xmlReader) Sets features on XML reader instance.
boolean	strictElements() Access to the property specifying whether to apply strictness to elements when unmarshalling.

Methods inherited from class java.lang.Object

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

Field Detail

TRUE_VALUE

static final java.lang.String TRUE_VALUE

See Also:

Constant Field Values

ON_VALUE

static final java.lang.String ON_VALUE

See Also:

Constant Field Values

Constructor Detail

Configuration

Configuration()

Protected default constructor

Method Detail

debug

public boolean debug()

Returns true if the configuration specifies debugging. Design note: This method should be overloaded by any sub-classes.

Returns:

true if the configuration specifies debugging.

See Also:

getDefaultDebug()

getDefaultDebug

public static boolean getDefaultDebug()

Returns true if the default configuration specified debugging.

Returns:

true if the configuration specifies debugging.

strictElements

public boolean strictElements()

Access to the property specifying whether to apply strictness to elements when unmarshalling. Default is true which means that elements appearing in the XML Documnt which cannot be mapped to a class cause a SAXException to be thrown. If set to false, these 'unknown' elements are ignored. Design note: This method should be overloaded by any sub-classes.

Returns:

true if element processing should be "strict".

See Also:

getDefaultStrictElements()

getDefaultStrictElements

public static boolean getDefaultStrictElements()

Access to the property specifying whether to apply strictness to elements when unmarshalling. Default is true which means that elements appearing in the XML Documnt which cannot be mapped to a class cause a SAXException to be thrown. If set to false, these 'unknown' elements are ignored

Returns:

true if element processing should be "strict".

See Also:

strictElements()

marshallingValidation

public boolean marshallingValidation()

Returns true if the current configuration (user-supplied or default) specifies validation in the marshalling framework. Design note: This method should be overloaded by any sub-classes.

Returns:

true if by default validation should be performed during the marshalling and unmarshalling process, otherwise false.

See Also:

getDefaultMarshallingValidation()

getDefaultMarshallingValidation

public static boolean getDefaultMarshallingValidation()

Returns true if the default configuration specifies validation in the marshalling framework.

Returns:

true if by default validation should be performed during the marshalling and unmarshalling process, otherwise false.

See Also:

marshallingValidation()

getProperties

public java.util.Properties getProperties()

Returns the current properties from the configuration file(s). The Properties returned may be empty, but never null. Design note: This method should be overloaded by any sub-classes.

Returns:

the current set of configuration properties.

See Also:

getDefault()

getDefault

public static java.util.Properties getDefault()

Returns the default configuration file. Changes to the returned properties set may affect all Castor functions relying on the default configuration.

Returns:

the default configuration properties

See Also:

getProperties()

getProperty

public java.lang.String getProperty(java.lang.String name,
                                    java.lang.String defValue)

Returns a property from the current configuration. Equivalent to calling getProperty on the result of getDefault().

Parameters:

name - The property name

defValue - The property's default value

Returns:

The property's value

See Also:

getDefaultProperty(String,String), getProperties()

getDefaultProperty

public static java.lang.String getDefaultProperty(java.lang.String name,
                                                  java.lang.String defValue)

Returns a property from the default configuration file. Equivalent to calling getProperty on the result of getDefault().

Parameters:

name - The property name

defValue - The property's default value

Returns:

The property's value

See Also:

(String, String)

getXMLNaming

public XMLNaming getXMLNaming()

Returns the currently configured naming conventions to use for the XML framework Design note: This method should be overloaded by any sub-classes.

Returns:

the currently configured naming conventions to use for the XML framework

See Also:

getDefaultXMLNaming()

getDefaultXMLNaming

public static XMLNaming getDefaultXMLNaming()

Returns the default naming conventions to use for the XML framework

Returns:

the default naming conventions to use for the XML framework

getParser

public org.xml.sax.Parser getParser()

Return an XML parser implementing the feature list specified in the configuration file. Design note: This method should be overloaded by any sub-classes.

Returns:

a suitable XML parser

See Also:

getDefaultParser()

getDefaultParser

public static org.xml.sax.Parser getDefaultParser()

Return an XML document parser implementing the feature list specified in the default configuration file.

Returns:

a suitable XML parser

See Also:

getParser()

getDefaultParser

public static org.xml.sax.Parser getDefaultParser(java.lang.String features)

Returns an XML document parser implementing the requested set of features. The feature list is a comma separated list of features that parser may or may not support. No errors are generated for unsupported features. If the feature list is not null, it overrides the default feature list specified in the configuration file, including validation and Namespaces.

Parameters:

features - The requested feature list, null for the defaults

Returns:

A suitable XML parser

setFeaturesOnXmlReader

protected static void setFeaturesOnXmlReader(java.lang.String features,
                                             boolean validation,
                                             boolean namespaces,
                                             org.xml.sax.XMLReader xmlReader)

Sets features on XML reader instance.

Parameters:

features -

validation - Whether to enable validation or not.

namespaces - Whether to enable namespace support for not.

xmlReader - The XMLReader instance to configure.

getPrimitiveNodeType

public NodeType getPrimitiveNodeType()

Returns the currently configured NodeType to use for Java primitives. A null value will be returned if no NodeType was specified, indicating the default NodeType should be used. Design note: This method should be overloaded by any sub-classes.

Returns:

the NodeType assigned to Java primitives, or null if no NodeType was specified.

See Also:

getDefaultPrimitiveNodeType()

getDefaultPrimitiveNodeType

public static NodeType getDefaultPrimitiveNodeType()

Returns the NodeType to use for Java primitives. A null value will be returned if no NodeType was specified, indicating the default NodeType should be used.

Returns:

the NodeType assigned to Java primitives, or null if no NodeType was specified.

See Also:

getPrimitiveNodeType()

getXMLReader

public org.xml.sax.XMLReader getXMLReader()

Returns an XML document parser implementing the requested set of features. The feature list is a comma separated list of features that parser may or may not support. No errors are generated for unsupported features. If the feature list is not null, it overrides the default feature list specified in the configuration file, including validation and Namespaces.

Returns:

A suitable XML parser

getDefaultXMLReader

public static org.xml.sax.XMLReader getDefaultXMLReader()

Returns an XML document parser implementing the requested set of features. The feature list is a comma separated list of features that parser may or may not support. No errors are generated for unsupported features. If the feature list is not null, it overrides the default feature list specified in the configuration file, including validation and Namespaces.

Returns:

A suitable XML parser

getDefaultXMLReader

public static org.xml.sax.XMLReader getDefaultXMLReader(java.lang.String features)

Returns an XML document parser implementing the requested set of features. The feature list is a comma separated list of features that parser may or may not support. No errors are generated for unsupported features. If the feature list is not null, it overrides the default feature list specified in the configuration file, including validation and Namespaces.

Parameters:

features - The requested feature list, null for the defaults

Returns:

A suitable XML parser

getRegExpEvaluator

public RegExpEvaluator getRegExpEvaluator()

Returns a new instance of the specified Regular Expression Evaluator, or null if no validator was specified

Returns:

the regular expression evaluator,

See Also:

getDefaultRegExpEvaluator()

getDefaultRegExpEvaluator

public static RegExpEvaluator getDefaultRegExpEvaluator()

Returns a new instance of the specified Regular Expression Evaluator, or null if no validator was specified

Returns:

the regular expression evaluator,

See Also:

getRegExpEvaluator()

getSerializer

public abstract Serializer getSerializer()

Returns a serializer for producing an XML instance document. The caller can specify an alternative output format, may reuse this serializer across several streams, and may serialize both DOM and SAX events. Design note: This method should be overloaded by any sub-classes.

Returns:

A suitable serializer

See Also:

getDefaultSerializer()

getDefaultSerializer

public static Serializer getDefaultSerializer()

Returns a default serializer for producing an XML document. The caller can specify an alternative output format, may reuse this serializer across several streams, and may serialize both DOM and SAX events. If such control is not required, it is recommended to call one of the other two methods.

Returns:

A suitable serializer

See Also:

getSerializer()

getOutputFormat

public abstract OutputFormat getOutputFormat()

Returns the currently configured OutputFormat for use with a Serializer. Design note: This method should be overloaded by any sub-classes.

Returns:

the currently configured OutputFormat.

See Also:

getDefaultOutputFormat()

getDefaultOutputFormat

public static OutputFormat getDefaultOutputFormat()

Returns the default OutputFormat for use with a Serializer.

Returns:

the default OutputFormat

getSerializer

public abstract org.xml.sax.DocumentHandler getSerializer(java.io.OutputStream output)
                                                   throws java.io.IOException

Returns a serializer for producing an XML document to the designated output stream using the default serialization format. Design note: This method should be overloaded by any sub-classes.

Parameters:

output - the output stream

Returns:

A suitable serializer

Throws:

java.io.IOException

getDefaultSerializer

public static org.xml.sax.DocumentHandler getDefaultSerializer(java.io.OutputStream output)
                                                        throws java.io.IOException

Returns a default serializer for producing an XML document to the designated output stream using the default serialization format.

Parameters:

output - the output stream

Returns:

A suitable serializer

Throws:

java.io.IOException

getSerializer

public abstract org.xml.sax.DocumentHandler getSerializer(java.io.Writer output)
                                                   throws java.io.IOException

Returns a serializer for producing an XML instance document to the designated output stream using the default serialization format. Design note: This method should be overloaded by any sub-classes.

Parameters:

output - the Writer to write data to.

Returns:

A suitable serializer

Throws:

java.io.IOException

getDefaultSerializer

public static org.xml.sax.DocumentHandler getDefaultSerializer(java.io.Writer output)
                                                        throws java.io.IOException

Returns a default serializer for producing an XML document to the designated output stream using the default serialization format.

Parameters:

output - the Writer to write data to.

Returns:

A suitable serializer

Throws:

java.io.IOException

loadDefaults

protected static void loadDefaults()

Called by getDefault() to load the configuration the first time. Will not complain about inability to load configuration file from one of the default directories, but if it cannot find the JAR's configuration file, will throw a run time exception.

loadProperties

public static java.util.Properties loadProperties(java.lang.String resourceName,
                                                  java.lang.String fileName)

Load the configuration will not complain about inability to load configuration file from one of the default directories, but if it cannot find the JAR's configuration file, will throw a run time exception.

getSerializerFactory

protected static XMLSerializerFactory getSerializerFactory(java.util.Properties props)

Returns the currently configured XMLSerializerFactory instance.

Parameters:

props - Property set to use.

Returns:

XMLSerializerFactory to use by Castor