Bug 973468 - [PRD] EAP62_1110 - [RFE] API to list resources inside deployments
[PRD] EAP62_1110 - [RFE] API to list resources inside deployments
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise Application Platform 6
Classification: JBoss
Component: Documentation (Show other bugs)
6.2.0
Unspecified Unspecified
unspecified Severity unspecified
: GA
: EAP 6.2.0
Assigned To: sgilda
Russell Dickenson
: Documentation, FutureFeature
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2013-06-11 21:39 EDT by Russell Dickenson
Modified: 2015-02-20 05:23 EST (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Enhancement
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-12-15 11:55:28 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Russell Dickenson 2013-06-11 21:39:45 EDT
Provide an API call that returns a listing of all the files in a deployment.
--[jira] https://issues.jboss.org/browse/PRODMGT-286
Comment 1 sgilda 2013-10-29 15:00:13 EDT
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
Comment 2 sgilda 2013-10-29 15:02:46 EDT
Created topic 24376: Programmatically Load Classes and Resources in a Deployment

Still need to add 'Iterating Resources in a Deployment'
Comment 3 sgilda 2013-10-29 15:32:02 EDT
JavaDoc for JBoss Modules: http://docs.jboss.org/jbossmodules/1.2.0.Final/api/
Comment 4 sgilda 2013-10-29 17:21:35 EDT
Created topic 24377: Programmatically Iterate Resources in a Deployment
Comment 5 sgilda 2013-10-29 19:34:19 EDT
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
Comment 7 Pavel Janousek 2013-10-30 07:04:08 EDT
Included in DevelGuide and verified during EAP-6.2.0-ER6 test cycle.

Note You need to log in before you can comment on or make changes to this bug.