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