net.sf.mmm.util.resource.api

Interface ClasspathScanner

All Known Implementing Classes:

AbstractClasspathScanner, ClasspathScannerImpl

@ComponentSpecification
public interface ClasspathScanner

This is the interface for a component that scans the classpath for resources. It makes your classpath a browsable filesystem that allows to walk through all packages like directories and list their content.
ATTENTION:
On the first call of any of the getClasspathResource*() methods the entire classpath will be scanned and the result will be cached. This is an expensive operation. However, after the results are cached further invocations are relatively cheap. Please note that only the "directory structure" is kept in cache but not any content. Invocations to read file contents from the classpath will always return the recent data without caching. If you have a dynamic classpath where resources can be added at runtime see clearCaches(). If you create and initialize the implementation (manually or via Ioc) it shall not scan the classpath or build any caches before any of the actual getClasspathResource*() methods are invoked.

Since:

7.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
void	clearCaches() Evicts all cache data so that any further invocation of the other methods will rebuild the cached data from scratch.
BrowsableResource	getClasspathResource()
BrowsableResource	getClasspathResource(Package pkg)
BrowsableResource	getClasspathResource(String classpath)
Iterable<Class<?>>	getClasspathResourceClasses(Filter<String> classnameFilter, Filter<Class<?>> classFilter)
Iterable<? extends BrowsableResource>	getClasspathResourceFiles()
Iterable<? extends BrowsableResource>	getClasspathResourceFiles(Filter<? super BrowsableResource> filter)
String	getQualifiedName(DataResource classResource)
<T> Class<T>	loadClass(BrowsableResource classResource)

Method Detail

getClasspathResource

BrowsableResource getClasspathResource()

Returns:

the BrowsableResource for the root (or default) package.

getClasspathResource

BrowsableResource getClasspathResource(String classpath)

Parameters:

classpath - is the classpath location pointing to a Package or ClasspathResource.

Returns:

the BrowsableResource for the given classpath.

getClasspathResource

BrowsableResource getClasspathResource(Package pkg)

Parameters:

pkg - is the Package to get.

Returns:

the BrowsableResource pointing to the given package.

getClasspathResourceFiles

Iterable<? extends BrowsableResource> getClasspathResourceFiles()

Returns:

an Iterable with ALL existing file resources on the classpath.

getClasspathResourceFiles

Iterable<? extends BrowsableResource> getClasspathResourceFiles(Filter<? super BrowsableResource> filter)

Parameters:

filter - decides which file resources to accept. Please note that the name of the filtered resources will end with ".class" in case of a Class.

Returns:

an Iterable with all resource files on the classpath accepted by the given filter.

getClasspathResourceClasses

Iterable<Class<?>> getClasspathResourceClasses(Filter<String> classnameFilter,
                                               Filter<Class<?>> classFilter)

Parameters:

classnameFilter - a Filter used to filter by qualified classname (to prevent unnecessary classloading).

classFilter - a Filter used to filter the Classes that have passed the classnameFilter and should be returned.

Returns:

an Iterable with the accepted classes.

Since:

7.3.0

getQualifiedName

String getQualifiedName(DataResource classResource)

Parameters:

classResource - a DataResource that identifies a Java *.class file or a Package from your classpath. Should be retrieved from this ClasspathScanner.

Returns:

the corresponding qualified class name or package name. Will be null in case the given DataResource is not pointing to a Class or Package.

Since:

7.3.0

loadClass

<T> Class<T> loadClass(BrowsableResource classResource)
                throws IllegalArgumentException

Type Parameters:

T - the generic type of the returned Class for simplistic usage.

Parameters:

classResource - a BrowsableResource that identifies a Java *.class file from your classpath. Should be retrieved from this ClasspathScanner.

Returns:

the loaded Class.

Throws:

IllegalArgumentException - if the given BrowsableResource does not point to a *.class file.

Since:

7.3.0

clearCaches

void clearCaches()

Evicts all cache data so that any further invocation of the other methods will rebuild the cached data from scratch.
ATTENTION:
Using this method can be very expensive for subsequent calls. A regular Java application has a static classpath so this method does not make any sense. Only use this method if you have dynamic class-loaders and you are fully aware of performance implications.