# 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). | - | -
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. | - | 1.0.4
org.exolab.castor.regexp | Specifies the regular expression validator to use. | A class that implements `org.exolab.castor.xml.validators.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` | `true` | -
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

## 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.