Fork me on GitHub

XML configuration file

News

  • Added a section on how to access the properties as defined in the Castor properties file from within code.

  • Release 1.2.1: : Added new org.exolab.castor.xml.lenient.integer.validation property to allow configuration of leniency for validation for Java properties generated from <xs:integer> types during code generation.

  • Release 1.2: : Access to the org.exolab.castor.util.LocalConfiguration class has been removed completely. To access the properties as used by Castor from code, please refer to the below section.

  • Release 1.1.3: Added special processing of proxied classes. The property org.exolab.castor.xml.proxyInterfaces allows you to specify a list of interfaces that such proxied objects implement. If your object implements one of these interfaces Castor will not use the class itself but its superclass at introspection or to find class mappings and ClassDescriptors.

  • Release 0.9.7: Added new org.exolab.castor.persist.useProxies property to allow configuration of JDBC proxy classes. If enabled, JDBC proxy classes will be used to wrap java.sql.Connection and java.sql.PreparedStatement instances, to allow for more detailed and complete JDBC statements to be output during logging. When turned off, no logging statements will be generated at all.

Introduction

Castor uses a configuration file for environmental properties that are shared across all the Castor sub systems. The configuration file is specified as a Java properties file with the name castor.properties.

By definition, a default configuration file is included with the Castor XML JAR. Custom properties can be supplied using one of the following methods. Please note that the custom properties specified will override the default configuration.

  • Place a file named castor.properties anywhere on the classpath of your application.

  • Place a file named castor.properties in the working directory of your application.

  • Use the system property org.castor.user.properties.location to specify the location of your custom properties.

Please note that Castor XML - upon startup - will try the methods given above in exactly the sequence as stated above; if it managed to find a custom property file using any of the given methods, it will cancel its search.

When running the provided examples, Castor will use the configuration file located in the examples directory which specifies additional debugging information as well as pretty printing of all produced XML documents.

The following properties are currently supported in the configuration file:

Name Description Values Default Since
org.exolab.castor.xml.introspector.primitive.nodetype Property specifying the type of XML node to use for primitive values, either element or attribute element or attribute attribute
org.exolab.castor.parser Property specifying the class name of the SAX XML parser to use.
org.exolab.castor.parser.validation Specifies whether to perform XML document validation by default. true and false false
org.exolab.castor.parser.namespaces Specifies whether to support XML namespaces by default. false and true false
org.exolab.castor.xml.nspackages Specifies a list of XML namespace to Java package mappings.
org.exolab.castor.xml.naming Property specifying the ‘type’ of the XML naming conventions to use. Values of this property must be either mixed , lower , or the name of a class which extends org.exolab.castor.xml.XMLNaming . mixed , lower , or the name of a class which extends org.exolab.castor.xml.XMLNaming lower
org.castor.xml.java.naming Property specifying the ‘type’ of the Java naming conventions to use. Values of this property must be either null or the name of a class which extends link org.castor.xml.JavaNaming. null or the name of a class which extends link org.castor.xml.JavaNaming. null
org.exolab.castor.marshalling.validation Specifies whether to use validation during marshalling. false or true true
org.exolab.castor.indent Specifies whether XML documents (as generated at marshalling) should use indentation or not. false or true false
org.exolab.castor.sax.features Specifies additional features for the XML parser. A comma separated list of SAX (parser) features (that might or might not be supported by the specified SAX parser). http://apache.org/xml/features/disallow-doctype-decl
org.exolab.castor.sax.features-to-disable Specifies features to be disbaled on the underlying SAX parser. A comma separated list of SAX (parser) features to be disabled. http://xml.org/sax/features/external-general-entities, http://xml.org/sax/features/external-parameter-entities, http://apache.org/xml/features/nonvalidating/load-external-dtd 1.0.4
org.exolab.castor.regexp Specifies the regular expression validator to use. A class that implements org.exolab.castor.util.RegExpValidator.
org.exolab.castor.xml.strictelements Specifies whether to apply strictness to elements when unmarshalling. When enabled, the existence of elements in the XML document, which cannot be mapped to a class, causes a {@link SAXException} to be thrown. If set to false, these ‘unknown’ elements are ignored. false or true false
org.exolab.castor.xml.loadPackageMappings Specifies whether the ClassDescriptorResolver should (automatically) search for and consult with package mapping files ( .castor.xml ) to retrieve class descriptor information false or true true 1.0.2
org.exolab.castor.xml.serializer.factory Specifying what XML serializers factory to use. A class name org.exolab.castor.xml.XercesXMLSerializerFactory 1.0
org.exolab.castor.xml.lenient.sequence.order Specifies whether sequence order validation should be lenient. false or true false 1.1
org.exolab.castor.xml.lenient.id.validation Specifies whether id/href validation should be lenient. false or true false 1.1
org.exolab.castor.xml.proxyInterfaces Specifies whether or not to search for an proxy interface at marshalling. If property is not empty the objects to be marshalled will be searched if they implement one of the given interface names. If the interface is implemented, the superclass will be marshalled instead of the class itself. A list of proxy interfaces 1.1.3
org.exolab.castor.xml.lenient.integer.validation Specifies whether validation for Java properties generated from <xs:integer> should be lenient, i.e. allow for int s as well. false or true false 1.2.1
org.exolab.castor.xml.version Specifies the XML document version number to be used during marshalling; defaults to 1.0. 1.0 or 1.1 1.0 1.3.2

Note

As of Castor 1.3.3, the default values for org.exolab.castor.sax.features and org.exolab.castor.sax.features-to-disable have changed to include/disable selected features.

Accessing the properties from within code

As of Castor 1.1, it is possible to read and set the value of properties programmatically using the getProperty(String) and setProperty(String,String) on the following classes:

  • org.exolab.castor.xml.Unmarshaller

  • org.exolab.castor.xml.Marshaller

  • org.exolab.castor.xml.XMLContext

Whilst using the setter methods on the first two classes will change the settings of the respective instances only, using the setProperty() method on the org.exolab.castor.xml.XMLContext class will change the configuration globally, and affect all org.exolab.castor.xml.Unmarshaller and org.exolab.castor.xml.Marshaller instances created thereafter using the org.exolab.castor.xml.XMLContext.createUnmarshaller() and org.exolab.castor.xml.XMLContext.createMarshaller() methods.