amber.xtp

RESIN 3.2 最新源码

<tr>
  <td>table</td>
  <td>specifies a secondary table if not in the primary</td>
  <td>none</td>
</tr>
</deftable>

<def title="javax.persistence.JoinColumn">
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinColumn {
  String name() default "";
  String referencedColumnName() default "";
  boolean unique() default false;
  boolean nullable() default false;
  boolean insertable() default true;
  boolean updateable() default true;
  String columnDefinition() default "";
  String table() default "";
}
</def>

<example title="Example: Student to House link">
public class Student {
  @Id
  @Column(name="student_id")
  long getId()

  @ManyToOne
  @JoinColumn(name="house_id")
  public House getHouse()
}
</example>

<example title="Example: Student SQL">
CREATE TABLE Student {
  student_id BIGINT PRIMARY KEY auto_increment

  house_id BIGINT REFERENCES House(id)
)
</example>

</s3>

<s3 title="@JoinColumns">

<p>Defines a set of join (foreign) columns for composite keys.</p>

<def title="javax.persistence.JoinColumns">
@Target({TYPE,METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinColumns {
  JoinColumn [] value() default{}
}
</def>

</s3>

<s3 title="@JoinTable">

<p>Defines an association table for a many-to-many relation.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>name</td>
  <td>Table definition for the association table</td>
  <td>concatening the source and target table names</td>
</tr>
<tr>
  <td>catalog</td>
  <td>Database catalog</td>
  <td>""</td>
</tr>
<tr><td>schema</td><td>Database schema</td><td>""
</td></tr><tr><td>joinColumns</td><td>Columns from from the association table to the source table</td><td>Uses the source table primary key
</td></tr><tr><td>inverseJoinColumns</td><td>Columns from from the association table to the target table</td><td>Uses the target table primary key
</td></tr></deftable>

<def title="javax.persistence.JoinTable">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface JoinTable {
  String table() default "";
  String catalog() default "";
  String schema() default "";
  JoinColumn []joinColumns() default {};
  JoinColumn []inverseJoinColumns() default {};
  UniqueContraint []uniqueConstraint() default {};
}
</def>

</s3>

<s3 title="@ManyToMany">

<p>Marks a field as a many-to-many (association) relation.</p>

<p>The column names are the key columns of the source and target tables.</p>

<p>See the <a href="../examples/amber-many2many/index.xtp">many-to-many tutorial</a> for an example.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>cascade</td>
  <td>Operations which cascade to the target</td>
  <td>none</td>
</tr>
<tr>
  <td>fetch</td>
  <td>EAGER or LAZY fetching</td>
  <td>FetchType.EAGER</td>
</tr>
<tr>
  <td>mappedBy</td>
  <td>Specifies the source relation if a target</td>
  <td></td>
</tr>
<tr>
  <td>targetEntity</td>
  <td>The class of the target entity</td>
  <td>the property's type</td>
</tr>
</deftable>

<def title="javax.persistence.ManyToMany">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ManyToMany {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default LAZY;
  String mappedBy isInverse() default "";
}
</def>

<example title="Example: @ManyToMany link ">
@Entity
public class Student {
  @ManyToMany
  @JoinTable(
    name="student_course_map",
    joinColumns={@JoinColumn(name="student_id")},
    inverseJoinColumns={@JoinColumn(name="course_id")}
  )
  public Collection getCourses()

  ...
}
</example>

</s3>

<s3 title="@ManyToOne">

<p>Marks a field as a many-to-one (link) relation.</p>

<p>The default column name is the column name of the target key.</p>

<p>See the <a href="../examples/amber-many2one/index.xtp">many-to-one tutorial</a> for an example.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>targetEntity</td>
  <td>The class of the target entity</td>
  <td>the property's type</td>
</tr>
<tr>
  <td>cascade</td>
  <td>Operations which cascade to the target: ALL, PERSIST,
      MERGE, REMOVE or REFRESH</td>
  <td>none</td>
</tr>
<tr>
  <td>fetch</td>
  <td>EAGER or LAZY fetching</td>
  <td>FetchType.EAGER</td>
</tr>
<tr>
  <td>optional</td>
  <td>If false, the relation must always have a value</td>
  <td>true</td>
</tr>
</deftable>

<def title="javax.persistence.ManyToOne">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ManyToOne {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  boolean optional() default true;
}
</def>

<example title="Example: @ManyToOne link ">
@Entity
public class Student {
  @ManyToOne
  @JoinColumn(name="house")
  public House getHouse()

  ...
}
</example>

</s3>

<s3 title="@MapKey">

<p>Marks a field as key in a Map relationship.</p>

<def title="javax.persistence.MapKey">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface MapKey {
  String name() default "";
}
</def>

</s3>

<s3 title="@OneToMany">

<p>Marks a field as a one-to-many (collection) relation.
Because a one-to-many field is dependent, it
needs a @ManyToOne relation on the source table which defines the column.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>targetEntity</td>
  <td>The class of the target entity</td>
  <td>the property's type</td>
</tr>
<tr>
  <td>cascade</td>
  <td>Operations which cascade to the target: ALL, PERSIST, MERGE,
REMOVE, and REFRESH</td>
  <td>none</td>
</tr>
<tr>
  <td>fetch</td>
  <td>EAGER or LAZY fetching</td>
  <td>FetchType.EAGER</td>
</tr>
<tr>
  <td>mappedBy</td>
  <td>Specifies the owning @ManyToOne property on the target entity.</td>
  <td></td>
</tr>
</deftable>

<def title="javax.persistence.OneToMany">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToMany {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  String mappedBy() default "";
}
</def>

<example title="Example: collection">
@Entity
public class House {
  ...
  @OneToMany(targetEntity=Student.class,
             mappedBy="house")
  public Collection getStudents()
}

@Entity
public class Student {
  ...
  @ManyToOne
  @JoinColumn(name="house")
  public House getHouse()
}
</example>

<example title="Example: Collection SQL">
CREATE TABLE House {
  id BIGINT PRIMARY KEY
)

CREATE TABLE Student {
  id BIGINT PRIMARY KEY,

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

</s3>

<s3 title="@OneToOne">

<p>Marks a field as a one-to-one (dependent link) relation.
Because a one-to-one field is dependent, it
needs a @ManyToOne relation on the source table which defines the column.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>targetEntity</td>
  <td>The class of the target entity</td><td>the property's type</td>
</tr>
<tr>
  <td>cascade</td>
  <td>Operations which cascade to the target: ALL, PERSIST, MERGE,
REMOVE, and REFRESH</td>
  <td>none</td>
</tr>
<tr>
  <td>fetch</td>
  <td>EAGER or LAZY fetching</td>
  <td>FetchType.EAGER</td>
</tr>
<tr>
  <td>mappedBy</td>
  <td>Specifies the owning relation</td>
  <td></td>
</tr>
</deftable>

<def title="javax.persistence.OneToOne">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OneToOne {
  String targetEntity default "";
  CascadeType []cascade() default {};
  FetchType fetch() default EAGER;
  boolean optional() default true;
  String mappedBy() default "";
}
</def>

</s3>

<s3 title="@OrderBy">

<p><code>@OrderBy</code> specifies the SQL column to use for ordering
collection relations.</p>

<deftable>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>name</td>
  <td>The property name to sort the collection by.</td>
  <td>the property's type</td>
</tr>
</deftable>

<def title="javax.persistence.OrderBy">
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OrderBy {
  String value() default "";
}
</def>

</s3>

</s2>

</s1>

<s1 title="Amber Lifecycle">

<s2 title="Non-Transactional Lifecycle">

<p>Amber's non-transactional lifecycle has three important states:</p>

<ul>
<li><b>clean:</b> the bean is loaded from the database</li>
<li><b>dirty:</b> the bean has unwritten changes</li>
<li><b>hollow:</b> the bean is unloaded (lazily-loaded)</li>
</ul>

<p>In the diagram below, the red methods (<code>load()</code>,
<code>getXXX()</code>, and <code>flush()</code>) query and
update the database.</p>

<figure src="amber-non-xa.gif" width="356" height="140"/>

<p>The <code>aConn.load("1")</code> method loads the bean from the
database and transitions to the <var>clean</var> state.</p>

<p>Calling <code>test.setData("foo")</code> will change to
the <var>dirty</var> state.</p>

<p>Calling <code>aConn.flush()</code> writes the changes to
the database and changes to the <var>clean</var> state.  Amber may
also flush the changes and change to the clean state
at any time.  <code>flush()</code> merely guarantees that the changes
will be flushed to the database.</p>

<p>The <var>hollow</var> state represents lazily-loaded entities.  many-to-one
relations and some queries will return the unloaded bean instead of
a loaded bean.  When the application calls a <code>getXXX()</code> method,
the bean will load from the database and change to the <var>clean</var> state.
When the application calls a <code>setXXX()</code> method, the bean
will change to the <var>dirty</var> state.</p>

<example title="Example: Amber outside transaction">
public class MyServlet extends GenericServlet {
  @In EntityManagerFactory _factory;
  @In UserTransaction _trans;

  ...

  public void doTest(PrintWriter out)
    throws IOException
  {
     EntityManager aConn = _factory.createManager();

     // load() loads test and then detaches it
     qa.Test test = aConn.load(qa.Test.class, "1");

     // test has the loaded values
     out.println(test.getData());

     // but parent is not lazily-loaded when detached, i.e. it's null.
     qa.Test parent = test.getParent();

     aConn.close();
  }
}
</example>

</s2>

<s2 title="Transactional Lifecycle">

<p>In a transaction, Amber loads the bean from the
database, even if it was loaded outside of the transaction.
(Exceptions exist for cases like read-only beans.) By loading the
bean in the transaction, Amber lets the database handle the
transactional locking and state consistency.</p>

<p>Just like the non-transactional <var>clean</var> and <var>dirty</var>
states, Amber has transactional <var>clean</var> and <var>dirty</var> states
called <var>Persistent-clean</var> and <var>Persistent-dirty</var>.  As in
the non-transactional case, the <var>hollow</var> state represents
lazily-loaded beans.</p>
<ul>
<li><b>persistent-clean:</b> the bean is loaded from the database
within the transaction</li>
<li><b>persistent-dirty:</b> the bean has been changed</li>
<li><b>hollow:</b> the bean is unloaded (lazily-loaded or rolled-back)</li>
<li><b>persistent-nonXA:</b> the bean was loaded outside of the
transaction (and would need reloading if used in the transaction)</li>
</ul>

<figure src="amber-lifecycle.gif" width="511" height="285"/>

<p>The main differences from the non-transactional lifecycle
are:</p>
<ul>
<li>Transactions need a load from inside the transaction.  Loads
before the transaction cannot be reused.</li>
<li>Updates occur during the commit() call and change to the
nonXA-clean state</li>
<li>Rollbacks change to the hollow state.</li>
</ul>

</s2>
</s1>


<s1 title="Configuration Files">
<s2 title="Example configuration">

<p>The lifecycle description uses a single running example, Test, which
has two properties: <code>getData()</code> which returns a string, and
<code>getParent()</code> which is a pointer to another Test object.</p>

<example title="Example: META-INF/orm.xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm orm_1_0.xsd"
   version="1.0"&gt;
  &lt;package&gt;qa&lt;/package&gt;
  &lt;entity name="Test" class="qa.Test" access="PROPERTY"&gt;
    &lt;table name="TEST"/&gt;
      &lt;attributes&gt;
        &lt;id name="id"&gt;
          &lt;column name="ID"/&gt;
        &lt;/id&gt;
        &lt;basic name="data"&gt;
          &lt;column name="DATA"/&gt;
        &lt;/basic&gt;
        &lt;many-to-one name="parent"&gt;
          &lt;join-column name="FK_PARENT"/&gt;
        &lt;/many-to-one&gt;
     &lt;/attributes&gt;
   &lt;/table&gt;
  &lt;/entity&gt;
&lt;/entity-mappings&gt;
</example>

</s2>
</s1>

  </body>
</document>