Provide an API call that returns a listing of all the files in a deployment. --[jira] https://issues.jboss.org/browse/PRODMGT-286
David M Lloyd's etherpad content: http://etherpad.corp.redhat.com/RYYiDJqQz6 Pasting contents here in case it disappears. :-) Existing stuff is normal, my ideas are in bold, notes are in italics ... Class Loading and Modules Introduction Overview of Class Loading and Modules Class Loading Modules Module Dependencies Class Loading in Deployments Class Loading Precedence Dynamic Module Naming jboss-deployment-structure.xml Add an Explicit Module Dependency to a Deployment Generate MANIFEST.MF entries using Maven Prevent a Module Being Implicitly Loaded Exclude a Subsystem from a Deployment Use the Class Loader Programmatically in a Deployment <--- New from here on Loading Classes and Resources in a Deployment Including examples: Using Class.forName to load and initialize clases Finding all resources with a given name Loading a class file from the class loader ======= Using Class.forName to load and initialize clases When using the Class.forName() method, it is recommended that you avoid the one-argument form, and instead use the three-argument form. You will typically specify your own class' class loader (either using YourClass.class.getClassLoader() syntax or simply getClass().getClassLoader()). This has the advantage of not requiring the JVM to examine the call stack to determine the class loader to use, and in addition, it allows you to decide whether you want the target class to be initialized on load. ======= Finding all resources with a given name If you know the name and path of a resource, the best way to load it directly is using the standard JDK Class or ClassLoader API. If it is a single resource which is in the same directory as your class or another class in your deployment, you may use the Class getResourceAsStream() method like this: InputStream stream = MyClass.class.getResourceAsStream("resourcename"); If you are looking for all instances of a single resource that are visible to your deployment's class loader, the appropriate method to call is on ClassLoader: URL[] urls = MyClass.class.getClassLoader().getResources("full/resource/path"); The array of URLs may be traversed to open each stream in turn using its openStream() method. (**note: While it is possible to use the openConnection() and related methods on these URL instances, it is not necessary as the classes will all be loaded from local storage; thus it is encouraged to simply deal with streams to minimize code complexity.) ======= Loading a class file from the class loader To load the class file which corresponds to a given loaded class, typically you can use this syntax: InputStream stream = YourClass.class.getResourceAsStream(YourClass.class.getSimpleName() + ".class"); If the class is not yet loaded, you generally must go to the class loader and translate the path: InputStream stream = YourClass.class.getClassLoader().getResourceAsStream("the.class.name".replace('.', '/') + ".class"); ======= Iterating Resources in a Deployment Including examples: Simple listing of resources within deployment and within all imports Finding all resources that match a pattern ======= Simple listing of resources within deployment and within all imports Sometimes it is not enough to look up resources by exact path; for example, the exact path may not be known or there may be more than one file name that must be examined in an y given path. In this case, the JBoss Modules library (Dependency: org.jboss.modules) provides several APIs for iterating all deployment resources. Note that while this gives increased flexibility, it will also run much more slowly than a direct path lookup. Resources in a deployment can be iterated by utilizing one of two methods. The first method will iterate all of the resources found in a single module (i.e. deployment): -- org.jboss.modules.ModuleClassLoader#iterateResources(String startName,boolean recurse) The ModuleClassLoader#iterateResources method iterates the resources within a single module using ModuleClassLoader. This method takes two arguments: a starting directory name to search, and a boolean that specifies whether it should recurse into subdirectories. For example: ModuleClassLoader mcl = (ModuleClassLoader) TargetClass.class.getClassLoader(); Iterator<Resource> mclResources = mcl.iterateResources("bin",true); The resultant iterator may be used to examine each match in turn and easily query its name and size (if available), and open a readable stream or acquire a URL for the resource. -- org.jboss.modules.Module#iterateResources(PathFilter) The Module#iterateResources method iterates all the resources in the module, as well as all the resources that are imported into that module. As a result, it will return a much larger set than the previous method. This method requires an argument which is a filter that narrows down the result to a specific pattern, or alternatively PathFilters.acceptAll() can be supplied to return the entire set. For example: ModuleClassLoader mcl = (ModuleClassLoader) TargetClass.class.getClassLoader(); Module m = mcl.getModule(); Interator<Resource> mResources = m.iterateResources(PathFilters.acceptAll()); ======= Finding all resources that match a pattern If you are attempting to find only specific resources within your deployment or within your deployment's full import set, you may wish to filter the resource iteration. The JBoss Modules filtering APIs give you several tools to accomplish this. When examining the full set of dependencies, the Module#iterateResources method's PathFilter parameter can be used to check the name of each resource for a match. When looking only in the deployment using ModuleClassLoader#iterateResources however, the resultant iterator must be filtered using additional methods. The PathFilters#filtered() method provides a filtered view of a resource iterator that can be used in this case. There are several useful PathFilter implementations that may be used. The PathFilters class includes many static methods to create and compose filters that perform various functions, including finding child paths or exact matches, or matching an Ant-style "glob" pattern. ======= Class Loading and Subdeployments Modules and Class Loading in Enterprise Archives Subdeployment Class Loader Isolation Disable Subdeployment Class Loader Isolation Within a EAR Reference Implicit Module Dependencies Included Modules JBoss Deployment Structure Deployment Descriptor Reference This is the related bug: https://bugzilla.redhat.com/show_bug.cgi?id=999663
Created topic 24376: Programmatically Load Classes and Resources in a Deployment Still need to add 'Iterating Resources in a Deployment'
JavaDoc for JBoss Modules: http://docs.jboss.org/jbossmodules/1.2.0.Final/api/
Created topic 24377: Programmatically Iterate Resources in a Deployment
Modified topic 14875, the CSP map for the Development Guide for 6.2 as follows: Exclude a Subsystem from a Deployment [11440] Added this after the above: Section: Use the Class Loader Programmatically in a Deployment Programmatically Load Classes and Resources in a Deployment [24376] Programmatically Iterate Resources in a Deployment [24377] before Section: Class Loading and Subdeployments
New topics are on-stage and ready for review (Revision 2.0-9): http://documentation-devel.engineering.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/6.2/html-single/Development_Guide/index.html#sect-Use_the_Class_Loader_Programmatically_in_a_Deployment
Included in DevelGuide and verified during EAP-6.2.0-ER6 test cycle.