1 /*
2 * Copyright 2007 Ralf Joachim
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 *
14 * $Id: Configuration.java 6907 2007-03-28 21:24:52Z rjoachim $
15 */
16 package org.castor.xml;
17
18 import org.castor.core.CoreProperties;
19 import org.castor.core.util.CastorProperties;
20 import org.castor.core.util.AbstractProperties;
21
22 /**
23 * Properties of XML module.
24 *
25 * @version $Id: Configuration.java,v 1.8 2006/03/08 17:25:52 jens Exp $
26 * @author <a href="mailto:ralf DOT joachim AT syscon DOT eu">Ralf Joachim</a>
27 * @since 1.1.3
28 */
29 public class XMLProperties extends AbstractProperties {
30 // --------------------------------------------------------------------------
31
32 /** Path to Castor properties of core module. */
33 private static final String FILEPATH = "/org/castor/xml/";
34
35 /** Name of Castor properties of core module. */
36 private static final String FILENAME = "castor.xml.properties";
37
38 // --------------------------------------------------------------------------
39
40 /**
41 * Factory method for a default XML properties instance. Application and domain class loaders will
42 * be initialised to the one used to load this class. The properties instance returned will be a
43 * CastorProperties with a XMLProperties and a CoreProperties instance as parents. The
44 * CastorProperties holding user specific properties is the only one that can be modified by put()
45 * and remove() methods. XMLProperties and CoreProperties are responsible to deliver Castor's
46 * default values if they have not been overwritten by the user.
47 *
48 * @return Properties instance for Castor XML module.
49 */
50 public static AbstractProperties newInstance() {
51 AbstractProperties core = new CoreProperties();
52 AbstractProperties xml = new XMLProperties(core);
53 AbstractProperties castor = new CastorProperties(xml);
54 return castor;
55 }
56
57 /**
58 * Factory method for a XML properties instance that uses the specified class loaders. The
59 * properties instance returned will be a CastorProperties with a XMLProperties and a
60 * CoreProperties instance as parents. The CastorProperties holding user specific properties is
61 * the only one that can be modified by put() and remove() methods. XMLProperties and
62 * CoreProperties are responsible to deliver Castor's default values if they have not been
63 * overwritten by the user.
64 *
65 * @param app {@link ClassLoader} to be used for all classes of Castor and its required libraries.
66 * @param domain {@link ClassLoader} to be used for all domain objects.
67 * @return Properties instance for Castor XML module.
68 */
69 public static AbstractProperties newInstance(final ClassLoader app, final ClassLoader domain) {
70 AbstractProperties core = new CoreProperties(app, domain);
71 AbstractProperties xml = new XMLProperties(core);
72 AbstractProperties castor = new CastorProperties(xml);
73 return castor;
74 }
75
76 // --------------------------------------------------------------------------
77
78 /**
79 * Construct properties with given parent. Application and domain class loaders will be
80 * initialized to the ones of the parent. <br/>
81 * Note: This constructor is not intended for public use. Use one of the newInstance() methods
82 * instead.
83 *
84 * @param parent Parent properties.
85 */
86 public XMLProperties(final AbstractProperties parent) {
87 super(parent);
88 loadDefaultProperties(FILEPATH, FILENAME);
89 }
90
91 // --------------------------------------------------------------------------
92
93 // Specify public keys of XML configuration properties here.
94
95 // --------------------------------------------------------------------------
96
97 /**
98 * Property specifying the type of XML node to use for primitive values, either 'element' or
99 * 'attribute'.
100 *
101 * Possible values: - 'element' - 'attribute' (default)
102 *
103 * <pre>
104 * org.exolab.castor.xml.introspector.primitive.nodetype
105 * </pre>
106 */
107 public static final String PRIMITIVE_NODE_TYPE =
108 "org.exolab.castor.xml.introspector.primitive.nodetype";
109
110 /**
111 * Property specifying the class name of the SAX 1 XML parser to use.
112 *
113 * <pre>
114 * org.exolab.castor.parser
115 * </pre>
116 */
117 public static final String PARSER = "org.exolab.castor.parser";
118
119 // TODO: expand comment to make things clearer; check against code
120 /**
121 * Property specifying whether to perform document validation by default.
122 *
123 * Possible values: - false (default) - true
124 *
125 * <pre>
126 * org.exolab.castor.SAXParser.validation
127 * </pre>
128 */
129 public static final String PARSER_VALIDATION = "org.exolab.castor.parser.validation";
130
131 /**
132 * Property specifying whether to support XML namespaces by default.
133 *
134 * Possible values: - false (default) - true
135 *
136 * <pre>
137 * org.exolab.castor.SAXParser.namespaces
138 * </pre>
139 */
140 public static final String NAMESPACES = "org.exolab.castor.parser.namespaces";
141
142 /**
143 * Property specifying XML namespace to Java package mappings.
144 *
145 * <pre>
146 * org.exolab.castor.xml.nspackages
147 * </pre>
148 */
149 public static final String NAMESPACE_PACKAGE_MAPPINGS = "org.exolab.castor.xml.nspackages";
150
151 /**
152 * Property specifying the 'type' of the XML naming conventions to use. Values of this property
153 * must be either "mixed", "lower", or the name of a class which extends
154 * {@link org.exolab.castor.xml.AbstractXMLNaming}.
155 *
156 * Possible values: - 'mixed' - 'lower' - A class name (which extends
157 * {@link org.exolab.castor.xml.AbstractXMLNaming}).
158 *
159 * <pre>
160 * org.exolab.castor.xml.naming
161 * </pre>
162 *
163 */
164 public static final String XML_NAMING = "org.exolab.castor.xml.naming";
165
166 /**
167 * Property specifying the 'type' of the Java naming conventions to use. Values of this property
168 * must be either null or the name of a class which extends {@link org.castor.xml.JavaNaming}.
169 *
170 * Possible values: - null - A class name (which extends {@link org.castor.xml.JavaNaming}).
171 *
172 * <pre>
173 * org.castor.xml.java_naming
174 * </pre>
175 *
176 */
177 public static final String JAVA_NAMING = "org.castor.xml.java.naming";
178
179 /**
180 * Property specifying whether to use validation in the marshalling framework.
181 *
182 *
183 * Possible values: - false - true (default)
184 *
185 * <pre>
186 * org.exolab.castor.marshalling.validation
187 * </pre>
188 */
189 public static final String MARSHALLING_VALIDATION = "org.exolab.castor.marshalling.validation";
190
191 /**
192 * Property specifying whether XML documents (as generated at marshalling) should use indentation
193 * or not.
194 *
195 * Possible values: - false (default) - true
196 *
197 * <pre>
198 * org.exolab.castor.indent
199 * </pre>
200 */
201 public static final String USE_INDENTATION = "org.exolab.castor.indent";
202
203 /**
204 * Property specifying additional features for the XML parser. This value contains a comma
205 * separated list of features that might or might not be supported by the specified SAX parser.
206 *
207 * <pre>
208 * org.exolab.castor.sax.features
209 * </pre>
210 */
211 public static final String PARSER_FEATURES = "org.exolab.castor.sax.features";
212
213 /**
214 * Property specifying features to be disabled on the underlying SAX parser. This value contains a
215 * comma separated list of features to be disabled.
216 *
217 * <pre>
218 * org.exolab.castor.sax.features - to - disable
219 * </pre>
220 */
221 public static final String PARSER_FEATURES_DISABLED = "org.exolab.castor.sax.features-to-disable";
222
223 /**
224 * Property specifying the regular expression validator to use. The specified class must implement
225 * {@link org.exolab.castor.xml.validators.RegExpValidator}
226 *
227 * Possible values: - A class name.
228 *
229 * <pre>
230 * org.exolab.castor.regexp
231 * </pre>
232 */
233 public static final String REG_EXP_CLASS_NAME = "org.exolab.castor.regexp";
234
235 /**
236 * Property specifying whether to run in debug mode.
237 *
238 * Possible values: - false (default) - true
239 *
240 * <pre>
241 * org.exolab.castor.debug
242 * </pre>
243 */
244 public static final String DEBUG = "org.exolab.castor.debug";
245
246 /**
247 * Property specifying whether to apply strictness to elements when unmarshalling. Default is true
248 * which means that elements appearing in the XML document, which cannot be mapped to a class,
249 * cause a {@link SAXException} to be thrown. If set to false, these 'unknown' elements are
250 * ignored.
251 *
252 * Possible values: - false - true (default)
253 *
254 * <pre>
255 * org.exolab.castor.strictelements
256 * </pre>
257 */
258 public static final String STRICT_ELEMENTS = "org.exolab.castor.xml.strictelements";
259
260 /**
261 * Property specifying whether or not to save the "keys" of a {@link Hashtable} or {@link Map}
262 * during marshalling. By default this is true.
263 *
264 * Backwards compatibility switch (for 0.9.5.2 users and earlier)
265 *
266 * Possible values: - false - true (default)
267 *
268 * <pre>
269 * org.exolab.castor.xml.saveMapKeys
270 * </pre>
271 *
272 * @since 0.9.5.3
273 */
274 public static final String SAVE_MAP_KEYS = "org.exolab.castor.xml.saveMapKeys";
275
276 /**
277 * Property specifying whether the ClassDescriptorResolver should (automatically) search for and
278 * consult with package mapping files (.castor.xml) to retrieve class descriptor information; on
279 * by default.
280 *
281 * Possible values: - false - true (default)
282 *
283 * <pre>
284 * org.exolab.castor.xml.loadPackageMappings
285 * </pre>
286 *
287 * @since 1.0
288 */
289 public static final String LOAD_PACKAGE_MAPPING = "org.exolab.castor.xml.loadPackageMappings";
290
291 /**
292 * Property specifying what factory to use for dealing with XML serializers.
293 *
294 * Possible value: - A class name
295 *
296 * <pre>
297 * org.exolab.castor.xml.serializer.factory
298 * </pre>
299 *
300 * @since 1.0
301 */
302 public static final String SERIALIZER_FACTORY = "org.exolab.castor.xml.serializer.factory";
303
304 /**
305 * Property specifying whether sequence order validation should be lenient.
306 *
307 * Possible values - false (default) - true
308 *
309 * <pre>
310 * org.exolab.castor.xml.lenient.sequence.order = false
311 * </pre>
312 *
313 * since 1.1
314 */
315 public static final String LENIENT_SEQUENCE_ORDER =
316 "org.exolab.castor.xml.lenient.sequence.order";
317
318 /**
319 * Property specifying whether id/href validation should be lenient; defaults to false.
320 *
321 * Possible values: - false (default) - true
322 *
323 * <pre>
324 * org.exolab.castor.xml.lenient.id.validation = false
325 * </pre>
326 *
327 * since 1.1
328 */
329 public static final String LENIENT_ID_VALIDATION = "org.exolab.castor.xml.lenient.id.validation";
330
331 /**
332 * Property specifying whether or not to search for an proxy interface at marshalling. If property
333 * is not empty the objects to be marshalled will be searched if they implement one of the given
334 * interface names. If the interface is implemented the superclass will be marshalled instead of
335 * the class itself.
336 *
337 * <pre>
338 * org.exolab.castor.xml.proxyInterfaces
339 * </pre>
340 *
341 * @since 1.1.3
342 */
343 public static final String PROXY_INTERFACES = "org.exolab.castor.xml.proxyInterfaces";
344
345
346 /**
347 * Property specifying whether element strictness for introspected classes/elements should be
348 * lenient (aka allowed); defaults to true.
349 *
350 * Possible values: - false - true (default)
351 *
352 * <pre>
353 * org.exolab.castor.xml.lenient.introspected.element.strictness = true
354 * </pre>
355 *
356 * @since 1.1.3
357 */
358 public static final String LENIENT_INTROSPECTED_ELEMENT_STRICTNESS =
359 "org.exolab.castor.xml.lenient.introspected.element.strictness";
360
361 /**
362 * Property specifying which collections handlers should be used for Java 1.1 and Java 1.2
363 * run-times.
364 *
365 * <pre>
366 * org.exolab.castor.mapping.collections
367 * </pre>
368 */
369 public static final String COLLECTION_HANDLERS_FOR_JAVA_11_OR_12 =
370 "org.exolab.castor.mapping.collections";
371
372 /**
373 * Property specifying if introspection should be used at class resolving.
374 *
375 * <pre>
376 * org.castor.xml.class - resolver.use - introspection
377 * </pre>
378 */
379 public static final String USE_INTROSPECTION = "org.castor.xml.class-resolver.use-introspection";
380
381 /**
382 * The property name for enabling collection wrapping. The property controls whether or not
383 * collections (arrays, vectors, etc) should be wrapped in a container element. For example:
384 *
385 * <pre>
386 * <foos>
387 * <foo>foo1</foo>
388 * <foo>foo2</foo>
389 * </foos>
390 *
391 * instead of the default:
392 *
393 * <foos>foo1<foos>
394 * <foos>foo2</foos>
395 *
396 * </pre>
397 *
398 * Use this property with a value of true or false in the castor.properties file
399 *
400 * org.exolab.castor.xml.introspector.wrapCollections=true -or-
401 * org.exolab.castor.xml.introspector.wrapCollections=false
402 *
403 * This property is false by default.
404 */
405 public static final String WRAP_COLLECTIONS_PROPERTY =
406 "org.exolab.castor.xml.introspector.wrapCollections";
407
408 /**
409 * Property that allows to specify whether the validation for <xs:integer> should accept the
410 * old 'int/Integer' members as well; default to false.
411 *
412 * Possible values: - false (default) - true
413 *
414 * <pre>
415 * org.exolab.castor.xml.lenient.integer.validation = false
416 * </pre>
417 */
418 public static final String LENIENT_INTEGER_VALIDATION =
419 "org.exolab.castor.xml.lenient.integer.validation";
420
421 /**
422 * Property that allows to specify the XML document version number to be used during marshalling;
423 * defaults to 1.0.
424 *
425 * Possible values: - 1.0 (default) - 1.1
426 *
427 * <pre>
428 * org.exolab.castor.xml.version = 1.0
429 * </pre>
430 */
431 public static final String XML_VERSION = "org.exolab.castor.xml.version";
432
433 /**
434 * Property that allows to override Castor's introspector conversion rules for member names; if
435 * enabled, even member names such as 'XMLMember' will be camel-cased to 'xMLMember'; defaults to
436 * false.
437 *
438 * Possible values: - false (default) - true
439 *
440 * <pre>
441 * org.exolab.castor.xml.member.naming.capitalisation.strict = false
442 * </pre>
443 */
444 public static final String MEMBER_NAME_CAPITALISATION_STRICT =
445 "org.exolab.castor.xml.member.naming.capitalisation.strict";
446
447 }