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