Java does not feature native support for package contents inspection. There isn't also a convenient way to search for classes on a given package or Jar file. Other limitations include also find subpackages of a given package and even finding all the subfolders of a given folder. To preform this tasks a lot of boilerplate code must be written, and Resource Utilites aims to cover up this shortage.
Please refer to the Resource utilities Javadoc for the complete API specification.
There are two different options regarding the package classes search: one just finds the classes on the package and the other finds the classes on the packages and on all it's subpackages. Since both methods are similar in terms of paramters and return types, only the deep package search will be demonstrated. The other operates in the same fashion. The methods receive the name of the package to search (the top-level pacakage on the deep search method) and return a list of the package(s) class names as Strings.
Heres an usage example:
...
try {
List<String> deepClasses = ResourceUtils.getClassesInDeepPackage("pt.digitalis.utils.inspection");
for (String className : deepClasses)
System.out.println(className);
} catch (ResourceNotFoundException resourceNotFoundException) {
// Exception-handling code
}
...
The produced output is similar to this:
pt.digitalis.utils.inspection.exception.AuxiliaryOperationException pt.digitalis.utils.inspection.exception.InvalidResourceException pt.digitalis.utils.inspection.exception.ResourceNotFoundException pt.digitalis.utils.inspection.exception.TestExceptions pt.digitalis.utils.inspection.ClasspathUtils$1 pt.digitalis.utils.inspection.ClasspathUtils pt.digitalis.utils.inspection.ClasspathUtilsTest$1ClassFileFilter pt.digitalis.utils.inspection.ClasspathUtilsTest pt.digitalis.utils.inspection.MockUpClass pt.digitalis.utils.inspection.ReflectionUtils pt.digitalis.utils.inspection.ReflectionUtilsTest pt.digitalis.utils.inspection.ResourceUtils$FolderFilter pt.digitalis.utils.inspection.ResourceUtils pt.digitalis.utils.inspection.ResourceUtilsTest pt.digitalis.utils.inspection.AttributeAnnotation pt.digitalis.utils.inspection.ClasspathUtils$FilenameFilter pt.digitalis.utils.inspection.MethodAnnotation pt.digitalis.utils.inspection.TypeAnnotation
Note that the classes on the 'pt.digitalis.utils.inspection.exception' subpackage are captured as well.
If the getClassNamesInPackage(String) had been used the classes on the 'pt.digitalis.utils.inspection.exception' subpackage would not be captured.
Methods to find the names of classes of a given package on several folders or Jar files are also provided. As before, the methods operate in a similar fashion, so only one example will be given. The methods receive the name of the package and a list of folders (remember that a folder is of the File type in Java!) or Jar files and they both return a list with the given package class FQNs found on the given folder/Jar list.
This methods may be useful to find classes of a given package that are physically dispersed through several folders or jar files. Some project management tools (such as Maven!!) separate the test code from the application code. Albeit belonging to the same package the test code is stored on a different folder than the application code.
Here's an usage example of getClassNamesInFolders(String, List<File>):
...
try {
List<File> folders = new ArrayList<File>();
// Append path accordingly to the used OS
folders.add(new File("drive:\\path\\to\\folder"));
List<String> deepClasses = ResourceUtils.getClassNamesInFolders(INSPECTION_UTILS_PACKAGE_NAME, folders);
for (String deepClass : deepClasses)
System.out.println(deepClass);
} catch (ResourceNotFoundException resourceNotFoundException) {
// Exception-handling code...
}
...
The preceding code is expected to produce an output similar to this:
pt.digitalis.utils.inspection.ClasspathUtils$1 pt.digitalis.utils.inspection.ClasspathUtils pt.digitalis.utils.inspection.ClasspathUtilsTest$1ClassFileFilter pt.digitalis.utils.inspection.ClasspathUtilsTest pt.digitalis.utils.inspection.MockUpClass pt.digitalis.utils.inspection.ReflectionUtils pt.digitalis.utils.inspection.ReflectionUtilsTest pt.digitalis.utils.inspection.ResourceUtils$FolderFilter pt.digitalis.utils.inspection.ResourceUtils pt.digitalis.utils.inspection.ResourceUtilsTest pt.digitalis.utils.inspection.AttributeAnnotation pt.digitalis.utils.inspection.ClasspathUtils$1 pt.digitalis.utils.inspection.ClasspathUtils$FilenameFilter pt.digitalis.utils.inspection.ClasspathUtils pt.digitalis.utils.inspection.ClasspathUtilsTest$1ClassFileFilter pt.digitalis.utils.inspection.ClasspathUtilsTest pt.digitalis.utils.inspection.MethodAnnotation pt.digitalis.utils.inspection.MockUpClass pt.digitalis.utils.inspection.ReflectionUtils pt.digitalis.utils.inspection.ReflectionUtilsTest pt.digitalis.utils.inspection.ResourceUtils$FolderFilter pt.digitalis.utils.inspection.ResourceUtils pt.digitalis.utils.inspection.ResourceUtilsTest pt.digitalis.utils.inspection.TypeAnnotation
Finding a given package's resources in Java is the primordial example of boilerplate code. Moreover, this simple task forces the progammer to dive into Java hard core features (such as class loading) and low-level tasks (such as String parsing and the like). Fortunately, Resource Utilities API provides a method that hides all this complexity from the client programmer who just wants an easy way to get the resources. This method's name is getPackageResources(String). It receives the package name as argument and returns an enumerated type with the package's resources URLs.
Here's how to use it:
...
Enumeration<URL> resources = null;
try {
resources = ResourceUtils.getPackageResources("pt.digitalis.utils.inspection");
// More code here
} catch (ResourceNotFoundException resourceNotFoundException) {
// Exception-handling code...
}
...
Printing the contents of the resources variable would yield something like the following:
file:/X:/MyCode/digi-utils/target/classes/pt/digitalis/utils/inspection
To cope with Java cumbersome subfolder search mechanism, Resource Utilities offers the getSubfolders(File) method. It receives a folder (remember that a folder is of the File type in Java!) and returns a with all it's subfolders.
The following example show how to use this method:
...
try {
// Path structure may vary accordingly to the OS
File folder = new Folder("drive:\\path\\to\\top\\level\\folder");
List<String> subfolders = ResourceUtils.getSubfolders(folder);
// More code here
} catch (ResourceNotFoundException resourceNotFoundException) {
// Exception-handling code...
}
...
The output may vary depending on the passed folder and OS.
Finding a package subpackage's is not natively supported in Java and results in a great deal of awkward code. Resource Utilities answers this need with getSubpackages(String) method. The method returns a list with the names of all the subpackages of a package whose name was passed to the method as an argument.
Here's an usage example:
...
try {
List<String> subpackages = ResourceUtils.getSubpackages("pt.digitalis.utils.inspection");
for (String packageName : subpackages)
System.out.println(packageName);
} catch (ResourceNotFoundException resourceNotFoundException) {
// Exception-handling code here...
}
...
Since package 'pt.digitalis.utils.inspection' just contains one subpackage the output would just contain an entry:
pt.digitalis.utils.inspection.exception