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