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