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.logging.log4j.core.config.plugins.util;
018
019import java.io.File;
020import java.io.FileInputStream;
021import java.io.FileNotFoundException;
022import java.io.IOException;
023import java.io.UnsupportedEncodingException;
024import java.net.URI;
025import java.net.URISyntaxException;
026import java.net.URL;
027import java.net.URLDecoder;
028import java.nio.charset.StandardCharsets;
029import java.util.Arrays;
030import java.util.Collection;
031import java.util.Enumeration;
032import java.util.HashSet;
033import java.util.List;
034import java.util.Set;
035import java.util.jar.JarEntry;
036import java.util.jar.JarInputStream;
037
038import org.apache.logging.log4j.Logger;
039import org.apache.logging.log4j.core.util.Loader;
040import org.apache.logging.log4j.status.StatusLogger;
041import org.osgi.framework.FrameworkUtil;
042import org.osgi.framework.wiring.BundleWiring;
043
044/**
045 * <p>
046 * ResolverUtil is used to locate classes that are available in the/a class path and meet arbitrary conditions. The two
047 * most common conditions are that a class implements/extends another class, or that is it annotated with a specific
048 * annotation. However, through the use of the {@link Test} class it is possible to search using arbitrary conditions.
049 * </p>
050 *
051 * <p>
052 * A ClassLoader is used to locate all locations (directories and jar files) in the class path that contain classes
053 * within certain packages, and then to load those classes and check them. By default the ClassLoader returned by
054 * {@code Thread.currentThread().getContextClassLoader()} is used, but this can be overridden by calling
055 * {@link #setClassLoader(ClassLoader)} prior to invoking any of the {@code find()} methods.
056 * </p>
057 *
058 * <p>
059 * General searches are initiated by calling the {@link #find(ResolverUtil.Test, String...)} method and supplying a
060 * package name and a Test instance. This will cause the named package <b>and all sub-packages</b> to be scanned for
061 * classes that meet the test. There are also utility methods for the common use cases of scanning multiple packages for
062 * extensions of particular classes, or classes annotated with a specific annotation.
063 * </p>
064 *
065 * <p>
066 * The standard usage pattern for the ResolverUtil class is as follows:
067 * </p>
068 *
069 * <pre>
070 * ResolverUtil&lt;ActionBean&gt; resolver = new ResolverUtil&lt;ActionBean&gt;();
071 * resolver.findImplementation(ActionBean.class, pkg1, pkg2);
072 * resolver.find(new CustomTest(), pkg1);
073 * resolver.find(new CustomTest(), pkg2);
074 * Collection&lt;ActionBean&gt; beans = resolver.getClasses();
075 * </pre>
076 *
077 * <p>
078 * This class was copied and modified from Stripes - http://stripes.mc4j.org/confluence/display/stripes/Home
079 * </p>
080 */
081public class ResolverUtil {
082    /** An instance of Log to use for logging in this class. */
083    private static final Logger LOGGER = StatusLogger.getLogger();
084
085    private static final String VFSZIP = "vfszip";
086
087    private static final String BUNDLE_RESOURCE = "bundleresource";
088
089    /** The set of matches being accumulated. */
090    private final Set<Class<?>> classMatches = new HashSet<>();
091
092    /** The set of matches being accumulated. */
093    private final Set<URI> resourceMatches = new HashSet<>();
094
095    /**
096     * The ClassLoader to use when looking for classes. If null then the ClassLoader returned by
097     * Thread.currentThread().getContextClassLoader() will be used.
098     */
099    private ClassLoader classloader;
100
101    /**
102     * Provides access to the classes discovered so far. If no calls have been made to any of the {@code find()}
103     * methods, this set will be empty.
104     *
105     * @return the set of classes that have been discovered.
106     */
107    public Set<Class<?>> getClasses() {
108        return classMatches;
109    }
110
111    /**
112     * Returns the matching resources.
113     * 
114     * @return A Set of URIs that match the criteria.
115     */
116    public Set<URI> getResources() {
117        return resourceMatches;
118    }
119
120    /**
121     * Returns the classloader that will be used for scanning for classes. If no explicit ClassLoader has been set by
122     * the calling, the context class loader will be used.
123     *
124     * @return the ClassLoader that will be used to scan for classes
125     */
126    public ClassLoader getClassLoader() {
127        return classloader != null ? classloader : (classloader = Loader.getClassLoader(ResolverUtil.class, null));
128    }
129
130    /**
131     * Sets an explicit ClassLoader that should be used when scanning for classes. If none is set then the context
132     * classloader will be used.
133     *
134     * @param aClassloader
135     *        a ClassLoader to use when scanning for classes
136     */
137    public void setClassLoader(final ClassLoader aClassloader) {
138        this.classloader = aClassloader;
139    }
140
141    /**
142     * Attempts to discover classes that pass the test. Accumulated classes can be accessed by calling
143     * {@link #getClasses()}.
144     *
145     * @param test
146     *        the test to determine matching classes
147     * @param packageNames
148     *        one or more package names to scan (including subpackages) for classes
149     */
150    public void find(final Test test, final String... packageNames) {
151        if (packageNames == null) {
152            return;
153        }
154
155        for (final String pkg : packageNames) {
156            findInPackage(test, pkg);
157        }
158    }
159
160    /**
161     * Scans for classes starting at the package provided and descending into subpackages. Each class is offered up to
162     * the Test as it is discovered, and if the Test returns true the class is retained. Accumulated classes can be
163     * fetched by calling {@link #getClasses()}.
164     *
165     * @param test
166     *        an instance of {@link Test} that will be used to filter classes
167     * @param packageName
168     *        the name of the package from which to start scanning for classes, e.g. {@code net.sourceforge.stripes}
169     */
170    public void findInPackage(final Test test, String packageName) {
171        packageName = packageName.replace('.', '/');
172        final ClassLoader loader = getClassLoader();
173        Enumeration<URL> urls;
174
175        try {
176            urls = loader.getResources(packageName);
177        } catch (final IOException ioe) {
178            LOGGER.warn("Could not read package: " + packageName, ioe);
179            return;
180        }
181
182        while (urls.hasMoreElements()) {
183            try {
184                final URL url = urls.nextElement();
185                final String urlPath = extractPath(url);
186
187                LOGGER.info("Scanning for classes in [" + urlPath + "] matching criteria: " + test);
188                // Check for a jar in a war in JBoss
189                if (VFSZIP.equals(url.getProtocol())) {
190                    final String path = urlPath.substring(0, urlPath.length() - packageName.length() - 2);
191                    final URL newURL = new URL(url.getProtocol(), url.getHost(), path);
192                    @SuppressWarnings("resource")
193                    final JarInputStream stream = new JarInputStream(newURL.openStream());
194                    try {
195                        loadImplementationsInJar(test, packageName, path, stream);
196                    } finally {
197                        close(stream, newURL);
198                    }
199                } else if (BUNDLE_RESOURCE.equals(url.getProtocol())) {
200                    loadImplementationsInBundle(test, packageName);
201                } else {
202                    final File file = new File(urlPath);
203                    if (file.isDirectory()) {
204                        loadImplementationsInDirectory(test, packageName, file);
205                    } else {
206                        loadImplementationsInJar(test, packageName, file);
207                    }
208                }
209            } catch (final IOException | URISyntaxException ioe) {
210                LOGGER.warn("could not read entries", ioe);
211            }
212        }
213    }
214
215    String extractPath(final URL url) throws UnsupportedEncodingException, URISyntaxException {
216        String urlPath = url.getPath(); // same as getFile but without the Query portion
217        // System.out.println(url.getProtocol() + "->" + urlPath);
218
219        // I would be surprised if URL.getPath() ever starts with "jar:" but no harm in checking
220        if (urlPath.startsWith("jar:")) {
221            urlPath = urlPath.substring(4);
222        }
223        // For jar: URLs, the path part starts with "file:"
224        if (urlPath.startsWith("file:")) {
225            urlPath = urlPath.substring(5);
226        }
227        // If it was in a JAR, grab the path to the jar
228        if (urlPath.indexOf('!') > 0) {
229            urlPath = urlPath.substring(0, urlPath.indexOf('!'));
230        }
231
232        // LOG4J2-445
233        // Finally, decide whether to URL-decode the file name or not...
234        final String protocol = url.getProtocol();
235        final List<String> neverDecode = Arrays.asList(VFSZIP, BUNDLE_RESOURCE);
236        if (neverDecode.contains(protocol)) {
237            return urlPath;
238        }
239        final String cleanPath = new URI(urlPath).getPath();
240        if (new File(cleanPath).exists()) {
241            // if URL-encoded file exists, don't decode it
242            return cleanPath;
243        }
244        return URLDecoder.decode(urlPath, StandardCharsets.UTF_8.name());
245    }
246
247    private void loadImplementationsInBundle(final Test test, final String packageName) {
248        final BundleWiring wiring = FrameworkUtil.getBundle(ResolverUtil.class).adapt(BundleWiring.class);
249        final Collection<String> list = wiring.listResources(packageName, "*.class",
250                BundleWiring.LISTRESOURCES_RECURSE);
251        for (final String name : list) {
252            addIfMatching(test, name);
253        }
254    }
255
256    /**
257     * Finds matches in a physical directory on a filesystem. Examines all files within a directory - if the File object
258     * is not a directory, and ends with <i>.class</i> the file is loaded and tested to see if it is acceptable
259     * according to the Test. Operates recursively to find classes within a folder structure matching the package
260     * structure.
261     *
262     * @param test
263     *        a Test used to filter the classes that are discovered
264     * @param parent
265     *        the package name up to this directory in the package hierarchy. E.g. if /classes is in the classpath and
266     *        we wish to examine files in /classes/org/apache then the values of <i>parent</i> would be
267     *        <i>org/apache</i>
268     * @param location
269     *        a File object representing a directory
270     */
271    private void loadImplementationsInDirectory(final Test test, final String parent, final File location) {
272        final File[] files = location.listFiles();
273        if (files == null) {
274            return;
275        }
276
277        StringBuilder builder;
278        for (final File file : files) {
279            builder = new StringBuilder();
280            builder.append(parent).append('/').append(file.getName());
281            final String packageOrClass = parent == null ? file.getName() : builder.toString();
282
283            if (file.isDirectory()) {
284                loadImplementationsInDirectory(test, packageOrClass, file);
285            } else if (isTestApplicable(test, file.getName())) {
286                addIfMatching(test, packageOrClass);
287            }
288        }
289    }
290
291    private boolean isTestApplicable(final Test test, final String path) {
292        return test.doesMatchResource() || path.endsWith(".class") && test.doesMatchClass();
293    }
294
295    /**
296     * Finds matching classes within a jar files that contains a folder structure matching the package structure. If the
297     * File is not a JarFile or does not exist a warning will be logged, but no error will be raised.
298     *
299     * @param test
300     *        a Test used to filter the classes that are discovered
301     * @param parent
302     *        the parent package under which classes must be in order to be considered
303     * @param jarFile
304     *        the jar file to be examined for classes
305     */
306    private void loadImplementationsInJar(final Test test, final String parent, final File jarFile) {
307        @SuppressWarnings("resource")
308        JarInputStream jarStream = null;
309        try {
310            jarStream = new JarInputStream(new FileInputStream(jarFile));
311            loadImplementationsInJar(test, parent, jarFile.getPath(), jarStream);
312        } catch (final FileNotFoundException ex) {
313            LOGGER.error("Could not search jar file '" + jarFile + "' for classes matching criteria: " + test
314                    + " file not found", ex);
315        } catch (final IOException ioe) {
316            LOGGER.error("Could not search jar file '" + jarFile + "' for classes matching criteria: " + test
317                    + " due to an IOException", ioe);
318        } finally {
319            close(jarStream, jarFile);
320        }
321    }
322
323    /**
324     * @param jarStream
325     * @param source
326     */
327    private void close(final JarInputStream jarStream, final Object source) {
328        if (jarStream != null) {
329            try {
330                jarStream.close();
331            } catch (final IOException e) {
332                LOGGER.error("Error closing JAR file stream for {}", source, e);
333            }
334        }
335    }
336
337    /**
338     * Finds matching classes within a jar files that contains a folder structure matching the package structure. If the
339     * File is not a JarFile or does not exist a warning will be logged, but no error will be raised.
340     *
341     * @param test
342     *        a Test used to filter the classes that are discovered
343     * @param parent
344     *        the parent package under which classes must be in order to be considered
345     * @param stream
346     *        The jar InputStream
347     */
348    private void loadImplementationsInJar(final Test test, final String parent, final String path,
349            final JarInputStream stream) {
350
351        try {
352            JarEntry entry;
353
354            while ((entry = stream.getNextJarEntry()) != null) {
355                final String name = entry.getName();
356                if (!entry.isDirectory() && name.startsWith(parent) && isTestApplicable(test, name)) {
357                    addIfMatching(test, name);
358                }
359            }
360        } catch (final IOException ioe) {
361            LOGGER.error("Could not search jar file '" + path + "' for classes matching criteria: " + test
362                    + " due to an IOException", ioe);
363        }
364    }
365
366    /**
367     * Add the class designated by the fully qualified class name provided to the set of resolved classes if and only if
368     * it is approved by the Test supplied.
369     *
370     * @param test
371     *        the test used to determine if the class matches
372     * @param fqn
373     *        the fully qualified name of a class
374     */
375    protected void addIfMatching(final Test test, final String fqn) {
376        try {
377            final ClassLoader loader = getClassLoader();
378            if (test.doesMatchClass()) {
379                final String externalName = fqn.substring(0, fqn.indexOf('.')).replace('/', '.');
380                if (LOGGER.isDebugEnabled()) {
381                    LOGGER.debug("Checking to see if class " + externalName + " matches criteria [" + test + ']');
382                }
383
384                final Class<?> type = loader.loadClass(externalName);
385                if (test.matches(type)) {
386                    classMatches.add(type);
387                }
388            }
389            if (test.doesMatchResource()) {
390                URL url = loader.getResource(fqn);
391                if (url == null) {
392                    url = loader.getResource(fqn.substring(1));
393                }
394                if (url != null && test.matches(url.toURI())) {
395                    resourceMatches.add(url.toURI());
396                }
397            }
398        } catch (final Throwable t) {
399            LOGGER.warn("Could not examine class '" + fqn, t);
400        }
401    }
402
403    /**
404     * A simple interface that specifies how to test classes to determine if they are to be included in the results
405     * produced by the ResolverUtil.
406     */
407    public interface Test {
408        /**
409         * Will be called repeatedly with candidate classes. Must return True if a class is to be included in the
410         * results, false otherwise.
411         * 
412         * @param type
413         *        The Class to match against.
414         * @return true if the Class matches.
415         */
416        boolean matches(Class<?> type);
417
418        /**
419         * Test for a resource.
420         * 
421         * @param resource
422         *        The URI to the resource.
423         * @return true if the resource matches.
424         */
425        boolean matches(URI resource);
426
427        boolean doesMatchClass();
428
429        boolean doesMatchResource();
430    }
431
432}