View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  package org.apache.logging.log4j.core.config.plugins.util;
18  
19  import java.io.File;
20  import java.io.FileInputStream;
21  import java.io.FileNotFoundException;
22  import java.io.IOException;
23  import java.io.UnsupportedEncodingException;
24  import java.net.URI;
25  import java.net.URISyntaxException;
26  import java.net.URL;
27  import java.net.URLDecoder;
28  import java.nio.charset.StandardCharsets;
29  import java.util.Arrays;
30  import java.util.Collection;
31  import java.util.Enumeration;
32  import java.util.HashSet;
33  import java.util.List;
34  import java.util.Set;
35  import java.util.jar.JarEntry;
36  import java.util.jar.JarInputStream;
37  
38  import org.apache.logging.log4j.Logger;
39  import org.apache.logging.log4j.core.util.Loader;
40  import org.apache.logging.log4j.status.StatusLogger;
41  import org.osgi.framework.FrameworkUtil;
42  import org.osgi.framework.wiring.BundleWiring;
43  
44  /**
45   * <p>
46   * ResolverUtil is used to locate classes that are available in the/a class path and meet arbitrary conditions. The two
47   * most common conditions are that a class implements/extends another class, or that is it annotated with a specific
48   * annotation. However, through the use of the {@link Test} class it is possible to search using arbitrary conditions.
49   * </p>
50   *
51   * <p>
52   * A ClassLoader is used to locate all locations (directories and jar files) in the class path that contain classes
53   * within certain packages, and then to load those classes and check them. By default the ClassLoader returned by
54   * {@code Thread.currentThread().getContextClassLoader()} is used, but this can be overridden by calling
55   * {@link #setClassLoader(ClassLoader)} prior to invoking any of the {@code find()} methods.
56   * </p>
57   *
58   * <p>
59   * General searches are initiated by calling the {@link #find(ResolverUtil.Test, String...)} method and supplying a
60   * package name and a Test instance. This will cause the named package <b>and all sub-packages</b> to be scanned for
61   * classes that meet the test. There are also utility methods for the common use cases of scanning multiple packages for
62   * extensions of particular classes, or classes annotated with a specific annotation.
63   * </p>
64   *
65   * <p>
66   * The standard usage pattern for the ResolverUtil class is as follows:
67   * </p>
68   *
69   * <pre>
70   * ResolverUtil&lt;ActionBean&gt; resolver = new ResolverUtil&lt;ActionBean&gt;();
71   * resolver.findImplementation(ActionBean.class, pkg1, pkg2);
72   * resolver.find(new CustomTest(), pkg1);
73   * resolver.find(new CustomTest(), pkg2);
74   * Collection&lt;ActionBean&gt; beans = resolver.getClasses();
75   * </pre>
76   *
77   * <p>
78   * This class was copied and modified from Stripes - http://stripes.mc4j.org/confluence/display/stripes/Home
79   * </p>
80   */
81  public class ResolverUtil {
82      /** An instance of Log to use for logging in this class. */
83      private static final Logger LOGGER = StatusLogger.getLogger();
84  
85      private static final String VFSZIP = "vfszip";
86  
87      private static final String BUNDLE_RESOURCE = "bundleresource";
88  
89      /** The set of matches being accumulated. */
90      private final Set<Class<?>> classMatches = new HashSet<>();
91  
92      /** The set of matches being accumulated. */
93      private final Set<URI> resourceMatches = new HashSet<>();
94  
95      /**
96       * The ClassLoader to use when looking for classes. If null then the ClassLoader returned by
97       * Thread.currentThread().getContextClassLoader() will be used.
98       */
99      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 }