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