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<ActionBean> resolver = new ResolverUtil<ActionBean>(); 071 * resolver.findImplementation(ActionBean.class, pkg1, pkg2); 072 * resolver.find(new CustomTest(), pkg1); 073 * resolver.find(new CustomTest(), pkg2); 074 * Collection<ActionBean> 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}