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