<document>
  <header>
    <title>JSF with Java Injection</title>
        <description>
          <p>Java Injection (JSR-299) gives JSF a solid foundation for
its component model, based on Java Injection's typesafe IoC capabilities
and annotation-based discovery. </p>
        </description>
    <type>tutorial</type>
    <tutorial-startpage>test.jsf</tutorial-startpage>
  </header>

<body>
<localtoc/>

<s1 title="Files in this tutorial">
<deftable>
<tr>
  <th>File</th>
  <th>Description</th>
</tr>
<tr>
  <td><viewfile-link file="test.jsp"/></td>
  <td>JSP to create the JSF component tree.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/example/Calculator.java"/></td>
  <td>Calculator model simple bean, taking the input and calculating the result.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/resin-web.xml"/></td>
  <td>Configures FacesServlet.</td>
</tr>
<tr>
  <td><viewfile-link file="WEB-INF/classes/META-INF/beans.xml"/></td>
  <td>Java Injection configuration file.</td>
</tr>
</deftable>
</s1>

<s1 title="Overview">

<p>Java Injection works together with JSF to provide a solid
component configuration for the data model of a JSF application.</p>

<p>With Java Injection, component classes are automatically registered
through classpath scanning,, reducing the amount of configuration XML to
a minimum.  In this example, we only need XML to define the FacesServlet,
and a marker beans.xml to direct Java Injection to search for
component classes.</p>

<p>The data components automatically populate the JSF EL (expression language),
so they are automatically available to the JSF application.</p>

<p>This example creates a simple calculator which adds two numbers together.
The <code>Calculator</code> model receives the user data and
produces the results.  A trivial JSP page creates the JSF UI
component tree.</p>

</s1>

<s1 title="Model Component">

<p>The data model is the heart of the JSF application.  In this case,
a trivial calculator.</p>

<p>The <code>example.Calculator</code> is a Java Injection <a href="http://wiki.caucho.com/Simple+Bean">Simple Bean</a>.  When Resin scans the classes,
it will discover <code>Calculator</code>, introspect it, and automatically
register the calculator.  Once it's registered, any other
Java Injection component, or JSP/JSF EL, or PHP file or servlet or EJB can
use the component.</p>

<p>The <code>Calculator</code> component has no XML configuration at all,
since there's nothing to configure.  For other applications, some of the
component beans will want configuration to set properties, which will
occur in something like the resin-web.xml file.</p>

<example title="Calculator.java">
package example;

import javax.context.RequestScoped;
import javax.annotation.Named;

@RequestScoped
@Named("calc")  
public class Calculator {
  private int _a;
  private int _b;

  public int getA() { return _a; }
  public void setA(int a) { _a = a; }

  public int getB() { return _b; }
  public void setB(int b) { _b = b; }

  public int getSum()
  {
    return _a + _b;
  }
}
</example>

<p>The <code>@RequestScoped</code> annotation tells Java Injection to store
the bean in the servlet request scope.  Each request will use its own
instance of the calculator.  If the scope was <code>@SessionScoped</code>,
the same <code>Calculator</code> would be used for the entire session.
If it was <code>@ConversationScoped</code> it would be used for the
JSF page.</p>

<p>The optional <code>@Named</code> annotation gives a name
for the calculator so JSP EL expressions and JSF can access it.
If there is no <code>@Named</code>, the bean cannot be used in a JSP
EL expression.</p>

<p>Java Injection components can also be injected with other
Java Injection, or DataSources, JPA EntityManager or EntityManagerFactory
or JMS Queues, and they can also use the <code>@PostConstruct</code>
and <code>@PreDestroy</code> lifecycle annotations.  Method interception
and event listening are also possible.</p>

</s1>

<s1 title="JSF/JSP: Building the Component Tree">

<p>JSF is designed around a UI component tree model.  The JSP code
builds the JSF component tree, hands it back to JSF, and then JSF will
display the component tree based on its current rendering configuration.
</p>

<ul>
<li>&lt;f:view> is a wrapper tag around all the JSF component tree.</li>
<li>&lt;h:messages> displays any error messages, like typing a string to
the number fields.</li>
<li>&lt;h:form> creates a HTML &lt;form></li>
<li>&lt;h:inputText> creates a HTML &lt;input> tag, using the
<code>Calculator</code> methods <code>getA()</code> and <code>setA()</code>
to receive the form values.</li>
<li>&lt;h:outputText> creates a HTML &lt;span> tag, with the text
value generated by the <code>Calculator</code> <code>getSum()</code> method.</li>
<li>&lt;h:commandButton> creates a HTML &lt;input type="submit"> tag.</li>
</ul>

<example title="test.jsp">
&lt;%@ taglib prefix="f" uri="http://java.sun.com/jsf/core" %>
&lt;%@ taglib prefix="h" uri="http://java.sun.com/jsf/html" %>
&lt;f:view>
  &lt;h:messages/>
  &lt;h:form>
    &lt;h:inputText value="#{calc.a}" size="4"/>
     + &lt;h:inputText value="#{calc.b}" size="4"/>
     = &lt;h:outputText value="#{calc.sum}" style="color:red"/>
    &lt;br>
    &lt;h:commandButton value="Add"/>
  &lt;/h:form>
&lt;/f:view>
</example>

<p>The JSF expression language expressions <code>#{calc.a}</code> and
<code>#{calc.b}</code> are used in two phases of JSF.  When displaying,
JSF will lookup the <code>Calculator</code> with "calc", and call
its <code>getA()</code> method.  When processing the form, JSF will
lookup the <code>Calculator</code> and call the <code>setA()</code>
method to assign the new value.</p>

</s1>

<s1 title="Housekeeping: the resin-web.xml and beans.xml">

<p>The housekeeping overhead is a minimum when using Java Injection.
In this example we just need two pieces of XML configuration:</p>

<ol>
<li>Configuring the JSF servlet in the web.xml</li>
<li>Marking a classpath root with a beans.xml</li>
</ol>

<p>Java Injection will scan classes directories and jars if they contain
a <code>META-INF/beans.xml</code> file, so many applications will
just use <code>beans.xml</code> as a marker file with no content.
Others applications will want to configure the Java Injection components using
the <code>beans.xml</code> or may put that configuration in the
<code>resin-web.xml</code>.</p>

<example title="WEB-INF/resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;servlet-mapping url-pattern="*.jsf"
                   servlet-class="javax.faces.webapp.FacesServlet"/>

&lt;/web-app>
</example>

<example title="META-INF/beans.xml">
&lt;Beans xmlns="urn:java:ee">
  &lt;!--
     - The beans.xml marks a class root for Java Inject to search for
     - simple beans.  Since the example doesn't need to override any
     - defaults, there's no additional configuration necessary.
     -->
&lt;/Beans>
</example>

</s1>

<s1 title="Completing the Application">

<p>A more complete application would likely the IoC injection capabilities
of Java Injection.  For example:</p>

<ul>
<li>Use Java Persistence by injecting a <code>@Current EntityManager</code>
to a model field.</li>
<li>Injecting a Java injection singleton service
with <code>@Current</code>, defined
by a &lt;foo:MyBean> configuration in the resin.xm. (assuming it needs configuration.</li>
<li>Using JDBC directly with <code>@Current DataSource</code> or <code>@Name("jdbc/test") DataSource.</code>.</li>
<li>Using EJB stateless or stateful session beans as services.</li>
</ul>

</s1>

</body>
</document>
