1 /**
2 * Redistribution and use of this software and associated documentation
3 * ("Software"), with or without modification, are permitted provided that the
4 * following conditions are met:
5 *
6 * 1. Redistributions of source code must retain copyright statements and
7 * notices. Redistributions must also contain a copy of this document.
8 *
9 * 2. Redistributions in binary form must reproduce the above copyright notice,
10 * this list of conditions and the following disclaimer in the documentation
11 * and/or other materials provided with the distribution.
12 *
13 * 3. The name "Exolab" must not be used to endorse or promote products derived
14 * from this Software without prior written permission of Intalio, Inc. For
15 * written permission, please contact info@exolab.org.
16 *
17 * 4. Products derived from this Software may not be called "Exolab" nor may
18 * "Exolab" appear in their names without prior written permission of Intalio,
19 * Inc. Exolab is a registered trademark of Intalio, Inc.
20 *
21 * 5. Due credit should be given to the Exolab Project (http://www.exolab.org/).
22 *
23 * THIS SOFTWARE IS PROVIDED BY INTALIO, INC. AND CONTRIBUTORS ``AS IS'' AND ANY
24 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26 * DISCLAIMED. IN NO EVENT SHALL INTALIO, INC. OR ITS CONTRIBUTORS BE LIABLE FOR
27 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
29 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
30 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
31 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 *
34 * Copyright 1999 (C) Intalio, Inc. All Rights Reserved.
35 *
36 * This file was originally developed by Keith Visco during the course of
37 * employment at Intalio Inc. All portions of this file developed by Keith Visco
38 * after Jan 19 2005 are Copyright (C) 2005 Keith Visco. All Rights Reserved.
39 *
40 * $Id: ClassDescriptorResolver.java 5951 2006-05-30 22:18:48Z bsnyder $
41 */
42
43 package org.exolab.castor.xml;
44
45 import java.util.Iterator;
46
47 import org.castor.xml.InternalContext;
48 import org.exolab.castor.mapping.ClassDescriptor;
49 import org.exolab.castor.xml.util.ResolverStrategy;
50
51 /**
52 * An interface for finding or "resolving" XMLClassDescriptor classes.
53 *
54 * <BR/> <B>Note:</B> This interface is used by the marshalling Framework for
55 * resolving XMLClassDescriptors for non-primitive types. There are no
56 * guarantees that this class will be called for java native classes.
57 *
58 * @author <a href="mailto:keith AT kvisco DOT com">Keith Visco</a>
59 * @version $Revision: 5951 $ $Date: 2005-02-28 17:41:38 -0700 (Mon, 28 Feb
60 * 2005) $
61 */
62 public interface XMLClassDescriptorResolver extends ClassDescriptorResolver {
63
64 /**
65 * To set the XMLContext to be used.
66 *
67 * @param xmlContext
68 * the XMLContext to be used
69 */
70 void setInternalContext(final InternalContext xmlContext);
71
72 /**
73 * Enables or disables introspection. Introspection is enabled by default.
74 *
75 * @param enable
76 * a flag to indicate whether or not introspection is allowed.
77 */
78 void setUseIntrospection(final boolean enable);
79
80 /**
81 * Sets whether or not to look for and load package specific mapping files
82 * (".castor.xml").
83 *
84 * @param loadPackageMappings
85 * a boolean that enables or disables the loading of package
86 * specific mapping files
87 */
88 void setLoadPackageMappings(final boolean loadPackageMappings);
89
90 /**
91 * Sets the ClassLoader to use when loading class descriptors.
92 *
93 * @param loader
94 * the ClassLoader to use
95 */
96 void setClassLoader(ClassLoader loader);
97
98 /**
99 * The resolver strategy to use for class and package resolving. Will set
100 * the current attributes into the new strategy.
101 *
102 * @param resolverStrategy
103 * the ResolverStrategy to use for resolve calls
104 */
105 void setResolverStrategy(final ResolverStrategy resolverStrategy);
106
107 /**
108 * To set the Introspector to be used. It is stored as attribute of resolver
109 * and set as property into the current strategy.
110 *
111 * @param introspector
112 * the Introspector to use
113 */
114 void setIntrospector(final Introspector introspector);
115
116 /**
117 * Returns the XMLClassDescriptor for the given class name.
118 *
119 * @param className
120 * the class name to find the XMLClassDescriptor for
121 * @return the XMLClassDescriptor for the given class name
122 * @throws ResolverException in case that resolving fails unrecoverable
123 */
124 XMLClassDescriptor resolve(String className) throws ResolverException;
125
126 /**
127 * Returns the XMLClassDescriptor for the given class name.
128 *
129 * @param className
130 * the class name to find the XMLClassDescriptor for
131 * @param loader
132 * the ClassLoader to use
133 * @return the XMLClassDescriptor for the given class name
134 * @throws ResolverException in case that resolving fails unrecoverable
135 */
136 XMLClassDescriptor resolve(String className, ClassLoader loader) throws ResolverException;
137
138 /**
139 * Returns the first XMLClassDescriptor that matches the given XML name and
140 * namespaceURI. Null is returned if no descriptor can be found.
141 *
142 * @param xmlName
143 * The class name to find the XMLClassDescriptor for.
144 * @param namespaceURI
145 * The namespace URI to identify the XMLClassDescriptor.
146 * @param loader
147 * The ClassLoader to use.
148 * @return The XMLClassDescriptor for the given XML name.
149 * @throws ResolverException in case that resolving fails unrecoverable
150 */
151 XMLClassDescriptor resolveByXMLName(String xmlName, String namespaceURI, ClassLoader loader)
152 throws ResolverException;
153
154 /**
155 * Returns an enumeration of XMLClassDescriptor objects that match the given
156 * xml name.
157 *
158 * @param xmlName
159 * The class name to find the XMLClassDescriptor for.
160 * @param namespaceURI
161 * The namespace URI to identify the XMLClassDescriptor.
162 * @param loader
163 * The ClassLoader to use.
164 * @return An Iterator of XMLClassDescriptor objects.
165 * @throws ResolverException in case that resolving fails unrecoverable
166 */
167 Iterator<ClassDescriptor> resolveAllByXMLName(String xmlName, String namespaceURI,
168 ClassLoader loader) throws ResolverException;
169
170 /**
171 * Loads the class descriptor for the class instance specified. The use of
172 * this method is useful when no mapping is used, as happens when the domain
173 * classes hase been generated using the XML code generator (in which case
174 * instead of a mapping file class descriptor files will be generated).
175 *
176 * @param className
177 * Name of the class for which the associated descriptor should
178 * be loaded.
179 * @throws ResolverException
180 * If there's an unrecoverable problem with resolving a certain
181 * class.
182 */
183 void addClass(final String className) throws ResolverException;
184
185 /**
186 * Loads the class descriptors for the class instances specified. The use of
187 * this method is useful when no mapping is used, as happens when the domain
188 * classes hase been generated using the XML code generator (in which case
189 * instead of a mapping file class descriptor files will be generated).
190 *
191 * @param classNames
192 * Names of the classes for which the associated descriptors
193 * should be loaded.
194 * @throws ResolverException
195 * If there's an unrecoverable problem with resolving a certain
196 * class.
197 */
198 void addClasses(final String[] classNames) throws ResolverException;
199
200 /**
201 * Loads the class descriptor for the class instance specified. The use of
202 * this method is useful when no mapping is used, as happens when the domain
203 * classes have been generated using the XML code generator (in which case
204 * instead of a mapping file class descriptor files will be generated).
205 *
206 * @param clazz
207 * Class for which the associated descriptor should be loaded.
208 * @throws ResolverException
209 * If there's an unrecoverable problem with resolving a certain
210 * class.
211 */
212 void addClass(final Class<?> clazz) throws ResolverException;
213
214 /**
215 * Loads the class descriptors for the class instances specified. The use of
216 * this method is useful when no mapping is used, as happens when the domain
217 * classes hase been generated using the XML code generator (in which case
218 * instead of a mapping file class descriptor files will be generated).
219 *
220 * @param clazzes
221 * Classes for which the associated descriptors should be loaded.
222 * @throws ResolverException
223 * If there's an unrecoverable problem with resolving a certain
224 * class.
225 */
226 void addClasses(final Class<?>[] clazzes) throws ResolverException;
227
228 /**
229 * Loads class descriptors from the package specified. The use of this
230 * method is useful when no mapping is used, as happens when the domain
231 * classes hase been generated using the XML code generator (in which case
232 * instead of a mapping file class descriptor files will be generated).
233 * <p>
234 * Please note that this functionality will work only if you provide the
235 * <tt>.castor.cdr</tt> file with your generated classes (as generated by
236 * the XML code generator).
237 * <p>
238 *
239 * @param packageName
240 * The package name for the (descriptor) classes
241 * @throws ResolverException
242 * If there's a problem loading class descriptors for the given
243 * package.
244 */
245 void addPackage(final String packageName) throws ResolverException;
246
247 /**
248 * Loads class descriptors from the packages specified. The use of this
249 * method is useful when no mapping is used, as happens when the domain
250 * classes hase been generated using the XML code generator (in which case
251 * instead of a mapping file class descriptor files will be generated).
252 * <p>
253 * Please note that this functionality will work only if you provide the
254 * <tt>.castor.cdr</tt> files with your generated classes (as generated by
255 * the XML code generator).
256 * <p>
257 *
258 * @param packageNames
259 * The package names for the (descriptor) classes
260 * @throws ResolverException
261 * If there's a problem loading class descriptors for the given
262 * package.
263 */
264 void addPackages(final String[] packageNames) throws ResolverException;
265
266 /**
267 * Loads class descriptors from the package specified. The use of this
268 * method is useful when no mapping is used, as happens when the domain
269 * classes hase been generated using the XML code generator (in which case
270 * instead of a mapping file class descriptor files will be generated).
271 * <p>
272 * Please note that this functionality will work only if you provide the
273 * <tt>.castor.cdr</tt> file with your generated classes (as generated by
274 * the XML code generator).
275 * <p>
276 *
277 * @param packageName
278 * The package name for the (descriptor) classes
279 * @throws ResolverException
280 * If there's a problem loading class descriptors for the given
281 * package.
282 * @deprecated Please use e.g. #addPackage(String) instead.
283 */
284 void loadClassDescriptors(final String packageName) throws ResolverException;
285
286 /**
287 * To clear the descriptor cache.
288 * @since 1.1.3
289 */
290 void cleanDescriptorCache();
291
292 } // -- ClassDescriptorResolver