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}