1 /*
2 * Copyright 2007 Joachim Grueneis
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 package org.castor.xml;
15
16 import java.io.IOException;
17 import java.io.OutputStream;
18 import java.io.Writer;
19
20 import org.exolab.castor.mapping.Mapping;
21 import org.exolab.castor.mapping.MappingException;
22 import org.exolab.castor.mapping.MappingLoader;
23 import org.exolab.castor.util.RegExpEvaluator;
24 import org.exolab.castor.xml.Introspector;
25 import org.exolab.castor.xml.NodeType;
26 import org.exolab.castor.xml.OutputFormat;
27 import org.exolab.castor.xml.ResolverException;
28 import org.exolab.castor.xml.Serializer;
29 import org.exolab.castor.xml.XMLClassDescriptorResolver;
30 import org.exolab.castor.xml.util.ResolverStrategy;
31 import org.xml.sax.DocumentHandler;
32 import org.xml.sax.Parser;
33 import org.xml.sax.XMLReader;
34
35 /**
36 * The internal context is meant as center piece providing (and keeping) all information that is
37 * required by Marshaller, Unmarshaller, SourceGenerator, MappingTool, SchemaReader and
38 * SchemaWriter. It is created, filled with initial data and put into all other parts of Castor by
39 * {@link XMLContext}. It is NOT meant to be directly instantiated by user implementations! For all
40 * other objects it provides access to Castor state information (e.g. known descriptors) and
41 * configuration values.
42 *
43 * @author <a href="mailto:jgrueneis At gmail DOT com">Joachim Grueneis</a>
44 * @since 1.1.2
45 */
46 public interface InternalContext extends PropertyChangeProvider {
47
48 /**
49 * Instructs Castor to load class descriptors from the mapping given.
50 *
51 * @param mapping Castor XML mapping (file), from which the required class descriptors will be
52 * derived.
53 * @throws MappingException If the {@link Mapping} cannot be loaded and analyzed successfully.
54 */
55 void addMapping(final Mapping mapping) throws MappingException;
56
57 /**
58 * Loads the class descriptor for the class instance specified. The use of this method is useful
59 * when no mapping is used, as happens when the domain classes has been generated using the XML
60 * code generator (in which case instead of a mapping file class descriptor files will be
61 * generated).
62 *
63 * @param clazz the class for which the associated descriptor should be loaded.
64 * @throws ResolverException in case that resolving the Class fails fatally
65 */
66 void addClass(final Class<?> clazz) throws ResolverException;
67
68 /**
69 * Loads the class descriptor for the class instance specified. The use of this method is useful
70 * when no mapping is used, as happens when the domain classes hase been generated using the XML
71 * code generator (in which case instead of a mapping file class descriptor files will be
72 * generated).
73 *
74 * @param clazzes the classes for which the associated descriptor should be loaded.
75 * @throws ResolverException in case that resolving the Class fails fatally
76 */
77 void addClasses(final Class<?>[] clazzes) throws ResolverException;
78
79 /**
80 * Loads class descriptors from the package specified. The use of this method is useful when no
81 * mapping is used, as happens when the domain classes hase been generated using the XML code
82 * generator (in which case instead of a mapping file class descriptor files will be generated).
83 * <p>
84 * Please note that this functionality will work only if you provide the <tt>.castor.cdr</tt> file
85 * with your generated classes (as generated by the XML code generator).
86 * <p>
87 *
88 * @param packageName The package name for the (descriptor) classes
89 * @throws ResolverException If there's a problem loading class descriptors for the given package.
90 */
91 void addPackage(final String packageName) throws ResolverException;
92
93 /**
94 * Loads class descriptors from the packages specified. The use of this method is useful when no
95 * mapping is used, as happens when the domain classes hase been generated using the XML code
96 * generator (in which case instead of a mapping file class descriptor files will be generated).
97 * <p>
98 * Please note that this functionality will work only if you provide the <tt>.castor.cdr</tt>
99 * files with your generated classes (as generated by the XML code generator).
100 * <p>
101 *
102 * @param packageNames The package names for the (descriptor) classes
103 * @throws ResolverException If there's a problem loading class descriptors for the given package.
104 */
105 void addPackages(final String[] packageNames) throws ResolverException;
106
107 /**
108 * Sets an application-specific {@link XMLClassDescriptorResolver} instance.
109 *
110 * @param xmlClassDescriptorResolver the resolver to use
111 */
112 void setResolver(final XMLClassDescriptorResolver xmlClassDescriptorResolver);
113
114 /**
115 * To set properties for marshalling and unmarshalling behavior.
116 *
117 * @param propertyName name of the property to set
118 * @param value the value to set to
119 */
120 void setProperty(final String propertyName, final Object value);
121
122 /**
123 * To get the value of a specific property.
124 *
125 * @param propertyName name of the Property
126 * @return the value (Object) of the property
127 */
128 Object getProperty(final String propertyName);
129
130 /**
131 * Returns the naming conventions to use for the XML framework.
132 *
133 * @return the naming conventions to use for the XML framework
134 */
135 XMLNaming getXMLNaming();
136
137 /**
138 * Returns the naming conventions to use for the XML framework.
139 *
140 * @param classLoader the class loader to be used when instantiating a new naming instance
141 * @return the naming conventions to use for the XML framework
142 * @TODO: Joachim should be synchronized, shouldn't it be??
143 */
144 XMLNaming getXMLNaming(final ClassLoader classLoader); // -- getXMLNaming
145
146 /**
147 * The {@link JavaNaming} instance to be used.
148 *
149 * @return {@link JavaNaming} instance to be used.
150 */
151 JavaNaming getJavaNaming();
152
153 /**
154 * Return an XML document parser implementing the feature list specified in the configuration
155 * file.
156 *
157 * @return A suitable XML parser
158 */
159 Parser getParser();
160
161 /**
162 * Returns an XML document parser implementing the requested set of features. The feature list is
163 * a comma separated list of features that parser may or may not support. No errors are generated
164 * for unsupported features. If the feature list is not null, it overrides the default feature
165 * list specified in the configuration file, including validation and Namespaces.
166 *
167 * @param features The requested feature list, null for the defaults
168 * @return A suitable XML parser
169 */
170 Parser getParser(final String features);
171
172 /**
173 * Returns an XML document parser implementing the requested set of features. The feature list is
174 * a comma separated list of features that parser may or may not support. No errors are generated
175 * for unsupported features. If the feature list is not null, it overrides the default feature
176 * list specified in the configuration file, including validation and Namespaces.
177 *
178 * @return A suitable XML parser
179 */
180 XMLReader getXMLReader(); // -- getXMLReader
181
182 /**
183 * Returns an XML document parser implementing the requested set of features. The feature list is
184 * a comma separated list of features that parser may or may not support. No errors are generated
185 * for unsupported features. If the feature list is not null, it overrides the default feature
186 * list specified in the configuration file, including validation and Namespaces.
187 *
188 * @param features the name of feature to set
189 * @return A suitable XML parser
190 */
191 XMLReader getXMLReader(final String features); // -- getXMLReader
192
193 /**
194 * Returns the NodeType to use for Java primitives. A null value will be returned if no NodeType
195 * was specified, indicating the default NodeType should be used.
196 *
197 * @return the NodeType assigned to Java primitives, or null if no NodeType was specified.
198 **/
199 NodeType getPrimitiveNodeType(); // -- getPrimitiveNodeType
200
201 /**
202 * Returns a new instance of the specified Regular Expression Evaluator, or null if no validator
203 * was specified.
204 *
205 * @return the regular expression evaluator,
206 *
207 **/
208 RegExpEvaluator getRegExpEvaluator(); // -- getRegExpEvaluator
209
210 /**
211 * Returns a default serializer for producing an XML document. The caller can specify an
212 * alternative output format, may reuse this serializer across several streams, and may serialize
213 * both DOM and SAX events. If such control is not required, it is recommended to call one of the
214 * other two methods.
215 *
216 * @return A suitable serializer
217 */
218 Serializer getSerializer();
219
220 /**
221 * Returns the default OutputFormat for use with a Serializer.
222 *
223 * @return the default OutputFormat
224 **/
225 OutputFormat getOutputFormat(); // -- getOutputFormat
226
227 /**
228 * Returns a default serializer for producing an XML document to the designated output stream
229 * using the default serialization format.
230 *
231 * @param output The output stream
232 * @return A suitable serializer
233 * @throws IOException if instantiation of the serializer fails
234 */
235 DocumentHandler getSerializer(final OutputStream output) throws IOException;
236
237 /**
238 * Returns a default serializer for producing an XML document to the designated output stream
239 * using the default serialization format.
240 *
241 * @param output The output stream
242 * @return A suitable serializer
243 * @throws IOException if instantiation of serializer fails
244 */
245 DocumentHandler getSerializer(final Writer output) throws IOException;
246
247 /**
248 * To get the XMLClassdescriptorResolver instance hold in the context.
249 *
250 * @return the XMLClassdescriptorResolver instance hold in the context
251 */
252 XMLClassDescriptorResolver getXMLClassDescriptorResolver();
253
254 /**
255 * To get the Introspector assigned to this XMLContext.
256 *
257 * @return the Introspector assigned to this XMLContext
258 */
259 Introspector getIntrospector();
260
261 /**
262 * To get the XMLClassDescriptor resolver strategy to be used when resolving classes into class
263 * descriptors.
264 *
265 * @return the ResolverStrategy to use
266 */
267 ResolverStrategy getResolverStrategy();
268
269 /**
270 * To set the XMLClassDescriptor resolver strategy to be used.
271 *
272 * @param resolverStrategy the ResolverStrategy to use
273 */
274 void setResolverStrategy(final ResolverStrategy resolverStrategy);
275
276 /**
277 * To set the {@link MappingLoader} to be used in this Castor session.
278 *
279 * @param mappingLoader the {@link MappingLoader} to use
280 */
281 void setMappingLoader(final MappingLoader mappingLoader);
282
283 /**
284 * To get the {@link MappingLoader} specified to be used in this Castor session.
285 *
286 * @return the {@link MappingLoader} to use
287 */
288 MappingLoader getMappingLoader();
289
290 /**
291 * To set the {@link JavaNaming}?property.
292 *
293 * @param javaNaming the {@link JavaNaming} to use
294 */
295 void setJavaNaming(final JavaNaming javaNaming);
296
297 /**
298 * To set the {@link XMLNaming} property.
299 *
300 * @param xmlNaming the {@link XMLNaming} to use
301 */
302 abstract void setXMLNaming(final XMLNaming xmlNaming);
303
304 /**
305 * To set any boolean property.
306 *
307 * @param propertyName name of the property to set
308 * @param value boolean value to set
309 */
310 void setProperty(final String propertyName, final boolean value);
311
312 /**
313 * Providing access to Boolean properties of the configuration.
314 *
315 * @param propertyName name of the property
316 * @return null if property is not set or whichever value is set
317 */
318 Boolean getBooleanProperty(final String propertyName);
319
320 /**
321 * Providing access to String properties of the configuration.
322 *
323 * @param propertyName name of the property
324 * @return null if the property is not set or whichever value is set
325 */
326 String getStringProperty(final String propertyName);
327
328 /**
329 * To set the class loader to be used in all further marshalling, unmarshalling and other actions.
330 *
331 * @param classLoader the ClassLoader instance to use
332 */
333 void setClassLoader(final ClassLoader classLoader);
334
335 /**
336 * To set the {@link XMLClassDescriptorResolver} to be used. Be aware, that the
337 * XMLClassDescriptorResolver instance holds a descriptor cache!! Maybe change it to have the
338 * descriptor cache as part of the context?
339 *
340 * @param xmlClassDescriptorResolver the {@link XMLClassDescriptorResolver} to use
341 */
342 void setXMLClassDescriptorResolver(final XMLClassDescriptorResolver xmlClassDescriptorResolver);
343
344 /**
345 * To specify which {@link Introspector}?is to be used.
346 *
347 * @param introspector {@link Introspector} to be used
348 */
349 void setIntrospector(final Introspector introspector);
350
351 /**
352 * To get the ClassLoader to use for loading resources.
353 *
354 * @return the ClassLoader to use
355 */
356 ClassLoader getClassLoader();
357
358 /**
359 * Get lenient id validation flag.
360 *
361 * @return lenient id validation flag
362 */
363 boolean getLenientIdValidation();
364
365 /**
366 * Get lenient sequence order flag.
367 *
368 * @return lenient sequence order flag
369 */
370 boolean getLenientSequenceOrder();
371
372 /**
373 * Get load package mapping flag.
374 *
375 * @return load package mapping flag
376 */
377 Boolean getLoadPackageMapping();
378
379 /**
380 * To set the load package mapping flag.
381 *
382 * @param loadPackageMapping the load package mapping flag
383 */
384 void setLoadPackageMapping(final Boolean loadPackageMapping);
385
386 /**
387 * To get use-introspection flag.
388 *
389 * @return use-introspection flag
390 */
391 Boolean getUseIntrospector();
392
393 /**
394 * To set use-introspection flag.
395 *
396 * @param useIntrospector use-introspection flag
397 */
398 void setUseIntrospector(final Boolean useIntrospector);
399
400 /**
401 * To get marshalling-validation flag.
402 *
403 * @return marshalling-validation flag
404 */
405 boolean marshallingValidation();
406
407 /**
408 * To get strict-element flag.
409 *
410 * @return strict-element flag
411 */
412 boolean strictElements();
413
414 }