<document>
  <header>
    <product>resin-ee</product>
    <title>Collections: The @OneToMany Relation</title>
        <description>
<p>The @OneToMany relation adds collection extensions to the query language
and provides a Java Collection containing the children.  @OneToMany
represents a collection of children belonging to a parent,
like students in Gryffindor house at Hogwarts school.</p>

<p>
The <a href="amber|tutorial/cmp-many2one/index.xtp">Many-To-One tutorial</a>
illustrated that a many-to-one relation links one source entity to another
target entity.  A one-to-many relation links the target entity back to the
source entity.
</p>

<p>
In this example, 
each House has many Students, 
each Student has one House.
House has a one-to-many relationship with Student,
Student has a many-to-one relationship with House
</p>

        </description>
    <type>tutorial</type>
    <tutorial-startpage>one2many</tutorial-startpage>
  </header>

  <body>
    <summary/>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/resin-web.xml"/>
    <td>web.xml configuration
<tr><td><viewfile-link file="WEB-INF/classes/META-INF/persistence.xml"/>
    <td>persistence.xml configuration
<tr><td><viewfile-link file="WEB-INF/classes/example/Student.java"/>
    <td>The student bean
<tr><td><viewfile-link file="WEB-INF/classes/example/House.java"/>
    <td>The house bean
<tr><td><viewfile-link file="WEB-INF/classes/example/OneToManyServlet.java"/>
    <td>The test servlet
</deftable>
</section>

<section title="Data Model: Object and Database Models">

<section title="Database Schema">

<p>
The database schema is unchanged from the
<a href="amber|tutorial/cmp-many2one/index.xtp">Many-To-One tutorial</a>,
and might look like:</p>

<example title="SQL">
CREATE TABLE house (
  id BIGINT PRIMARY KEY auto_increment,

  name VARCHAR(250),
)

CREATE TABLE student (
  id BIGINT PRIMARY KEY auto_increment,

  name VARCHAR(250),

  house BIGINT REFERENCES house(id)
)
</example>
</section>

<section title="@OneToMany - the relation's &quot;inverse&quot; side ">
<p>The <var/House/> bean has a students field that returns the students that belong to the house.  House annotates <code>getStudents</code> with 
<code>@OneToMany</code> to describe the relationship.  The <code>@JoinColumn</code> is used to specify the <i>foreign key</i>, the field in <var>Student</var> 
that is the <code>@ManyToOne</code> link.
</p>

<example title="House.java"
         file="WEB-INF/classes/example/House.java"
         re-marker="Get the Student" re-start="Get the Student" re-end="^  }">
  @<a href="amber|amber-table.xtp#@OneToMany">OneToMany</a>(mappedBy="house")
  private Set&lt;Student&gt; _students;
</example>
</section>

<section title="@ManyToOne - the relation's &quot;owning&quot; side">
<p>
A @OneToMany always requires a corresponding @ManyToOne on the target entity.
The Student has a house field annotated a <code>@ManyToOne</code>,
unchanged from the 
<a href="ejb3|tutorial/cmp-many2one/index.xtp">Many-To-One tutorial</a>.
</p>

<example title="Student.java"
         file="WEB-INF/classes/example/Student.java"
         re-start="this Student belongs to" re-end="^  }">

  <a href="amber|amber-table.xtp#@ManyToOne">@ManyToOne</a>
  <a href="amber|amber-table.xtp#@JoinColumn">@JoinColumn</a>(name="house")
  private House _house;
</example>

</section>
</section>
<!--
<section title="@FetchType">
<p>
Often a <code>@OneToMany</code> relationship should be marked as <var/lazy/>.
This indicates that the target entities should not be retrieved from the
database until the <code>@OneToMany</code> field is used.
</p>

<p>
The <code>@OneToMany</code> annotation for the students field indicates a
FetchType of <code/LAZY/>.  A House can potentially have many Students, and in
use the students may not be needed by the code using the House bean.  For
example, if the goal is to display a summary list only Houses, the associated
Student's will not be needed and it would be inefficient to fetch them each
time.
</p>

<example title="House.java"
         file="WEB-INF/classes/example/House.java"
         re-start="FetchType">
  @OneToMany(targetEntity=Student.class, mappedBy="house")
  public Set&lt;Student&gt; getStudents()
</example>

</section>
-->
<section title="java.util.Collection: Using House.getStudents()">

<p>
The one-to-many relation provides a House the ability to get all of its
Students.  Resin will perform any necessary
database lookup.
</p>

<p>The example queries all houses and prints their
names and all of their students.</p>

<example title="Using House.getStudents()"
         file="WEB-INF/classes/example/OneToManyServlet.java"
         re-start="SELECT h FROM" re-end="^    }">

private void doService(PrintWriter out)
  throws java.io.IOException
{
  public void service(HttpServletRequest req, HttpServletResponse res)
    throws java.io.IOException, ServletException
  {
    PrintWriter out = res.getWriter();

    res.setContentType("text/html");

    String sql = "SELECT h FROM House h";
    
    Query allHouse = _entityManager.createQuery("SELECT o FROM House o");

    List houses = allHouse.getResultList();

    for (int i = 0; i &lt; houses.size(); i++) {
      House house = (House) houses.get(i);

      out.println("&lt;h3&gt;" + house.getName() + "&lt;/h3&gt;");

      for ( Student student : house.getStudents() ) {
        out.println( student.getName() + "&lt;br&gt;" );
      }
    }
  }
}
</example>

</section>

<section title="Query extensions">

<section title="Result Collections: SELECT h.students">

<example title="h.students">
SELECT h.students FROM House h WHERE h.name='Gryffindor'
</example>

</section>

<section title="Joins: FROM House h, IN(h.students) s">

<example title="IN">
SELECT s FROM House h, IN(h.students) s WHERE h.name='Gryffindor'
</example>

</section>

<section title="Membership: s MEMBER OF h.students">

<example title="MEMBER OF">
SELECT s FROM Student s, House h WHERE s MEMBER OF h.students
</example>

</section>

<section title="Empty: h.students IS EMPTY">

<example title="IS EMPTY">
SELECT h FROM House h WHERE h.students IS EMPTY
</example>

</section>

</section>

  </body>
</document>
