001/** 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.camel.impl.converter; 018 019import java.io.BufferedReader; 020import java.io.IOException; 021import java.io.InputStreamReader; 022import java.lang.reflect.Method; 023import java.net.URL; 024import java.nio.charset.Charset; 025import java.util.ArrayList; 026import java.util.Arrays; 027import java.util.Enumeration; 028import java.util.HashSet; 029import java.util.List; 030import java.util.Set; 031import java.util.StringTokenizer; 032import static java.lang.reflect.Modifier.isAbstract; 033import static java.lang.reflect.Modifier.isPublic; 034import static java.lang.reflect.Modifier.isStatic; 035 036import org.apache.camel.Converter; 037import org.apache.camel.Exchange; 038import org.apache.camel.FallbackConverter; 039import org.apache.camel.TypeConverter; 040import org.apache.camel.TypeConverterLoaderException; 041import org.apache.camel.spi.PackageScanClassResolver; 042import org.apache.camel.spi.TypeConverterLoader; 043import org.apache.camel.spi.TypeConverterRegistry; 044import org.apache.camel.util.CastUtils; 045import org.apache.camel.util.IOHelper; 046import org.apache.camel.util.ObjectHelper; 047import org.apache.camel.util.StringHelper; 048import org.slf4j.Logger; 049import org.slf4j.LoggerFactory; 050 051/** 052 * A class which will auto-discover {@link Converter} objects and methods to pre-load 053 * the {@link TypeConverterRegistry} of converters on startup. 054 * <p/> 055 * This implementation supports scanning for type converters in JAR files. The {@link #META_INF_SERVICES} 056 * contains a list of packages or FQN class names for {@link Converter} classes. The FQN class names 057 * is loaded first and directly by the class loader. 058 * <p/> 059 * The {@link PackageScanClassResolver} is being used to scan packages for {@link Converter} classes and 060 * this procedure is slower than loading the {@link Converter} classes directly by its FQN class name. 061 * Therefore its recommended to specify FQN class names in the {@link #META_INF_SERVICES} file. 062 * Likewise the procedure for scanning using {@link PackageScanClassResolver} may require custom implementations 063 * to work in various containers such as JBoss, OSGi, etc. 064 * 065 * @version 066 */ 067public class AnnotationTypeConverterLoader implements TypeConverterLoader { 068 public static final String META_INF_SERVICES = "META-INF/services/org/apache/camel/TypeConverter"; 069 private static final Logger LOG = LoggerFactory.getLogger(AnnotationTypeConverterLoader.class); 070 private static final Charset UTF8 = Charset.forName("UTF-8"); 071 protected PackageScanClassResolver resolver; 072 protected Set<Class<?>> visitedClasses = new HashSet<Class<?>>(); 073 protected Set<String> visitedURIs = new HashSet<String>(); 074 075 public AnnotationTypeConverterLoader(PackageScanClassResolver resolver) { 076 this.resolver = resolver; 077 } 078 079 @Override 080 public void load(TypeConverterRegistry registry) throws TypeConverterLoaderException { 081 String[] packageNames; 082 083 LOG.trace("Searching for {} services", META_INF_SERVICES); 084 try { 085 packageNames = findPackageNames(); 086 if (packageNames == null || packageNames.length == 0) { 087 throw new TypeConverterLoaderException("Cannot find package names to be used for classpath scanning for annotated type converters."); 088 } 089 } catch (Exception e) { 090 throw new TypeConverterLoaderException("Cannot find package names to be used for classpath scanning for annotated type converters.", e); 091 } 092 093 // if we only have camel-core on the classpath then we have already pre-loaded all its type converters 094 // but we exposed the "org.apache.camel.core" package in camel-core. This ensures there is at least one 095 // packageName to scan, which triggers the scanning process. That allows us to ensure that we look for 096 // META-INF/services in all the JARs. 097 if (packageNames.length == 1 && "org.apache.camel.core".equals(packageNames[0])) { 098 LOG.debug("No additional package names found in classpath for annotated type converters."); 099 // no additional package names found to load type converters so break out 100 return; 101 } 102 103 // now filter out org.apache.camel.core as its not needed anymore (it was just a dummy) 104 packageNames = filterUnwantedPackage("org.apache.camel.core", packageNames); 105 106 // filter out package names which can be loaded as a class directly so we avoid package scanning which 107 // is much slower and does not work 100% in all runtime containers 108 Set<Class<?>> classes = new HashSet<Class<?>>(); 109 packageNames = filterPackageNamesOnly(resolver, packageNames, classes); 110 if (!classes.isEmpty()) { 111 LOG.debug("Loaded " + classes.size() + " @Converter classes"); 112 } 113 114 // if there is any packages to scan and load @Converter classes, then do it 115 if (packageNames != null && packageNames.length > 0) { 116 LOG.trace("Found converter packages to scan: {}", packageNames); 117 Set<Class<?>> scannedClasses = resolver.findAnnotated(Converter.class, packageNames); 118 if (scannedClasses.isEmpty()) { 119 throw new TypeConverterLoaderException("Cannot find any type converter classes from the following packages: " + Arrays.asList(packageNames)); 120 } 121 LOG.debug("Found " + packageNames.length + " packages with " + scannedClasses.size() + " @Converter classes to load"); 122 classes.addAll(scannedClasses); 123 } 124 125 // load all the found classes into the type converter registry 126 for (Class<?> type : classes) { 127 if (LOG.isTraceEnabled()) { 128 LOG.trace("Loading converter class: {}", ObjectHelper.name(type)); 129 } 130 loadConverterMethods(registry, type); 131 } 132 133 // now clear the maps so we do not hold references 134 visitedClasses.clear(); 135 visitedURIs.clear(); 136 } 137 138 /** 139 * Filters the given list of packages and returns an array of <b>only</b> package names. 140 * <p/> 141 * This implementation will check the given list of packages, and if it contains a class name, 142 * that class will be loaded directly and added to the list of classes. This optimizes the 143 * type converter to avoid excessive file scanning for .class files. 144 * 145 * @param resolver the class resolver 146 * @param packageNames the package names 147 * @param classes to add loaded @Converter classes 148 * @return the filtered package names 149 */ 150 protected String[] filterPackageNamesOnly(PackageScanClassResolver resolver, String[] packageNames, Set<Class<?>> classes) { 151 if (packageNames == null || packageNames.length == 0) { 152 return packageNames; 153 } 154 155 // optimize for CorePackageScanClassResolver 156 if (resolver.getClassLoaders().isEmpty()) { 157 return packageNames; 158 } 159 160 // the filtered packages to return 161 List<String> packages = new ArrayList<String>(); 162 163 // try to load it as a class first 164 for (String name : packageNames) { 165 // must be a FQN class name by having an upper case letter 166 if (StringHelper.isClassName(name)) { 167 Class<?> clazz = null; 168 for (ClassLoader loader : resolver.getClassLoaders()) { 169 try { 170 clazz = ObjectHelper.loadClass(name, loader); 171 LOG.trace("Loaded {} as class {}", name, clazz); 172 classes.add(clazz); 173 // class founder, so no need to load it with another class loader 174 break; 175 } catch (Throwable e) { 176 // do nothing here 177 } 178 } 179 if (clazz == null) { 180 // ignore as its not a class (will be package scan afterwards) 181 packages.add(name); 182 } 183 } else { 184 // ignore as its not a class (will be package scan afterwards) 185 packages.add(name); 186 } 187 } 188 189 // return the packages which is not FQN classes 190 return packages.toArray(new String[packages.size()]); 191 } 192 193 /** 194 * Finds the names of the packages to search for on the classpath looking 195 * for text files on the classpath at the {@link #META_INF_SERVICES} location. 196 * 197 * @return a collection of packages to search for 198 * @throws IOException is thrown for IO related errors 199 */ 200 protected String[] findPackageNames() throws IOException { 201 Set<String> packages = new HashSet<String>(); 202 ClassLoader ccl = Thread.currentThread().getContextClassLoader(); 203 if (ccl != null) { 204 findPackages(packages, ccl); 205 } 206 findPackages(packages, getClass().getClassLoader()); 207 return packages.toArray(new String[packages.size()]); 208 } 209 210 protected void findPackages(Set<String> packages, ClassLoader classLoader) throws IOException { 211 Enumeration<URL> resources = classLoader.getResources(META_INF_SERVICES); 212 while (resources.hasMoreElements()) { 213 URL url = resources.nextElement(); 214 String path = url.getPath(); 215 if (!visitedURIs.contains(path)) { 216 // remember we have visited this uri so we wont read it twice 217 visitedURIs.add(path); 218 LOG.debug("Loading file {} to retrieve list of packages, from url: {}", META_INF_SERVICES, url); 219 BufferedReader reader = IOHelper.buffered(new InputStreamReader(url.openStream(), UTF8)); 220 try { 221 while (true) { 222 String line = reader.readLine(); 223 if (line == null) { 224 break; 225 } 226 line = line.trim(); 227 if (line.startsWith("#") || line.length() == 0) { 228 continue; 229 } 230 tokenize(packages, line); 231 } 232 } finally { 233 IOHelper.close(reader, null, LOG); 234 } 235 } 236 } 237 } 238 239 /** 240 * Tokenizes the line from the META-IN/services file using commas and 241 * ignoring whitespace between packages 242 */ 243 private void tokenize(Set<String> packages, String line) { 244 StringTokenizer iter = new StringTokenizer(line, ","); 245 while (iter.hasMoreTokens()) { 246 String name = iter.nextToken().trim(); 247 if (name.length() > 0) { 248 packages.add(name); 249 } 250 } 251 } 252 253 /** 254 * Loads all of the converter methods for the given type 255 */ 256 protected void loadConverterMethods(TypeConverterRegistry registry, Class<?> type) { 257 if (visitedClasses.contains(type)) { 258 return; 259 } 260 visitedClasses.add(type); 261 try { 262 Method[] methods = type.getDeclaredMethods(); 263 CachingInjector<?> injector = null; 264 265 for (Method method : methods) { 266 // this may be prone to ClassLoader or packaging problems when the same class is defined 267 // in two different jars (as is the case sometimes with specs). 268 if (ObjectHelper.hasAnnotation(method, Converter.class, true)) { 269 boolean allowNull = false; 270 if (method.getAnnotation(Converter.class) != null) { 271 allowNull = method.getAnnotation(Converter.class).allowNull(); 272 } 273 injector = handleHasConverterAnnotation(registry, type, injector, method, allowNull); 274 } else if (ObjectHelper.hasAnnotation(method, FallbackConverter.class, true)) { 275 boolean allowNull = false; 276 if (method.getAnnotation(FallbackConverter.class) != null) { 277 allowNull = method.getAnnotation(FallbackConverter.class).allowNull(); 278 } 279 injector = handleHasFallbackConverterAnnotation(registry, type, injector, method, allowNull); 280 } 281 } 282 283 Class<?> superclass = type.getSuperclass(); 284 if (superclass != null && !superclass.equals(Object.class)) { 285 loadConverterMethods(registry, superclass); 286 } 287 } catch (NoClassDefFoundError e) { 288 boolean ignore = false; 289 // does the class allow to ignore the type converter when having load errors 290 if (ObjectHelper.hasAnnotation(type, Converter.class, true)) { 291 if (type.getAnnotation(Converter.class) != null) { 292 ignore = type.getAnnotation(Converter.class).ignoreOnLoadError(); 293 } 294 } 295 // if we should ignore then only log at debug level 296 if (ignore) { 297 LOG.debug("Ignoring converter type: " + type.getCanonicalName() + " as a dependent class could not be found: " + e, e); 298 } else { 299 LOG.warn("Ignoring converter type: " + type.getCanonicalName() + " as a dependent class could not be found: " + e, e); 300 } 301 } 302 } 303 304 private CachingInjector<?> handleHasConverterAnnotation(TypeConverterRegistry registry, Class<?> type, 305 CachingInjector<?> injector, Method method, boolean allowNull) { 306 if (isValidConverterMethod(method)) { 307 int modifiers = method.getModifiers(); 308 if (isAbstract(modifiers) || !isPublic(modifiers)) { 309 LOG.warn("Ignoring bad converter on type: " + type.getCanonicalName() + " method: " + method 310 + " as a converter method is not a public and concrete method"); 311 } else { 312 Class<?> toType = method.getReturnType(); 313 if (toType.equals(Void.class)) { 314 LOG.warn("Ignoring bad converter on type: " + type.getCanonicalName() + " method: " 315 + method + " as a converter method returns a void method"); 316 } else { 317 Class<?> fromType = method.getParameterTypes()[0]; 318 if (isStatic(modifiers)) { 319 registerTypeConverter(registry, method, toType, fromType, 320 new StaticMethodTypeConverter(method, allowNull)); 321 } else { 322 if (injector == null) { 323 injector = new CachingInjector<Object>(registry, CastUtils.cast(type, Object.class)); 324 } 325 registerTypeConverter(registry, method, toType, fromType, 326 new InstanceMethodTypeConverter(injector, method, registry, allowNull)); 327 } 328 } 329 } 330 } else { 331 LOG.warn("Ignoring bad converter on type: " + type.getCanonicalName() + " method: " + method 332 + " as a converter method should have one parameter"); 333 } 334 return injector; 335 } 336 337 private CachingInjector<?> handleHasFallbackConverterAnnotation(TypeConverterRegistry registry, Class<?> type, 338 CachingInjector<?> injector, Method method, boolean allowNull) { 339 if (isValidFallbackConverterMethod(method)) { 340 int modifiers = method.getModifiers(); 341 if (isAbstract(modifiers) || !isPublic(modifiers)) { 342 LOG.warn("Ignoring bad fallback converter on type: " + type.getCanonicalName() + " method: " + method 343 + " as a fallback converter method is not a public and concrete method"); 344 } else { 345 Class<?> toType = method.getReturnType(); 346 if (toType.equals(Void.class)) { 347 LOG.warn("Ignoring bad fallback converter on type: " + type.getCanonicalName() + " method: " 348 + method + " as a fallback converter method returns a void method"); 349 } else { 350 if (isStatic(modifiers)) { 351 registerFallbackTypeConverter(registry, new StaticMethodFallbackTypeConverter(method, registry, allowNull), method); 352 } else { 353 if (injector == null) { 354 injector = new CachingInjector<Object>(registry, CastUtils.cast(type, Object.class)); 355 } 356 registerFallbackTypeConverter(registry, new InstanceMethodFallbackTypeConverter(injector, method, registry, allowNull), method); 357 } 358 } 359 } 360 } else { 361 LOG.warn("Ignoring bad fallback converter on type: " + type.getCanonicalName() + " method: " + method 362 + " as a fallback converter method should have one parameter"); 363 } 364 return injector; 365 } 366 367 protected void registerTypeConverter(TypeConverterRegistry registry, 368 Method method, Class<?> toType, Class<?> fromType, TypeConverter typeConverter) { 369 registry.addTypeConverter(toType, fromType, typeConverter); 370 } 371 372 protected boolean isValidConverterMethod(Method method) { 373 Class<?>[] parameterTypes = method.getParameterTypes(); 374 return (parameterTypes != null) && (parameterTypes.length == 1 375 || (parameterTypes.length == 2 && Exchange.class.isAssignableFrom(parameterTypes[1]))); 376 } 377 378 protected void registerFallbackTypeConverter(TypeConverterRegistry registry, TypeConverter typeConverter, Method method) { 379 boolean canPromote = false; 380 // check whether the annotation may indicate it can promote 381 if (method.getAnnotation(FallbackConverter.class) != null) { 382 canPromote = method.getAnnotation(FallbackConverter.class).canPromote(); 383 } 384 registry.addFallbackTypeConverter(typeConverter, canPromote); 385 } 386 387 protected boolean isValidFallbackConverterMethod(Method method) { 388 Class<?>[] parameterTypes = method.getParameterTypes(); 389 return (parameterTypes != null) && (parameterTypes.length == 3 390 || (parameterTypes.length == 4 && Exchange.class.isAssignableFrom(parameterTypes[1])) 391 && (TypeConverterRegistry.class.isAssignableFrom(parameterTypes[parameterTypes.length - 1]))); 392 } 393 394 /** 395 * Filters the given list of packages 396 * 397 * @param name the name to filter out 398 * @param packageNames the packages 399 * @return he packages without the given name 400 */ 401 protected static String[] filterUnwantedPackage(String name, String[] packageNames) { 402 // the filtered packages to return 403 List<String> packages = new ArrayList<String>(); 404 405 for (String s : packageNames) { 406 if (!name.equals(s)) { 407 packages.add(s); 408 } 409 } 410 411 return packages.toArray(new String[packages.size()]); 412 } 413 414}