<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>12.&nbsp; Schema Reflection</title><link rel="stylesheet" href="css/docbook.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"><link rel="start" href="manual.html" title="Apache OpenJPA 1.2 User's Guide"><link rel="up" href="ref_guide_dbsetup.html" title="Chapter&nbsp;4.&nbsp; JDBC"><link rel="prev" href="ref_guide_schema_def.html" title="11.&nbsp; Default Schema"><link rel="next" href="ref_guide_schema_schematool.html" title="13.&nbsp; Schema Tool"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">12.&nbsp;
            Schema Reflection
        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_schema_def.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;
        JDBC
    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_schema_schematool.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ref_guide_schema_info"></a>12.&nbsp;
            Schema Reflection
        </h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_schema_info.html#ref_guide_schema_info_list">12.1. 
                Schemas List
            </a></span></dt><dt><span class="section"><a href="ref_guide_schema_info.html#ref_guide_schema_info_factory">12.2. 
                Schema Factory
            </a></span></dt></dl></div><a class="indexterm" name="d0e21461"></a><p>
OpenJPA needs information about your database schema for two reasons. First, it
can use schema information at runtime to validate that your schema is compatible
with your persistent class definitions. Second, OpenJPA requires schema
information during development so that it can manipulate the schema to match
your object model. OpenJPA uses the <code class="literal">SchemaFactory</code> interface
to provide runtime mapping information, and the <code class="classname">SchemaTool
</code> for development-time data. Each is presented below.
        </p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_schema_info_list"></a>12.1.&nbsp;
                Schemas List
            </h3></div></div></div><a class="indexterm" name="d0e21477"></a><a class="indexterm" name="d0e21480"></a><p>
By default, schema reflection acts on all the schemas your JDBC driver can
"see". You can limit the schemas and tables OpenJPA acts on with the <code class="literal">
openjpa.jdbc.Schemas</code> configuration property. This property accepts a
comma-separated list of schemas and tables. To list a schema, list its name. To
list a table, list its full name in the form <code class="literal">
&lt;schema-name&gt;.&lt;table-name&gt;</code>. If a table does not have a
schema or you do not know its schema, list its name as <code class="literal">
.&lt;table-name&gt;</code> (notice the preceding '.'). For example, to list
the <code class="literal">BUSOBJS</code> schema, the <code class="literal">ADDRESS</code> table in
the <code class="literal">GENERAL</code> schema, and the <code class="literal">SYSTEM_INFO</code>
table, regardless of what schema it is in, use the string:
            </p><pre class="programlisting">
BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Some databases are case-sensitive with respect to schema and table names.
Oracle, for example, requires names in all upper case.
                </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ref_guide_schema_info_factory"></a>12.2.&nbsp;
                Schema Factory
            </h3></div></div></div><a class="indexterm" name="d0e21516"></a><p>
OpenJPA relies on the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/SchemaFactory.html" target="_top">
<code class="classname">openjpa.jdbc.SchemaFactory</code></a> interface for runtime
schema information. You can control the schema factory OpenJPA uses through the
<code class="literal">openjpa.jdbc.SchemaFactory</code> property. There are several
built-in options to choose from:
            </p><div class="itemizedlist"><ul type="disc"><li><p>
<code class="literal">dynamic</code>: This is the default setting. It is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/DynamicSchemaFactory.html" target="_top">
<code class="classname">
org.apache.openjpa.jdbc.schema.DynamicSchemaFactory</code></a>. The 
<code class="classname">DynamicSchemaFactory</code> is the most performant
schema factory, because it does not validate mapping information against the
database. Instead, it assumes all object-relational mapping information is
correct, and dynamically builds an in-memory representation of the schema from
your mapping metadata. When using this factory, it is important that your
mapping metadata correctly represent your database's foreign key constraints so
that OpenJPA can order its SQL statements to meet them.
                    </p></li><li><p>
<code class="literal">native</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/LazySchemaFactory.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.schema.LazySchemaFactory</code></a>
. As persistent classes are loaded by the application, OpenJPA reads their
metadata and object-relational mapping information. This factory uses the
<code class="classname">java.sql.DatabaseMetaData</code> interface to reflect on the
schema and ensure that it is consistent with the mapping data being read.
Use this factory if you want up-front validation that your mapping metadata is 
consistent with the database during development. This factory accepts the 
following important properties:
                    </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">ForeignKeys</code>: Set to <code class="literal">true</code> to automatically
read foreign key information during schema validation.
                            </p></li></ul></div></li><li><p>
<code class="literal">table</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/TableSchemaFactory.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.schema.TableSchemaFactory</code></a>
. This schema factory stores schema information as an XML document in a database
table it creates for this purpose. If your JDBC driver doesn't support the
<code class="classname">java.sql.DatabaseMetaData</code> standard interface, but you
still want some schema validation to occur at runtime, you might use this
factory. It is not recommended for most users, though, because it is easy for
the stored XML schema definition to get out-of-synch with the actual database.
This factory accepts the following properties:
                    </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">Table</code>: The name of the table to create to store schema
information. Defaults to <code class="literal">OPENJPA_SCHEMA</code>.
                            </p></li><li><p>
<code class="literal">PrimaryKeyColumn</code>: The name of the table's numeric primary
key column. Defaults to <code class="literal">ID</code>.
                            </p></li><li><p>
<code class="literal">SchemaColumn</code>: The name of the table's string column for
holding the schema definition as an XML string. Defaults to <code class="literal">SCHEMA_DEF
</code>.
                            </p></li></ul></div></li><li><p>
<code class="literal">file</code>: This is an alias for the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="../javadoc/org/apache/openjpa/jdbc/schema/FileSchemaFactory.html" target="_top">
<code class="classname">org.apache.openjpa.jdbc.schema.FileSchemaFactory</code></a>
. This factory is a lot like the <code class="classname">TableSchemaFactory</code>, and
has the same advantages and disadvantages. Instead of storing its XML schema
definition in a database table, though, it stores it in a file. This factory
accepts the following properties:
                    </p><div class="itemizedlist"><ul type="circle"><li><p>
<code class="literal">File</code>: The resource name of the XML schema file. By default,
the factory looks for a resource called <code class="filename"> package.schema</code>,
located in any top-level directory of the <code class="literal">CLASSPATH</code> or in the
top level of any jar in your <code class="literal">CLASSPATH</code>.
                            </p></li></ul></div></li></ul></div><p>
You can switch freely between schema factories at any time. The XML file format
used by some factories is detailed in <a href="ref_guide_schema_xml.html" title="14.&nbsp; XML Schema Format">Section&nbsp;14, &#8220;
            XML Schema Format
        &#8221;</a>
. As with any OpenJPA plugin, you can can also implement your own schema
factory if you have needs not met by the existing options.
            </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_schema_def.html">Prev</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_dbsetup.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_schema_schematool.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">11.&nbsp;
            Default Schema
        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;13.&nbsp;
            Schema Tool
        </td></tr></table></div></body></html>