Docs for resource loader

* Finish off javadoc
* Update package-info
* Add refdocs

docs/src/main/docbook/en-US/resourceloading.xml

@@ -4,9 +4,55 @@
 <chapter id="resourceloading">
    <title>Resource Loading</title>
 
-   <section>
+   <para>
+      Weld Extensions provides an extensible, injectable resource loader. The resource loader can provide URLs or 
+      managed input streams. By default the resource loader will look at the classpath, and the servlet context if
+      available.
+   </para>
+
+   <para>
+      If the resource name is known at development time, the resource can be injected:
+   </para>
+
+   <programlisting role="JAVA">   @Inject
+   @Resource("WEB-INF/beans.xml")
+   URL beansXml;
+
+   @Inject
+   @Resource("WEB-INF/web.xml")
+   InputStream webXml;</programlisting>
 
+   <para>
+      If the resource name is not known, the <code>ResourceProvider</code> can be injected, and the resource looked up 
+      dynamically:
+   </para>
+
+   <programlisting role="JAVA">   @Inject
+   void readXml(ResourceProvider provider, String fileName) {
+      InputStream is = provider.loadResourceStream(fileName);
+   }</programlisting>
+
+   <para>
+      Any input stream injected, or created directly by the <code>ResourceProvider</code> is managed, and will be 
+      automatically closed when the bean declaring the injection point of the resource or provider is destroyed. 
+   </para>
+
+   <section>
+      <title>Extending the resource loader</title>
+
+      <para>
+         If you want to load resources from another location, you can provide an additional resource loader. First,
+         create the resource loader implementation:
+      </para>
+
+      <programlisting role="JAVA">class MyResourceLoader implements ResourceLoader {
+   ...
+}</programlisting>
 
+      <para>
+         And then register it as a service by placing the fully qualified class name of the implementation in a file
+         called <code>META-INF/services/org.jboss.weld.extensions.resourceLoader.ResourceLoader</code>.
+      </para>
    </section>
 
 </chapter>

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/DelegatingResourceLoader.java

@@ -15,7 +15,9 @@
  * Resource loader that delegates to a static list of resource loaders.
  * 
  * @author Stuart Douglas
+ * @deprecated this resource loader can easily leak between application instances
  */
+@Deprecated
 public class DelegatingResourceLoader implements ResourceLoader
 {
    private static final Logger log = LoggerFactory.getLogger("org.jboss.weld.extensions.resources");

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/ResourceLoader.java

@@ -50,27 +50,57 @@ public interface ResourceLoader extends Sortable
 {
 
    /**
+    * <p>
     * Get the {@link URL} for a resource.
+    * </p>
     * 
-    * @param resource the resource to get the {@link URL} for
+    * <p>
+    * The resource loaders are searched in precedence order, stopping when a
+    * resource is found.
+    * </p>
+    * 
+    * @param name the resource to get the {@link URL} for
     * @return the {@link URL}, or null if the resource does not exist
+    * @throws RuntimeException if an error occurs loading the resource
     */
    public URL getResource(String name);
 
    /**
+    * <p>
     * Get the {@link InputStream} for a resource.
+    * </p>
+    * 
+    * <p>
+    * The resource loaders are searched in precedence order, stopping when a
+    * resource is found.
+    * </p>
     * 
     * @param name the resource to get the {@link InputStream} for
     * @return the {@link InputStream}, or null if the resource does not exist
+    * @throws RuntimeException if an error occurs loading the resource
     */
    public InputStream getResourceAsStream(String name);
 
    /**
+    * <p>
+    * Get the URLs known to all resource loaders for a given name.
+    * </p>
+    * 
+    * @param name the resource to get the URLs for
+    * @return the URLs, or an empty collection if no resources are found
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public Collection<URL> getResources(String name);
 
+   /**
+    * <p>
+    * Get the input streams known to all resource loaders for a given name.
+    * </p>
     * 
-    * @param name
-    * @return
+    * @param name name the resource to get the input streams for
+    * @return the input streams, or an empty collection if no resources are
+    *         found
+    * @throws RuntimeException if an error occurs loading the resource
     */
    public Collection<InputStream> getResourcesAsStream(String name);
 

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/ResourceLoaderExtension.java

@@ -22,6 +22,9 @@
 import javax.enterprise.inject.spi.Extension;
 
 /**
+ * <p>
+ * CDI portable extension responsible for setting up the resource loader.
+ * </p>
  * 
  * @author Stuart Douglas
  * 

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/ResourceLoaderManager.java

@@ -29,18 +29,35 @@
 import org.jboss.weld.extensions.util.service.ServiceLoader;
 
 /**
- * Class that is responsible for loading {@link ResourceProvider}
- * implementations from the service loader and using them to load resources
+ * <p>
+ * {@link ResourceLoaderManager} discovers and instantiates all
+ * {@link ResourceLoader}s defined. It also provides accesss to these resources,
+ * either as {@link URL}s or {@link InputStream}s.
+ * </p>
+ * 
+ * <p>
+ * If you are working in a CDI managed environment, you should use
+ * {@link ResourceProvider} instead, as it provides automatic, contextual
+ * management of resources. If you are outside a CDI managed environment, then
+ * instantiating {@link ResourceLoaderManager} provides access to the same
+ * resources.
+ * </p>
  * 
  * @author Pete Muir
  * @author Stuart Douglas
  * 
+ * @see ResourceLoader
+ * @see ResourceProvider
  */
 public class ResourceLoaderManager
 {
 
    private final List<ResourceLoader> resourceLoaders;
 
+   /**
+    * Instantiate a new instance, loading any resource loaders from the service
+    * loader, and sorting them by precedence.
+    */
    public ResourceLoaderManager()
    {
       resourceLoaders = new ArrayList<ResourceLoader>();
@@ -51,11 +68,31 @@ public ResourceLoaderManager()
       Collections.sort(resourceLoaders, new Sortable.Comparator());
    }
 
+   /**
+    * The discovered {@link ResourceLoader} instances.
+    * 
+    * @return the resource loaders
+    */
    public Iterable<ResourceLoader> getResourceLoaders()
    {
       return Collections.unmodifiableList(resourceLoaders);
    }
 
+   /**
+    * <p>
+    * Load a resource by name.
+    * </p>
+    * 
+    * <p>
+    * The resource loaders will be searched in precedence order, the first
+    * result found being returned.
+    * </p>
+    * 
+    * @param name the resource to load
+    * @return a URL pointing to the resource, or <code>null</code> if no
+    *         resource can be loaded
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public URL getResource(String name)
    {
       for (ResourceLoader loader : resourceLoaders)
@@ -69,6 +106,21 @@ public URL getResource(String name)
       return null;
    }
 
+   /**
+    * <p>
+    * Load a resource by name.
+    * </p>
+    * 
+    * <p>
+    * The resource loaders will be searched in precedence order, the first
+    * result found being returned.
+    * </p>
+    * 
+    * @param name the resource to load
+    * @return an InputStream providing access to the resource, or
+    *         <code>null</code> if no resource can be loaded
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public InputStream getResourceAsStream(String name)
    {
       for (ResourceLoader loader : resourceLoaders)
@@ -102,6 +154,16 @@ public Collection<URL> getResources(String name)
       return urls;
    }
 
+   /**
+    * <p>
+    * Load all resources known to the resource loader by name.
+    * </p>
+    * 
+    * @param name the resource to load
+    * @return a collection of input streams pointing to the resources, or an
+    *         empty collection if no resources are found
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public Collection<InputStream> getResourcesAsStream(String name)
    {
       Set<InputStream> streams = new HashSet<InputStream>();

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/ResourceProvider.java

@@ -48,7 +48,7 @@
  * 
  * <p>
  * If you know the name of the resource you are loading at development time you
- * can inject it directly using the {@link Resource} qualifier.
+ * can inject it directly using the <code>&#64;{@link Resource}</code> qualifier.
  * </p>
  * 
  * <p>
@@ -94,16 +94,23 @@ private ResourceProvider(@Any Instance<InputStream> inputStreamProvider, @Any In
     * </p>
     * 
     * <p>
-    * The default search order is:
+    * The resource loaders will be searched in precedence order, the first
+    * result found being returned. The default search order is:
     * </p>
     * 
     * <ul>
-    * <li></li>
+    * <li>classpath</li>
+    * <li>servlet context, if available</li>
     * </ul>
     * 
+    * <p>
+    * However extensions may extend this list.
+    * </p>
     * 
-    * @param name
-    * @return
+    * @param name the resource to load
+    * @return an input stream providing access to the resource, or
+    *         <code>null</code> if no resource can be loaded
+    * @throws RuntimeException if an error occurs loading the resource
     */
    public InputStream loadResourceStream(String name)
    {
@@ -121,6 +128,27 @@ public InputStream loadResourceStream(String name)
 
    /**
     * <p>
+    * Load all resources known to the resource loader by name.
+    * </p>
+    * 
+    * <p>
+    * By default, Weld Extensions will search:
+    * </p>
+    * 
+    * <ul>
+    * <li>classpath</li>
+    * <li>servlet context, if available</li>
+    * </ul>
+    * 
+    * <p>
+    * However extensions may extend this list.
+    * </p>
+    * 
+    * @param name the resource to load
+    * @return a collection of input streams pointing to the resources, or an
+    *         empty collection if no resources are found
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public Collection<InputStream> loadResourcesStreams(String name)
    {
       if (name == null || name.equals(""))
@@ -134,20 +162,30 @@ public Collection<InputStream> loadResourcesStreams(String name)
       streamsCache.addAll(streams);
       return streams;
    }
+
+   /**
+    * <p>
     * Load a resource.
     * </p>
     * 
     * <p>
-    * The default search order is:
+    * The resource loaders will be searched in precedence order, the first
+    * result found being returned. The default search order is:
     * </p>
     * 
     * <ul>
-    * <li></li>
+    * <li>classpath</li>
+    * <li>servlet context, if available</li>
     * </ul>
     * 
+    * <p>
+    * However extensions may extend this list.
+    * </p>
     * 
-    * @param name
-    * @return
+    * @param name the resource to load
+    * @return a URL pointing to the resource, or <code>null</code> if no
+    *         resource can be loaded
+    * @throws RuntimeException if an error occurs loading the resource
     */
    public URL loadResource(String name)
    {
@@ -160,6 +198,29 @@ public URL loadResource(String name)
       return urlProvider.select(annotationInstanceProvider.get(Resource.class, values)).get();
    }
 
+   /**
+    * <p>
+    * Load all resources known to the resource loader by name.
+    * </p>
+    * 
+    * <p>
+    * By default, Weld Extensions will search:
+    * </p>
+    * 
+    * <ul>
+    * <li>classpath</li>
+    * <li>servlet context, if available</li>
+    * </ul>
+    * 
+    * <p>
+    * However extensions may extend this list.
+    * </p>
+    * 
+    * @param name the resource to load
+    * @return a collection of URLs pointing to the resources, or an empty
+    *         collection if no resources are found
+    * @throws RuntimeException if an error occurs loading the resource
+    */
    public Collection<URL> loadResources(String name)
    {
       if (name == null || name.equals(""))

impl/src/main/java/org/jboss/weld/extensions/resourceLoader/package-info.java

@@ -41,6 +41,7 @@
  * @see org.jboss.weld.extensions.resourceLoader.Resource
  * @see org.jboss.weld.extensions.resourceLoader.ResourceProvider
  * @see org.jboss.weld.extensions.resourceLoader.ResourceLoader
+ * @see org.jboss.weld.extensions.resourceLoader.ResourceLoaderManager
  */
 package org.jboss.weld.extensions.resourceLoader;