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