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 classloader
135     *        a ClassLoader to use when scanning for classes
136     */
137    public void setClassLoader(final ClassLoader classloader) {
138        this.classloader = classloader;
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 ioe) {
210                LOGGER.warn("could not read entries", ioe);
211            } catch (final URISyntaxException e) {
212                LOGGER.warn("could not read entries", e);
213            }
214        }
215    }
216
217    String extractPath(final URL url) throws UnsupportedEncodingException, URISyntaxException {
218        String urlPath = url.getPath(); // same as getFile but without the Query portion
219        // System.out.println(url.getProtocol() + "->" + urlPath);
220
221        // I would be surprised if URL.getPath() ever starts with "jar:" but no harm in checking
222        if (urlPath.startsWith("jar:")) {
223            urlPath = urlPath.substring(4);
224        }
225        // For jar: URLs, the path part starts with "file:"
226        if (urlPath.startsWith("file:")) {
227            urlPath = urlPath.substring(5);
228        }
229        // If it was in a JAR, grab the path to the jar
230        if (urlPath.indexOf('!') > 0) {
231            urlPath = urlPath.substring(0, urlPath.indexOf('!'));
232        }
233
234        // LOG4J2-445
235        // Finally, decide whether to URL-decode the file name or not...
236        final String protocol = url.getProtocol();
237        final List<String> neverDecode = Arrays.asList(VFSZIP, BUNDLE_RESOURCE);
238        if (neverDecode.contains(protocol)) {
239            return urlPath;
240        }
241        final String cleanPath = new URI(urlPath).getPath();
242        if (new File(cleanPath).exists()) {
243            // if URL-encoded file exists, don't decode it
244            return cleanPath;
245        }
246        return URLDecoder.decode(urlPath, StandardCharsets.UTF_8.name());
247    }
248
249    private void loadImplementationsInBundle(final Test test, final String packageName) {
250        final BundleWiring wiring = FrameworkUtil.getBundle(ResolverUtil.class).adapt(BundleWiring.class);
251        final Collection<String> list = wiring.listResources(packageName, "*.class",
252                BundleWiring.LISTRESOURCES_RECURSE);
253        for (final String name : list) {
254            addIfMatching(test, name);
255        }
256    }
257
258    /**
259     * Finds matches in a physical directory on a filesystem. Examines all files within a directory - if the File object
260     * is not a directory, and ends with <i>.class</i> the file is loaded and tested to see if it is acceptable
261     * according to the Test. Operates recursively to find classes within a folder structure matching the package
262     * structure.
263     *
264     * @param test
265     *        a Test used to filter the classes that are discovered
266     * @param parent
267     *        the package name up to this directory in the package hierarchy. E.g. if /classes is in the classpath and
268     *        we wish to examine files in /classes/org/apache then the values of <i>parent</i> would be
269     *        <i>org/apache</i>
270     * @param location
271     *        a File object representing a directory
272     */
273    private void loadImplementationsInDirectory(final Test test, final String parent, final File location) {
274        final File[] files = location.listFiles();
275        if (files == null) {
276            return;
277        }
278
279        StringBuilder builder;
280        for (final File file : files) {
281            builder = new StringBuilder();
282            builder.append(parent).append('/').append(file.getName());
283            final String packageOrClass = parent == null ? file.getName() : builder.toString();
284
285            if (file.isDirectory()) {
286                loadImplementationsInDirectory(test, packageOrClass, file);
287            } else if (isTestApplicable(test, file.getName())) {
288                addIfMatching(test, packageOrClass);
289            }
290        }
291    }
292
293    private boolean isTestApplicable(final Test test, final String path) {
294        return test.doesMatchResource() || path.endsWith(".class") && test.doesMatchClass();
295    }
296
297    /**
298     * Finds matching classes within a jar files that contains a folder structure matching the package structure. If the
299     * File is not a JarFile or does not exist a warning will be logged, but no error will be raised.
300     *
301     * @param test
302     *        a Test used to filter the classes that are discovered
303     * @param parent
304     *        the parent package under which classes must be in order to be considered
305     * @param jarFile
306     *        the jar file to be examined for classes
307     */
308    private void loadImplementationsInJar(final Test test, final String parent, final File jarFile) {
309        @SuppressWarnings("resource")
310        JarInputStream jarStream = null;
311        try {
312            jarStream = new JarInputStream(new FileInputStream(jarFile));
313            loadImplementationsInJar(test, parent, jarFile.getPath(), jarStream);
314        } catch (final FileNotFoundException ex) {
315            LOGGER.error("Could not search jar file '" + jarFile + "' for classes matching criteria: " + test
316                    + " file not found", ex);
317        } catch (final IOException ioe) {
318            LOGGER.error("Could not search jar file '" + jarFile + "' for classes matching criteria: " + test
319                    + " due to an IOException", ioe);
320        } finally {
321            close(jarStream, jarFile);
322        }
323    }
324
325    /**
326     * @param jarStream
327     * @param source
328     */
329    private void close(final JarInputStream jarStream, final Object source) {
330        if (jarStream != null) {
331            try {
332                jarStream.close();
333            } catch (final IOException e) {
334                LOGGER.error("Error closing JAR file stream for {}", source, e);
335            }
336        }
337    }
338
339    /**
340     * Finds matching classes within a jar files that contains a folder structure matching the package structure. If the
341     * File is not a JarFile or does not exist a warning will be logged, but no error will be raised.
342     *
343     * @param test
344     *        a Test used to filter the classes that are discovered
345     * @param parent
346     *        the parent package under which classes must be in order to be considered
347     * @param stream
348     *        The jar InputStream
349     */
350    private void loadImplementationsInJar(final Test test, final String parent, final String path,
351            final JarInputStream stream) {
352
353        try {
354            JarEntry entry;
355
356            while ((entry = stream.getNextJarEntry()) != null) {
357                final String name = entry.getName();
358                if (!entry.isDirectory() && name.startsWith(parent) && isTestApplicable(test, name)) {
359                    addIfMatching(test, name);
360                }
361            }
362        } catch (final IOException ioe) {
363            LOGGER.error("Could not search jar file '" + path + "' for classes matching criteria: " + test
364                    + " due to an IOException", ioe);
365        }
366    }
367
368    /**
369     * Add the class designated by the fully qualified class name provided to the set of resolved classes if and only if
370     * it is approved by the Test supplied.
371     *
372     * @param test
373     *        the test used to determine if the class matches
374     * @param fqn
375     *        the fully qualified name of a class
376     */
377    protected void addIfMatching(final Test test, final String fqn) {
378        try {
379            final ClassLoader loader = getClassLoader();
380            if (test.doesMatchClass()) {
381                final String externalName = fqn.substring(0, fqn.indexOf('.')).replace('/', '.');
382                if (LOGGER.isDebugEnabled()) {
383                    LOGGER.debug("Checking to see if class " + externalName + " matches criteria [" + test + ']');
384                }
385
386                final Class<?> type = loader.loadClass(externalName);
387                if (test.matches(type)) {
388                    classMatches.add(type);
389                }
390            }
391            if (test.doesMatchResource()) {
392                URL url = loader.getResource(fqn);
393                if (url == null) {
394                    url = loader.getResource(fqn.substring(1));
395                }
396                if (url != null && test.matches(url.toURI())) {
397                    resourceMatches.add(url.toURI());
398                }
399            }
400        } catch (final Throwable t) {
401            LOGGER.warn("Could not examine class '" + fqn, t);
402        }
403    }
404
405    /**
406     * A simple interface that specifies how to test classes to determine if they are to be included in the results
407     * produced by the ResolverUtil.
408     */
409    public interface Test {
410        /**
411         * Will be called repeatedly with candidate classes. Must return True if a class is to be included in the
412         * results, false otherwise.
413         * 
414         * @param type
415         *        The Class to match against.
416         * @return true if the Class matches.
417         */
418        boolean matches(Class<?> type);
419
420        /**
421         * Test for a resource.
422         * 
423         * @param resource
424         *        The URI to the resource.
425         * @return true if the resource matches.
426         */
427        boolean matches(URI resource);
428
429        boolean doesMatchClass();
430
431        boolean doesMatchResource();
432    }
433
434}