<?xml version='1.0' encoding='UTF-8'?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2010, Red Hat Middleware LLC, and individual contributors
  by the @authors tag. See the copyright.txt in the distribution for a
  full listing of individual contributors.

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
--><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
<chapter id="solder-resourceloading">
  <title>Injecting Resources and System Properties</title>
  
  <section>
    <title>Resource Loading</title>

    <para>
        Solder 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, either as a URL or an 
        InputStream:
     </para>
    <programlisting role="JAVA">   @Inject
     @Resource(&quot;WEB-INF/beans.xml&quot;)
     URL beansXml;

     @Inject
     @Resource(&quot;WEB-INF/web.xml&quot;)
     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>
        If you need access to all resources under a given name known to the resource loader (as opposed to first resource
        loaded), you can inject a collection of resources:
     </para>
    <programlisting role="JAVA"><![CDATA[   @Inject
     @Resource("WEB-INF/beans.xml")
     Collection<URL> beansXmls;

     @Inject
     @Resource("WEB-INF/web.xml")
     Collection<InputStream> webXmls;]]></programlisting>
    <tip>
      <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>
    </tip>
    <para>
        If the resource is a Properties bundle, you can also inject it as a set of <code>Properties</code>:
     </para>
    <programlisting role="JAVA"><![CDATA[   @Inject
     @Resource("META-INF/aws.properties")
     Properties awsProperties;]]></programlisting>
    <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.solder.resourceLoader.ResourceLoader</code>.
        </para>
    </section>
  </section>
  
  <section>
    <title>System Properties</title>
    
    <para>
      Solder allows system properties to be easily injected using the <code>@System</code> qualifier.  The following
      code snippet shows how you can inject system properties directly into your own bean:
    </para>
    
    <programlisting><![CDATA[import java.util.Properties;
import org.jboss.solder.core.System;
import javax.inject.Inject;

public class Foo {
    @Inject @System Properties properties;
    
    //..
}]]></programlisting>

    <para>
      Solder also exposes the system properties as a named bean called <code>sysProp</code>, allowing them to be 
      referenced directly via EL (Expression Language), for example from a JSF page definition.  Please refer to the
      <code>org.jboss.solder.system.SystemProperties</code> class in the Solder API documentation for a list of the
      available methods.
    </para>

  </section>
</chapter>
