<document>
  <header>
    <product>resin-ee</product>
    <resin-2.0>$ee/ejb-ref/resin-ejb-config.xtp</resin-2.0>
    <title>Resin EJB Configuration</title>
  </header>

  <body>
<summary/>

<section title='Configuration'>

<defun title='abstract-sql-type'>
<p>An abstract SQL type to be used when automatically creating a table for
the entity bean.  Resin-CMP will use the abstract-sql-type and the
database driver type to determine the actual type used to create
the database table.</p>
</defun>

<defun title='cache-size' version='Resin-CMP 1.0.5'>
<p>Defines the size of the entity cache.</p>
<p>The default cache-size is 8192.</p>
</defun>

<defun title='cache-timeout' version='Resin-CMP 1.0.5'>
<p>Defines how long a loaded bean will remain loaded.
As long as a cached CMP bean is loaded, it doesn't need to query the
database, saving time and database load.</p>

<p>The default value is 5 seconds.</p>
</defun>

<defun title='cmp-field'>
<p>Defines one of the bean's fields to be managed by Resin-CMP.
Since Resin-CMP will introspect the cmp-fields from the classes, the
cmp-field is optional.</p>

<p>cmp-fields are either Java primitives or serializable types, i.e.
values in a database table.  Relations between beans are configured
in the <a href='relations.xtp'>relations</a> section.</p>

<deftable>
<tr><th>Element<th>Meaning
<tr><td>field-name<td>the field name
<tr><td>sql-column<td>the SQL column name
<tr><td>sql-type<td>the SQL type
</deftable>

<p>The SQL name is generated automatically from the cmp-field (or
the getter method.)  The getter method <var/getMyField/> corresponds to
the cmp-field <var/myField/> and the SQL column <var/my_field/>.  An
EJB-QL query, always uses the cmp-field name, e.g. <var/myField/>.</p>

<p>The cmp-field can specify the SQL column name using sql-column.</p>

<example title="student.ejb">
  &lt;entity>
    &lt;abstract-schema-name>students&lt;/abstract-schema-name>
    &lt;sql-table>student_table&lt;/sql-table>
    ...
    &lt;cmp-field>
      &lt;field-name>id&lt;/field-name>
      &lt;sql-column>student_id&lt;/sql-column>
    &lt;/cmp-field>
    &lt;cmp-field>
      &lt;field-name>name&lt;/field-name>
      &lt;sql-column>user_name&lt;/sql-column>
    &lt;/cmp-field>
    ...
  &lt;/entity>
</example>

<p>The above descriptor would expect the following schema:</p>

<example title="student.sql">
CREATE TABLE student_table (
  student_id INTEGER AUTO_INCREMENT,
  user_name VARCHAR(255),

  PRIMARY KEY(student_id)
);
</example>

</defun>

<defun title='data-source'>
<p>Specifies the database JNDI name for the DataSource.  If unspecified,
it defaults to the value in EJBServer.</p>
</defun>

<defun title='field-name'>
<p>Specifies the field name for a cmp-field definition.  The field-name
is the bean name for the Java getter method.  So the field-name for <code/getFoo/> is <var/foo/>.</p>
</defun>

<defun title='method'>
<p>Configuration for a business method.  Each business method is
specified by a &lt;signature>.  The signature syntax is the
same as Java function syntax without the return type.</p>

<p>The arguments are optional and the method name can be "*".
The best matching method will be used.  Methods which match a
method with specified args is better than a method with only a method name.
And both are better than the default match.</p>

<example title="Configure most methods as read-only">
&lt;method signature="*">
  &lt;resin-isolation>read-only&lt;/resin-isolation>
&lt;/method>

&lt;method signature="writeMethod(String)">
  &lt;resin-isolation>database&lt;/resin-isolation>
&lt;/method>
</example>

<def>
method ::= signature, resin-isolation?
</def>

</defun>

<defun title='query-function'>
<p>Adds a new function to the EJB-QL language.
The query-function must specify the function signature in Java syntax.
The following types are allowed: int, double, boolean, String, Date and
any.</p>

<p>An optional <var/sql/> attribute lets you provide custom functions.</p>

<example title="Adding MD5">
&lt;query-function>
  &lt;signature>String MD5(String)&lt;/signature>
&lt;/query-function>
</example>

<example title="Adding an add function">
&lt;query-function>
  &lt;signature>int add(int, int)&lt;/signature>
  &lt;sql>((?1) + (?2))&lt;/signature>
&lt;/query-function>
</example>

<def>
query-function = element query-function {
  signature, sql?
}
</def>

</defun>

<defun title='query-loads-bean'>
<p>If true, an <code/ejbSelect/> or <code/find/> query will
load the beans in the query's select.  If false, the query will
only load the primary key and lazily load the bean when it's referenced.</p>

<p>Normally, setting this true will give better performance.</p>

<example title="Default all querys to lazy load">
&lt;method>
  &lt;signature>*&lt;/signature>
  &lt;query-loads-bean>false&lt;/query-loads-bean>
&lt;/method>
</example>

<p><b>Default:</b> true by default.</p>
</defun>

<defun title='read-only'>
<p>Configures a bean as read-only.
Read-only entity bean values can be cached between calls even
in "update" transactions .  The cache time is configured with cache-time.
</p>
</defun>

<defun title='resin-ejb'>
<p>Top-level configuration for the Resin-specific configuration.</p>

<def>
resin-ejb ::= enterprise-beans
</def>
</defun>

<defun title='resin-isolation'>
<p>Configures the isolation level for a method.  Each method is
classified with either <var/read-only/> or <var/database/> isolation.
<var/read-only/> methods only read database from the database.
<var/database/> methods read and write to the database.</p>

<p>By telling Resin which methods are read-only, Resin can effectively
cache read values and reduce the database load.</p>

<p>For methods defined by EJB as write methods, Resin will ignore
the read-only value.  <code/setXXX/>, <code/create/>, and <code/remove/>
methods always have <var/database/> or stronger isolation.</p>

<p>For methods defined by EJB as read methods, Resin
will use <var/read-only/> as a default.</p>

<p><b>Default:</b> the default value is <var/database/></p>
</defun>

<defun title='signature'>
<p>Speficies a function signature, i.e. a method declaration, in Java
syntax.
In the case of &lt;query-function>, &lt;signature> specifies the
name and types for a new EJB-QL function.
</p>
</defun>

<defun title='sql-column'>
<p>The SQL column name for a field or relation.  If is unspecified,
it defaults to the field name.  The value of sql-column is
never used in the EJB queries.  It's just used during SQL generation.</p>

<p>For relations where the target bean has a compound primary key,
the sql-column can specify a <var/references/> attribute to distinguish
which part of the primary key to configure.</p>

<example title="Specifying a cmp-field">
&lt;entity>
  &lt;ejb-name>students&lt;/ejb-name>
  ...
  &lt;cmp-field>
    &lt;field-name>id&lt;/field-name>
    &lt;sql-column>student_id&lt;/sql-column>
  &lt;/cmp-field>
&lt;/entity>
</example>

<example title="A pointer to a compound-key bean">
&lt;cmr-field>
  &lt;cmr-field-name>child&lt;/cmr-field-name>
  &lt;sql-column references='parent'>test_parent&lt;/sql-column>
  &lt;sql-column references='name'>test_cname&lt;/sql-column>
&lt;/cmr-field>
</example>

</defun>

<defun title='sql-type'>
<p>The SQL type to be used when automatically creating a table for
the entity bean.  The sql-type is the string that will be
used in the CREATE TABLE.</p>

</defun>

</section>

<section title='Formal Definition'>

<def>
resin-ejb ::= enterprise-beans?, query-function*

enterprise-beans ::= entity*

entity ::= (<a href="#ejb-name">ejb-name</a>,
            <a href="#sql-table">sql-table</a>?,
            <a href="#cache-timeout">cache-timeout</a>?,
            <a href="#cache-size">cache-size</a>?,
            <a href="#data-source">data-source</a>?,
            <a href="#cmp-field">cmp-field</a>*,
            <a href="#method">method</a>*)

cmp-field ::= (<a href="#field-name">field-name</a>,
               <a href="#sql-column">sql-column</a>?,
               <a href="#abstract-sql-type">abstract-sql-type</a>?,
               <a href="#sql-type">sql-type</a>?)

sql-column ::= (<var/text(column-name)/> |
                (<var/references/>, <var/id/>))

query-function ::= <a href="#signature">signature</a>

method ::= <a href="#signature">signature</a>,
           <a href="#resin-isolation">resin-isolation</a>?
           <a href="#query-loads-bean">query-loads-bean</a>?
</def>

</section>

</document>

