Apache/openjpa
1
0
Fork 0
mirror of https://github.com/apache/openjpa.git synced 2025-03-01 05:59:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

MetaDataFactory.newInstance method no longer needed. Continue work on docs

Browse Source 
(note: docs may temporarily be in invalid state).



git-svn-id: https://svn.apache.org/repos/asf/incubator/openjpa/trunk@452592 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
A. Abram White 2006-10-03 18:36:45 +00:00
parent f18ea3dd33
commit 174ae93d41
9 changed files with 474 additions and 316 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/meta/MappingRepository.java
View File

@ -266,14 +266,6 @@ public class MappingRepository
return getQueryKey(cls, name);
}
public MetaDataRepository newInstance() {
MappingRepository repos = new MappingRepository();
repos.setConfiguration(getConfiguration());
repos.startConfiguration();
repos.endConfiguration();
return repos;
}
public ClassMapping getMapping(Class cls, ClassLoader envLoader,
boolean mustExist) {
return (ClassMapping) super.getMetaData(cls, envLoader, mustExist);

6
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java
View File

@ -146,11 +146,9 @@ public class DataSourceFactory {
ecd.addListener(listeners[i]);
decorators.add(ecd);
// ask the DriverDataSource to provide any additional
// decorators
// ask the DriverDataSource to provide any additional decorators
if (ds instanceof DriverDataSource) {
List decs = ((DriverDataSource) ds).
createConnectionDecorators();
List decs = ((DriverDataSource)ds).createConnectionDecorators();
if (decs != null)
decorators.addAll(decs);
}

45
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java
View File

@ -30,34 +30,79 @@ import org.apache.openjpa.jdbc.sql.DBDictionary;
public interface DriverDataSource
extends DataSource {
/**
* JDBC URL.
*/
public void setConnectionURL(String connectionURL);
/**
* JDBC URL.
*/
public String getConnectionURL();
/**
* Driver class name.
*/
public void setConnectionDriverName(String connectionDriverName);
/**
* Driver class name.
*/
public String getConnectionDriverName();
/**
* JDBC user name.
*/
public void setConnectionUserName(String connectionUserName);
/**
* JDBC user name.
*/
public String getConnectionUserName();
/**
* JDBC password.
*/
public void setConnectionPassword(String connectionPassword);
/**
* JDBC password.
*/
public void setClassLoader(ClassLoader classLoader);
/**
* Classloader for loading driver class, etc.
*/
public ClassLoader getClassLoader();
/**
* Configuration of datasource properties.
*/
public void setConnectionFactoryProperties(Properties props);
/**
* Configuration of datasource properties.
*/
public Properties getConnectionFactoryProperties();
/**
* Configuration of connection.
*/
public void setConnectionProperties(Properties props);
/**
* Configuration of connection.
*/
public Properties getConnectionProperties();
/**
* Provide any built-in decorators; may be null.
*/
public List createConnectionDecorators();
/**
* Initialize self and dictionary once available.
*/
public void initDBDictionary(DBDictionary dict);
}

68
openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java
View File

@ -23,17 +23,14 @@ import java.sql.SQLException;
import java.util.List;
import java.util.Properties;
import org.apache.openjpa.jdbc.conf.JDBCConfiguration;
import org.apache.openjpa.jdbc.sql.DBDictionary;
import org.apache.openjpa.lib.conf.Configurable;
import org.apache.openjpa.lib.conf.Configuration;
import org.apache.openjpa.util.StoreException;
/**
* Non-pooling driver data source.
*/
public class SimpleDriverDataSource
implements DriverDataSource, Configurable {
implements DriverDataSource {
private String _connectionDriverName;
private String _connectionURL;
@ -41,7 +38,6 @@ public class SimpleDriverDataSource
private String _connectionPassword;
private Properties _connectionProperties;
private Properties _connectionFactoryProperties;
private JDBCConfiguration _conf;
private Driver _driver;
private ClassLoader _classLoader;
@ -68,7 +64,7 @@ public class SimpleDriverDataSource
public Connection getConnection(Properties props)
throws SQLException {
return _driver.connect(_conf.getConnectionURL(), props);
return getDriver().connect(_connectionURL, props);
}
public int getLoginTimeout() {
@ -85,33 +81,6 @@ public class SimpleDriverDataSource
public void setLogWriter(PrintWriter out) {
}
public void setConfiguration(Configuration conf) {
_conf = (JDBCConfiguration) conf;
}
public void startConfiguration() {
}
public void endConfiguration() {
try {
_driver = DriverManager.getDriver(_connectionURL);
if (_driver == null) {
try {
Class.forName(_connectionDriverName, true, _classLoader);
} catch (Exception e) {
}
_driver = DriverManager.getDriver(_connectionURL);
}
if (_driver == null)
_driver = (Driver) Class.forName(_connectionDriverName,
true, _classLoader).newInstance();
} catch (Exception e) {
if (e instanceof RuntimeException)
throw(RuntimeException) e;
throw new StoreException(e);
}
}
public void initDBDictionary(DBDictionary dict) {
}
@ -170,5 +139,38 @@ public class SimpleDriverDataSource
public String getConnectionDriverName() {
return _connectionDriverName;
}
private Driver getDriver() {
if (_driver != null)
return _driver;
try {
_driver = DriverManager.getDriver(_connectionURL);
if (_driver != null)
return _driver;
} catch (Exception e) {
}
try {
Class.forName(_connectionDriverName, true, _classLoader);
} catch (Exception e) {
}
try {
_driver = DriverManager.getDriver(_connectionURL);
if (_driver != null)
return _driver;
} catch (Exception e) {
}
try {
_driver = (Driver) Class.forName(_connectionDriverName,
true, _classLoader).newInstance();
return _driver;
} catch (Exception e) {
if (e instanceof RuntimeException)
throw(RuntimeException) e;
throw new StoreException(e);
}
}
}

12
openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java
View File

@ -156,18 +156,6 @@ public class MetaDataRepository
return _log;
}
/**
* Create a new instance of the same type as this instance, using this
* instance's configuration.
*/
public MetaDataRepository newInstance() {
MetaDataRepository repos = new MetaDataRepository();
repos.setConfiguration(_conf);
repos.startConfiguration();
repos.endConfiguration();
return repos;
}
/**
* The I/O used to load metadata.
*/

BIN
openjpa-project/src/doc/manual/img/string-rel-map.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 45 KiB

182
openjpa-project/src/doc/manual/ref_guide_deploy.xml
View File

@ -13,7 +13,7 @@ turn.
Factory Deployment
</title>
<para>
OpenJPA offers several <classname>EntityManagerFactory</classname>
OpenJPA offers two <classname>EntityManagerFactory</classname>
deployment options.
</para>
<section id="ref_guide_deploy_factory_standalone">
@ -44,19 +44,191 @@ Javadoc</ulink> details these extensions.
</para>
<para>
After obtaining the factory, you can cache it for all <classname>
EntityManager</classname> creation duties.
EntityManager</classname> creation duties. OpenJPA factories support being
bound to JNDI as well.
</para>
</section>
<section id="ref_guide_deploy_inject">
<title>
EntityManager Injection
</title>
<!-- ### -->
<para>
TBD
Java EE 5 application servers allow you to <emphasis>inject</emphasis>
entity managers into your session beans using the <literal>PersistenceContext
</literal> annotation. See your application server documentation for details.
</para>
</section>
</section>
<section id="ref_guide_enterprise_trans">
<title>
Integrating with the Transaction Manager
</title>
<indexterm zone="ref_guide_enterprise_trans">
<primary>
transactions
</primary>
<secondary>
managed
</secondary>
</indexterm>
<indexterm zone="ref_guide_enterprise_trans">
<primary>
TransactionManager
</primary>
<secondary>
integration
</secondary>
</indexterm>
<indexterm>
<primary>
managed transactions
</primary>
<see>
transactions
</see>
</indexterm>
<indexterm>
<primary>
TransactionMode
</primary>
</indexterm>
<para>
OpenJPA <classname>EntityManager</classname>s have the ability to automatically
synchronize their transactions with an external transaction manager.
###
If you
deploy via <link linkend="ref_guide_deploy_inject"><classname>EntityManager
</classname> injection</link> as described above, this synchronization is
typically automatic. Whether
or not <classname>EntityManager</classname>s from a given <classname>
EntityManagerFactory</classname> exhibit this behavior by default depends on
the <link linkend="kodo.TransactionMode">
<literal>kodo.TransactionMode</literal></link> configuration property.
The property can take the following values:
</para>
<para condition="jdo_notcombo">
Kodo <classname>PersistenceManager</classname>s have the ability
to automatically synchronize their transactions with an external
transaction manager. Whether or not <classname>
PersistenceManager</classname>s from a given
<classname>PersistenceManagerFactory</classname> exhibit this behavior
by default depends on the <link linkend="kodo.TransactionMode">
<literal>kodo.TransactionMode</literal></link> configuration property.
The property can take the following values:
</para>
<para condition="combo">
Kodo <classname>EntityManager</classname>s and <classname>
PersistenceManager</classname>s have the ability
to automatically synchronize their transactions with an external
transaction manager. Whether or not <classname>
EntityManager</classname>s and <classname>
PersistenceManager</classname>s from a given factory exhibit this
behavior by default depends on the <link linkend="kodo.TransactionMode">
<literal>kodo.TransactionMode</literal></link> configuration property.
The property can take the following values:
</para>
<itemizedlist>
<listitem>
<para>
<literal>local</literal>: Perform transaction operations
locally.
</para>
</listitem>
<listitem>
<para>
<literal>managed</literal>: Integrate with the application
server's managed global transactions.
</para>
</listitem>
</itemizedlist>
<para condition="ejb">
You can override the global transaction mode setting when you obtain an
<classname>EntityManager</classname> using the
<ulink url="&api-dir;/kodo/persistence/KodoEntityManagerFactory.html">
<classname>KodoEntityManagerFactory</classname></ulink>'s
<methodname>createEntityManager(PersistenceContextType ctype, boolean managed, int connRetainMode)
</methodname> method.
</para>
<para condition="jdo">
You can override the global transaction mode setting when you obtain a
<classname>PersistenceManager</classname> using the
<ulink url="&api-dir;/kodo/jdo/KodoPersistenceManagerFactory.html">
<classname>KodoPersistenceManagerFactory</classname></ulink>'s
<methodname>getPersistenceManager(boolean managed, int connRetainMode)
</methodname> method.
</para>
<para>
<indexterm><primary>ManagedRuntime</primary></indexterm>
In order to use global transactions, Kodo must be able to access
the application server's <classname>javax.transaction.TransactionManager
</classname>. Kodo can automatically discover the transaction
manager for most major application servers. Occasionally, however,
you might have to point Kodo to the transaction manager for an
unrecognized or non-standard application server setup. This is
accomplished through the <link linkend="kodo.ManagedRuntime"><literal>
kodo.ManagedRuntime</literal></link> configuration property. This
property describes a
<ulink url="&javadoc-dir;/kodo/ee/ManagedRuntime.html"><classname>
kodo.ee.ManagedRuntime</classname></ulink> implementation to use
for transaction manager discovery. You can specify your own
implementation, or use one of the built-ins:
</para>
<itemizedlist>
<listitem>
<para>
<literal>auto</literal>: This is the default. It is an alias
for the
<ulink url="&javadoc-dir;/kodo/ee/AutomaticManagedRuntime.html">
<classname>kodo.ee.AutomaticManagedRuntime</classname></ulink>
class. This managed runtime is able to automatically integrate
with several common application servers.
</para>
</listitem>
<listitem>
<para>
<literal>invocation</literal>: An alias for the
<ulink url="&javadoc-dir;/kodo/ee/InvocationManagedRuntime.html">
<classname>kodo.ee.InvocationManagedRuntime</classname></ulink>
class. You can configure this runtime to invoke any static
method in order to obtain the appserver's transaction manager.
</para>
</listitem>
<listitem>
<para>
<literal>jndi</literal>: An alias for the
<ulink url="&javadoc-dir;/kodo/ee/JNDIManagedRuntime.html">
<classname>kodo.ee.JNDIManagedRuntime</classname></ulink>
class. You can configure this runtime to look up the
transaction manager at any JNDI location.
</para>
</listitem>
</itemizedlist>
<para>
See the Javadoc for of each class for details on the bean properties
you can pass to these plugins in your configuration string.
</para>
&feature-enterprise;
<example id="ref_guide_enterprise_transex">
<title>Configuring Transaction Manager Integration</title>
<para condition="combo">JPA XML format:</para>
<programlisting condition="ejb">
<![CDATA[<property name="kodo.TransactionMode" value="managed"/>
<property name="kodo.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/>]]>
</programlisting>
<para condition="combo">JDO properties format:</para>
<programlisting condition="jdo">
kodo.TransactionMode: managed
kodo.ManagedRuntime: jndi(TransactionManagerName=java:/TransactionManager)
</programlisting>
</example>
<para>
Note that even when Kodo is using managed transaction, you can control
transactions through the specification local transaction APIs if you
wish. Kodo will propagate your transaction calls to the global
transaction.
</para>
</section>
<section id="ref_guide_enterprise_xa">
<title>
XA Transactions
@ -128,7 +300,7 @@ managed environment. The following components are required:
<listitem>
<para>
A managed environment that provides an XA compliant transaction manager.
Examples of this are application servers such as JBoss and WebLogic.
Examples of this are application servers such as WebLogic or JBoss.
</para>
</listitem>
<listitem>

342
openjpa-project/src/doc/manual/ref_guide_mapping.xml
View File

@ -46,8 +46,7 @@ specification.
their corresponding database schema from your object model. OpenJPA supports
forward mapping through the <emphasis>mapping tool</emphasis>. The next section
presents several common mapping tool use cases. You can invoke the tool through
the <literal>mappingtool</literal> shell/batch script included in the OpenJPA
distribution, or through its Java class,
its Java class,
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingTool"><classname>
org.apache.openjpa.jdbc.meta.MappingTool</classname></ulink>.
</para>
@ -115,7 +114,7 @@ the same-named option on the schema tool.
</listitem>
<listitem>
<para>
<literal>-openjpaTables/-kt &lt;true/t | false/f&gt;</literal>: Corresponds to
<literal>-openjpaTables/-ot &lt;true/t | false/f&gt;</literal>: Corresponds to
the same-named option on the schema tool.
</para>
</listitem>
@ -184,11 +183,10 @@ the action to take on each class. The available actions are:
<itemizedlist>
<listitem>
<para>
<literal>buildSchema</literal>: This is the default action when using JPA
mapping defaults (see <xref linkend="ref_guide_mapping_defaults"/> ). It
<literal>buildSchema</literal>: This is the default action. It
makes the database schema match your existing mappings. If your provided
mappings conflict with a class definition, OpenJPA will fail with an informative
exception.
mappings conflict with your class definitions, OpenJPA will fail with an
informative exception.
</para>
</listitem>
<listitem>
@ -222,7 +220,7 @@ The <filename>.class</filename> file of a persistent class.
<para>
If you do not supply any arguments to the mapping tool, it will run on the
classes in your persistent classes list (see
<xref linkend="ref_guide_pc_pcclasses"/> ).
<xref linkend="ref_guide_pc_pcclasses"/>).
</para>
<para>
The mappings generated by the mapping tool are stored by the system <emphasis>
@ -245,13 +243,9 @@ discusses your mapping factory options.
The JPA specification defines a comprehensive set of defaults for missing
mapping information. Thus, forward mapping in JPA is virtually automatic. After
using the mapping annotations covered in <xref linkend="jpa_overview_mapping"/>
of the JPA Overview to override any unsatisfactory defaults, run the
mapping tool's <literal>buildSchema</literal> action on your persistent classes.
This is the default action when you use JPA mapping defaults (see
<xref linkend="ref_guide_mapping_defaults"/> ).
</para>
<para>
The <literal>buildSchema</literal> action manipulates the database schema to
of the JPA Overview to override any unsatisfactory defaults, run the
mapping tool on your persistent classes. The default <literal>buildSchema
</literal> mapping tool action manipulates the database schema to
match your mappings. It fails if any of your mappings don't match your object
model.
</para>
@ -309,13 +303,12 @@ This example uses your existing mappings to determine the needed schema, then
writes the SQL to create that schema to <filename>create.sql</filename>.
</para>
<programlisting>
java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -sa build -sql create.sql Magazine.java
java org.apache.openjpa.jdbc.meta.MappingTool -sa build -sql create.sql Magazine.java
</programlisting>
</example>
<example id="ref_guid_mapping_ddl_part_ddl">
<title>
Create DDL to Update Database for Current
Mappings
Create DDL to Update Database for Current Mappings
</title>
<para>
This example uses your existing mappings to determine the needed schema. It then
@ -323,7 +316,7 @@ writes the SQL to add any missing tables and columns to the current schema to
<filename>update.sql</filename>.
</para>
<programlisting>
java org.apache.openjpa.jdbc.meta.MappingTool -a buildSchema -sql update.sql Magazine.java
java org.apache.openjpa.jdbc.meta.MappingTool -sql update.sql Magazine.java
</programlisting>
</example>
</section>
@ -356,8 +349,7 @@ meant for use during rapid test/debug cycles.
</para>
<para>
In order to enable automatic runtime mapping, you must first list all your
persistent classes as described in <xref linkend="ref_guide_pc_pcclasses"/>
.
persistent classes as described in <xref linkend="ref_guide_pc_pcclasses"/>.
</para>
<para>
OpenJPA will run the mapping tool on these classes when your application obtains
@ -423,13 +415,6 @@ in <xref linkend="ref_guide_mapping_middle"/>. The reverse mapping tool,
however, can give you an excellent starting point from which to grow your
persistent classes.
</para>
<!-- ### -->
<note>
<para>
The reverse mapping tool in this release does not yet output JPA annotations. It
is limited to JDO metadata output.
</para>
</note>
<para>
To use the reverse mapping tool, follow the steps below:
</para>
@ -470,8 +455,7 @@ proper relations between the persistent classes it creates.
<para>
Run the reverse mapping tool on the finished schema file. If you do not supply
the schema file to reverse map, the tool will run directly against the schema in
the database. The tool can be run via the included <literal>reversemappingtool
</literal> script, or through its Java class,
the database. The tool can be run via its Java class,
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ReverseMappingTool">
<classname>org.apache.openjpa.jdbc.meta.ReverseMappingTool</classname></ulink>.
</para>
@ -484,7 +468,7 @@ java org.apache.openjpa.jdbc.meta.ReverseMappingTool -pkg com.xyz -d ~/src -cp c
</programlisting>
</example>
<para>
In addition to OpenJPA's <link linkend="ref_guide_conf_devtools"> standard
In addition to OpenJPA's <link linkend="ref_guide_conf_devtools">standard
configuration flags</link>, including
<link linkend="ref_guide_conf_devtools_format">code formatting options</link>,
the reverse mapping tool recognizes the following command line arguments:
@ -630,8 +614,8 @@ the system defaults to a
<classname>PropertiesReverseCustomizer</classname></ulink>. This customizer
allows you to specify simple customization options in the properties file given
with the <literal>-customizerProperties</literal> flag below. We present the
available property keys <link linkend="ref_guide_pc_reverse_custom"> below
</link>.
available property keys <link linkend="ref_guide_pc_reverse_custom">
below</link>.
</para>
</listitem>
<listitem>
@ -652,7 +636,8 @@ property in the specified reverse customizer, and set to the given value.
<para>
Running the tool will generate <filename>.java</filename> files for each
generated class (and its application identity class, if applicable), along with
all necessary persistence metadata and mappings.
an <filename>orm.xml</filename> file containing the corresponding persistence
metadata.
</para>
</listitem>
<listitem>
@ -664,10 +649,12 @@ generates.
</para>
<para>
After you are satisfied with the generated classes and their mappings, you
should first compile them with <literal>javac</literal>, <literal>jikes
</literal>, or your favorite Java compiler. Make sure the classes and their
metadata are located in the directory corresponding to the <literal>-package
</literal> flag you gave the reverse mapping tool. Finally, enhance the classes
should first compile the classes with <literal>javac</literal>, <literal>
jikes</literal>, or your favorite Java compiler. Make sure the classes are
located in the directory corresponding to the <literal>-package</literal> flag
you gave the reverse mapping tool. Next, move the generated <filename>
orm.xml</filename> file to a <filename>META-INF</filename> directory within a
directory in your classpath. Finally, enhance the classes
if necessary (see <xref linkend="ref_guide_pc_enhance"/> ).
</para>
</listitem>
@ -843,11 +830,6 @@ com.xyz.Magazine.identity: datastore
com.xyz.pub.Company.identity: com.xyz.pub.CompanyId
</programlisting>
</example>
<para>
Your OpenJPA download includes the <classname> PropertiesReverseCustomizer
</classname> source code. You can use this code as an example when writing your
own customization class.
</para>
</section>
</section>
<section id="ref_guide_mapping_middle">
@ -883,10 +865,8 @@ In the <emphasis>meet-in-the-middle</emphasis>
mapping approach, you control both the relational model and the object model. It
is up to you to define the mappings between these models. The mapping
tool's <literal>validate</literal> action is useful to meet-in-the-middle
mappers. We examined the mapping tool in
<xref linkend="ref_guide_mapping_mappingtool"/>. The <literal>validate
</literal> action verifies that the mapping information for a class matches the
class definition and the existing schema. It throws an informative exception
mappers. This action verifies that the mapping information for a class matches
the class definition and the existing schema. It throws an informative exception
when your mappings are incorrect.
</para>
<example id="ref_guide_mapping_mappingtool_validate">
@ -907,18 +887,6 @@ data is correct, and modifies the schema to match your mappings. This lets you
modify your mapping data manually, but saves you the hassle of using your
database's tools to bring the schema up-to-date.
</para>
<para>
<literal>buildSchema</literal> is the default action when you use JPA mapping
defaults ( <xref linkend="ref_guide_mapping_defaults"/> ).
</para>
<example id="ref_guide_mapping_middle_buildschema_mid">
<title>
Creating the Relational Schema from Mappings
</title>
<programlisting>
java org.apache.openjpa.jdbc.meta.MappingTool Magazine.java
</programlisting>
</example>
</section>
<section id="ref_guide_mapping_defaults">
<title>
@ -945,7 +913,7 @@ The previous sections showed how to use the mapping tool to generate default
mappings. But how does the mapping tool know what mappings to generate? The
answer lies in the
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/MappingDefaults.html">
<classname> org.apache.openjpa.jdbc.meta.MappingDefaults</classname></ulink>
<classname>org.apache.openjpa.jdbc.meta.MappingDefaults</classname></ulink>
interface. OpenJPA uses an instance of this interface to decide how to name
tables and columns, where to put foreign keys, and generally how to create a
schema that matches your object model.
@ -954,7 +922,9 @@ schema that matches your object model.
<para>
OpenJPA relies on foreign key constraint information at runtime to order SQL
appropriately. Be sure to set your mapping defaults to reflect your existing
database constraints, or use explicit foreign key mappings as described in
database constraints, set the schema factory to reflect on the database for
constraint information (see <xref linkend="ref_guide_schema_info_factory"/>),
or use explicit foreign key mappings as described in
<xref linkend="ref_guide_mapping_jpa_fk"/>.
</para>
</important>
@ -962,7 +932,7 @@ database constraints, or use explicit foreign key mappings as described in
The <link linkend="openjpa.jdbc.MappingDefaults"><literal>
openjpa.jdbc.MappingDefaults</literal></link> configuration property controls
the <classname>MappingDefaults</classname> interface implementation in use. This
is a plugin property (see <xref linkend="ref_guide_conf_plugins"/> ), so
is a plugin property (see <xref linkend="ref_guide_conf_plugins"/>), so
you can substitute your own implementation or configure the existing ones.
OpenJPA includes the following standard implementations:
</para>
@ -990,20 +960,16 @@ properties:
<listitem>
<para>
<literal>DefaultMissingInfo</literal>: Whether to default missing column and
table names rather than throw an exception. Defaults to false, meaning full
table names rather than throw an exception. If set to false, full explicit
mappings are required at runtime and when using mapping tool actions like
<literal>buildSchema</literal> and <literal>validate</literal>.
</para>
<para>
The <literal>jpa</literal> plugin above sets this property to true to meet the
JPA specification.
</para>
</listitem>
<listitem>
<para>
<literal>BaseClassStrategy</literal>: The default mapping strategy for base
classes. You can specify a built-in strategy alias or the full class name of a
<link linkend="ref_guide_mapping_custom_class"> custom class strategy</link>.
<link linkend="ref_guide_mapping_custom_class">custom class strategy</link>.
You can also use OpenJPA's plugin format (see
<xref linkend="ref_guide_conf_plugins"/>) to pass arguments to the
strategy instance. See the
@ -1152,11 +1118,7 @@ indicator columns for embedded objects.
<listitem>
<para>
<literal>OrderLists</literal>: Whether to create a database ordering column for
maintaining the order of persistent lists and arrays. Defaults to true.
</para>
<para>
The <literal>jpa</literal> plugin above sets this property to false in
accordance with the JPA specification.
maintaining the order of persistent lists and arrays.
</para>
</listitem>
<listitem>
@ -1189,7 +1151,7 @@ value is the better choice.
<para>
The example below turns on foreign key generation during schema creation and
associates the <classname>org.mag.data.InfoStruct</classname> field type with
the custom <classname> org.mag.mapping.InfoStructHandler</classname> value
the custom <classname>org.mag.mapping.InfoStructHandler</classname> value
handler.
</para>
<example id="ref_guide_mapping_defaults_conf">
@ -1229,12 +1191,6 @@ to store the data necessary to map your persistent classes to the database
schema.
</para>
<para>
In JPA, mapping metadata is defined in annotations. Future versions of the JPA
drafts will also define a mapping XML format.
<xref linkend="jpa_overview_mapping"/> in the JPA Overview describes JPA
mapping options.
</para>
<para>
<xref linkend="ref_guide_meta_factory"/> introduced OpenJPA's <classname>
MetaDataFactory</classname> interface. OpenJPA uses this same interface to
abstract the storage and retrieval of mapping information. OpenJPA includes the
@ -1251,12 +1207,9 @@ The bundled mapping factories are:
<para>
<literal>-</literal>: Leaving the <literal> openjpa.jdbc.MappingFactory
</literal> property unset allows your metadata factory to take over mappings as
well.
</para>
<para>
If you are using the <literal>jpa</literal> metadata factory, OpenJPA will read
mapping information from your annotations and <filename>orm.xml</filename> when
you leave the mapping factory unspecified.
well. If you are using the default <literal>jpa</literal> metadata factory,
OpenJPA will read mapping information from your annotations and
<filename>orm.xml</filename> when you leave the mapping factory unspecified.
</para>
</listitem>
</itemizedlist>
@ -1369,8 +1322,8 @@ accomplish this in mapping metadata.
<programlisting>
@Entity
@Table(name="T1")
public class ...
{
public class ... {
@ManyToOne
@JoinColumns({
@JoinColumn(name="FK" referencedColumnName="PK1"),
@ -1389,8 +1342,8 @@ need single quotes for numeric constants. For example, the syntax to join
<programlisting>
@Entity
@Table(name="T1")
public class ...
{
public class ... {
@ManyToOne
@JoinColumns({
@JoinColumn(name="FK" referencedColumnName="PK2"),
@ -1405,8 +1358,8 @@ Finally, from the inverse direction, these joins would look like this:
<programlisting>
@Entity
@Table(name="T2")
public class ...
{
public class ... {
@ManyToOne
@JoinColumns({
@JoinColumn(name="T1.FK" referencedColumnName="PK1"),
@ -1529,8 +1482,8 @@ import org.apache.openjpa.persistence.jdbc.*;
@Entity
@Table(name="LOGS")
@DataStoreIdColumn(name="ENTRY")
public class LogEntry
{
public class LogEntry {
@Lob
private String content;
@ -1675,8 +1628,8 @@ this with the
annotation, which contains an array of <classname>Column</classname> values.
</para>
<para>
Remember to annotate custom field types with <classname> Persistent</classname>
, as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
Remember to annotate custom field types with <classname>Persistent</classname>,
as described in <xref linkend="ref_guide_meta_jpa_persistent"/>.
</para>
</section>
<section id="ref_guide_mapping_jpa_fieldjoin">
@ -1692,7 +1645,7 @@ to. Suppose, however, that the related type is unmapped, or that it is part of a
table-per-class inheritance hierarchy. Each subclass that might be assigned to
the field could reside in a different table, and could use entirely different
names for its primary key columns. It becomes impossible to supply a single
<literal> referencedColumnName</literal> that works for all subclasses.
<literal>referencedColumnName</literal> that works for all subclasses.
</para>
<para>
OpenJPA rectifies this by allowing you to declare which <emphasis>attribute
@ -1712,7 +1665,7 @@ For compound keys, use the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/XJoinColumns.html">
<classname>org.apache.openjpa.persistence.jdbc.XJoinColumns</classname></ulink>
annotation. The value of this annotation is an array of individual <classname>
XJoinColumn</classname> s.
XJoinColumn</classname>s.
</para>
</section>
<section id="ref_guide_mapping_jpa_embed">
@ -1836,8 +1789,8 @@ owning field will load as null.
import org.apache.openjpa.persistence.jdbc.*;
@Embeddable
public class PathCoordinate
{
public class PathCoordinate {
private String siteName;
@Persistent
@ -1848,8 +1801,8 @@ public class PathCoordinate
}
@Entity
public class Path
{
public class Path {
@Embedded
@EmbeddedMapping(nullIndicatorFieldName="siteName", overrides={
@MappingOverride(name="siteName", columns=@Column(name="START_SITE")),
@ -1991,28 +1944,6 @@ in the JPA Overview for a review of the <classname>JoinColumn</classname>
annotation.
</para>
</section>
<section id="ref_guide_mapping_jpa_coll_embed">
<title>
Element Embedded Mapping
</title>
<indexterm zone="ref_guide_mapping_jpa_coll_embed">
<primary>
ElementEmbeddedMapping
</primary>
<seealso>
mapping metadata
</seealso>
</indexterm>
<para>
The
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementEmbeddedMapping.html">
<classname>org.apache.openjpa.persistence.jdbc.ElementEmbeddedMapping
</classname></ulink> annotation allows you to map your collection or map's
embedded element type to your container table. This annotation has exactly the
same properties as the <classname>EmbeddedMapping</classname> annotation
described <link linkend="ref_guide_mapping_jpa_embed">above</link>.
</para>
</section>
<section id="ref_guide_mapping_jpa_coll_order">
<title>
Order Column
@ -2134,15 +2065,14 @@ import org.apache.openjpa.persistence.jdbc.*;
@Entity
@Table(name="LINE_ITEM", schema="CNTRCT")
public class LineItem
{
public class LineItem {
...
}
@Entity
@Table(name="SUB", schema="CNTRCT")
public class Subscription
{
public class Subscription {
@Id private long id;
@OneToMany
@ -2168,11 +2098,8 @@ public class Subscription
</indexterm>
<para>
We detailed the <literal>ContainerTable</literal> annotation in
<xref linkend="ref_guide_mapping_jpa_coll_table"/>. We also discussed
join columns embedded mappings in
<xref linkend="ref_guide_mapping_jpa_coll_joincols"/> and
<xref linkend="ref_guide_mapping_jpa_coll_embed"/>. Key columns, join
columns, and embedded mappings are new, however; we tackle them below.
<xref linkend="ref_guide_mapping_jpa_coll_table"/>. Custom map mappings may
also use this annotation to represent a map table.
</para>
</section>
<section id="ref_guide_mapping_jpa_constraints">
@ -2188,8 +2115,8 @@ batch size.
</para>
<para>
OpenJPA assumes certain columns have indexes or constraints based on your
mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>
. You can override the configured defaults on individual joins, field
mapping defaults, as detailed in <xref linkend="ref_guide_mapping_defaults"/>.
You can override the configured defaults on individual joins, field
values, collection elements, map keys, or map values using the annotations
presented in the following sections.
</para>
@ -2216,14 +2143,10 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Index.html">
annotation represents an index on the columns of a field. It is also used within
the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>ContainerTable
</classname></link> annotation to index join columns.
</para>
<para>
To index the columns of a collection or map element or map key, use the
To index the columns of a collection element, use the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementIndex.html">
<classname> org.apache.openjpa.persistence.jdbc.ElementIndex</classname></ulink>
and <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyIndex.html">
<classname>org.apache.openjpa.persistence.jdbc.KeyIndex</classname></ulink>
annotations, respectively. These annotations have the following properties:
annotation. These annotations have the following properties:
</para>
<itemizedlist>
<listitem>
@ -2270,18 +2193,11 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ForeignKey.html">
annotation represents a foreign key on the columns of a field. It is also used
within the <link linkend="ref_guide_mapping_jpa_coll_table"><classname>
ContainerTable</classname></link> annotation to set a database foreign key on
join columns.
</para>
<para>
To set a constraint to the columns of a collection or map element or map value,
use the
join columns. To set a constraint to the columns of a collection element, use
the
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementForeignKey.html">
<classname> org.apache.openjpa.persistence.jdbc.ElementForeignKey</classname>
</ulink> and
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyForeignKey.html">
<classname> org.apache.openjpa.persistence.jdbc.KeyForeignKey</classname>
</ulink> annotations, respectively. These annotations have the following
properties:
</ulink> annotation. These annotations have the following properties:
</para>
<itemizedlist>
<listitem>
@ -2327,7 +2243,9 @@ Keep in mind that OpenJPA uses foreign key information at runtime to avoid
constraint violations; it is important, therefore, that your
<link linkend="ref_guide_mapping_defaults">mapping defaults</link> and foreign
key annotations combine to accurately reflect your existing database
constraints.
constraints, or that you configure OpenJPA to reflect on your database schema
to discover existing foreign keys (see
<xref linkend="ref_guide_schema_info_factory"/>).
</para>
</section>
<section id="ref_guide_mapping_jpa_unique">
@ -2351,7 +2269,7 @@ constraints.
The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Unique.html">
<classname>org.apache.openjpa.persistence.jdbc.Unique</classname></ulink>
annotation represents a unqiue constraint on the columns of a field. It is more
convenient than using the <literal> uniqueConstraints</literal> property of
convenient than using the <literal>uniqueConstraints</literal> property of
standard JPA <classname>Table</classname> and <classname>SecondaryTable
</classname> annotations, because you can apply it directly to the constrained
field. The <classname>Unique</classname> annotation has the following
@ -2379,22 +2297,6 @@ supported by the database.
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_mapping_jpa_constraintex">
<title>
Examples
</title>
<para>
Here again is our map example from <xref linkend="ref_guide_mapping_jpa_map"/>
, now with explicit indexes and constraints added.
</para>
<mediaobject>
<imageobject>
<!-- PNG image data, 410 x 266 (see README) -->
<imagedata fileref="img/string-rel-map.png" width="273px"/>
</imageobject>
</mediaobject>
</section>
</section>
</section>
<section id="ref_guide_mapping_limits">
@ -2663,7 +2565,7 @@ efficiency of your relations.
<note>
<para>
OpenJPA also includes the <literal>type</literal> metadata extension for
narrowing the declared type of a field See <xref linkend="type"/>.
narrowing the declared type of a field. See <xref linkend="type"/>.
</para>
</note>
<para>
@ -2681,13 +2583,6 @@ OpenJPA defines the following extensions for nonpolymorphic values:
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementNonpolymorphic.html">
<classname>org.apache.openjpa.persistence.jdbc.ElementNonpolymorphic</classname>
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyNonpolymorphic.html">
<classname>org.apache.openjpa.persistence.jdbc.KeyNonpolymorphic</classname>
</ulink>
</para>
</listitem>
@ -2741,9 +2636,8 @@ In these cases, set the proper class critera extension to <literal>true
</literal> to force OpenJPA to append class criteria to its select SQL.
</para>
<para>
OpenJPA defines the following class criteria annotations for field relations,
array, collection, and map element relations, and map key relations,
respectively:
OpenJPA defines the following class criteria annotations for field relations and
array or collection element relations, respectively:
</para>
<itemizedlist>
<listitem>
@ -2756,13 +2650,6 @@ respectively:
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/ElementClassCriteria.html">
<classname>org.apache.openjpa.persistence.jdbc.ElementClassCriteria</classname>
</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyClassCriteria.html">
<classname>org.apache.openjpa.persistence.jdbc.KeyClassCriteria</classname>
</ulink>
</para>
</listitem>
@ -2787,54 +2674,14 @@ respectively:
</seealso>
</indexterm>
<para>
OpenJPA's family of strategy extensions allow you to specify a custom mapping
OpenJPA's
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
extension allows you to specify a custom mapping
strategy or value handler for a field. See
<xref linkend="ref_guide_mapping_custom"/> for information on custom
mappings.
</para>
<para>
OpenJPA includes the following JPA strategy annotations:
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>:
Field strategy or value handler plugin string.
</para>
</listitem>
<listitem>
<para>
<ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/KeyStrategy.html">
<classname>org.apache.openjpa.persistence.jdbc.KeyStrategy</classname></ulink>:
Map key value handler plugin string.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
<literal>jdbc-strategy</literal>: Field strategy or value handler plugin
string.
</para>
</listitem>
<listitem>
<para>
<literal>jdbc-element-strategy</literal>: Collection or array element value
handler plugin string.
</para>
</listitem>
<listitem>
<para>
<literal>jdbc-key-strategy</literal>: Map key value handler plugin string.
</para>
</listitem>
<listitem>
<para>
<literal>jdbc-value-strategy</literal>: Map value handler plugin string.
</para>
</listitem>
</itemizedlist>
</section>
</section>
</section>
@ -2882,8 +2729,7 @@ The <ulink url="../apidocs/org/apache/openjpa/persistence/jdbc/Strategy.html">
annotation allows you to declare a custom class mapping strategy in JPA mapping
metadata. Set the value of the annotation to the full class name of your custom
strategy. You can configure your strategy class' bean properties using
OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins"/>
.
OpenJPA's plugin syntax, detailed in <xref linkend="ref_guide_conf_plugins"/>.
</para>
</section>
<section id="ref_guide_mapping_custom_versdiscrim">
@ -2957,19 +2803,10 @@ Value handlers make it trivial to map any type that you can break down into one
or more simple values. All value handlers implement the <classname>
org.apache.openjpa.jdbc.meta.ValueHandler</classname> interface; see its
<ulink url="../apidocs/org/apache/openjpa/jdbc/meta/ValueHandler.html"> Javadoc
</ulink> for details. Rather than give synthetic examples of value handlers,
OpenJPA provides the source to most of the built-in handlers in the <filename>
src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA distribution.
Use these functional implementations as examples when you create your own value
handlers.
</para>
<para>
Note that value handlers are not only simple to write, but are highly reusable.
For example, imagine that you create a handler for <classname>java.awt.Point
</classname> values. You can not only use this handler to map fields of type
<classname>Point</classname>, but also to map <classname> Collection</classname>
s or <classname>Map</classname>s of <classname>Point</classname>s with no
additional work.
</ulink> for details. Also, examine the built-in handlers in the <filename>
src/openjpa/jdbc/meta/strats</filename> directory of your OpenJPA source
distribution. Use these functional implementations as examples when you
create your own value handlers.
</para>
</section>
<section id="ref_guide_mapping_custom_fieldstrat">
@ -3020,8 +2857,8 @@ MappingDefaults</classname> implementations allows you to globally associate
field types with their corresponding custom value handler or strategy. OpenJPA
will automatically use your custom strategies when it encounters a field of the
associated type. OpenJPA will use your custom value handlers whenever it
encounters a field, collection element, map key, or map value of the associated
type. <xref linkend="ref_guide_mapping_defaults"/> described mapping
encounters a field of the associated type.
<xref linkend="ref_guide_mapping_defaults"/> described mapping
defaults in detail.
</para>
<para>
@ -3032,7 +2869,7 @@ in the proper mapping metadata extension. OpenJPA includes the
<classname>org.apache.openjpa.persistence.jdbc.Strategy</classname></ulink>
annotation. You can configure the named strategy or handler's bean
properties in these extensions using OpenJPA's plugin format (see
<xref linkend="ref_guide_conf_plugins"/> ).
<xref linkend="ref_guide_conf_plugins"/>).
</para>
</section>
</section>
@ -3092,16 +2929,13 @@ openjpa.Runtime</literal>.
</listitem>
<listitem>
<para>
<literal>exception</literal>: Throw an exception when OpenJPA discovers an
<literal>exception</literal>: Throw an <classname>
EntityNotFoundException</classname> when OpenJPA discovers an
orphaned key. This is an alias for the
<ulink url="../apidocs/org/apache/openjpa/event/ExceptionOrphanedKeyAction.html">
<classname>org.apache.openjpa.event.ExceptionOrphanedKeyAction</classname>
</ulink> class.
</para>
<para>
In JPA, the exception type will be <classname>
javax.persistence.EntityNotFoundException</classname>.
</para>
</listitem>
<listitem>
<para>

127
openjpa-project/src/doc/manual/ref_guide_meta.xml
View File

@ -230,6 +230,133 @@ annotation exists. For example, <xref linkend="ref_guide_mapping_jpa_columns"/>
to denote a persistent <classname>java.awt.Point</classname> field.
</para>
</section>
<section id="ref_guide_meta_jpa_persistent_coll">
<title>Persistent Collection Fields</title>
<indexterm zone="ref_guide_meta_jpa_persistent_coll">
<primary>persistent fields</primary>
<secondary>collection metadata</secondary>
</indexterm>
<para>
JPA standardizes support for collections of entities with the <literal>
OneToMany</literal> and <literal>ManyToMany</literal> persistence strategies.
OpenJPA supports these strategies, and may be extended for other strategies as
well. For extended strategies, use the
<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentCollection.html">
<classname>kodo.persistence.PersistentCollection</classname></ulink> metadata
annotation to represents any persistent collection field. It has the following
properties:
</para>
<itemizedlist>
<listitem>
<para>
<literal>Class elementType</literal>: The class of the collection elements.
This information is usually taken from the parameterized collection element
type. You must supply it explicitly, however, if your field isn't a
parameterized type.
</para>
</listitem>
<listitem>
<para>
<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
lazily. Corresponds exactly to the same-named property of standard JPA
annotations such as <link linkend="ejb3_overview_meta_basic"><classname>
Basic</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>String mappedBy</literal>: Names the field in the related entity that
maps this bidirectional relation. Corresponds to the same-named property of
standard JPA annotations such as <link linkend="ejb3_overview_meta_manytomany">
<classname>ManyToMany</classname></link>.
</para>
</listitem>
<listitem>
<para>
<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
cascade behavior for the collection elements. Corresponds exactly to the
<literal>cascade</literal> property of standard JPA annotations such as
<link linkend="ejb3_overview_meta_manytomany"><classname>
ManyToMany</classname></link>. Defaults to empty array.
</para>
</listitem>
<listitem>
<para>
<literal>boolean elementEmbedded</literal>: Set this property to <literal>true
</literal> if the elements are stored as embedded objects.
</para>
</listitem>
</itemizedlist>
</section>
<section id="ref_guide_meta_jpa_persistent_map">
<title>Persistent Map Fields</title>
<indexterm zone="ref_guide_meta_jpa_persistent_map">
<primary>persistent fields</primary>
<secondary>map metadata</secondary>
</indexterm>
<para>
JPA has limited support for maps. If you extend JPA's standard map support to
encompass new mappings, use the
<ulink url="../apidocs/org/apache/openjpa/persistence/PersistentMap.html">
<classname>kodo.persistence.PersistentMap</classname></ulink> metadata
annotation to represent your custom persistent map fields. It has the
following properties:
</para>
<itemizedlist>
<listitem>
<para>
<literal>Class keyType</literal>: The class of the map keys. This information
is usually taken from the parameterized map key type. You must supply it
explicitly, however, if your field isn't a parameterized type.
</para>
</listitem>
<listitem>
<para>
<literal>Class elementType</literal>: The class of the map values. This
information is usually taken from the parameterized map value type. You must
supply it explicitly, however, if your field isn't a parameterized type.
</para>
</listitem>
<listitem>
<para>
<literal>FetchType fetch</literal>: Whether to load the collection eagerly or
lazily. Corresponds exactly to the same-named property of standard JPA
annotations such as <link linkend="ejb3_overview_meta_basic"><classname>
Basic</classname></link>. Defaults to <literal>FetchType.LAZY</literal>.
</para>
</listitem>
<listitem>
<para>
<literal>CascadeType[] keyCascade</literal>: Array of enum values defining
cascade behavior for the map keys. Corresponds exactly to the <literal>cascade
</literal> property of standard JPA annotations such as
<link linkend="ejb3_overview_meta_manytoone"><classname>
ManyToOne</classname></link>. Defaults to empty array.
</para>
</listitem>
<listitem>
<para>
<literal>CascadeType[] elementCascade</literal>: Array of enum values defining
cascade behavior for the map values. Corresponds exactly to the
<literal>cascade</literal> property of standard JPA annotations such as
<link linkend="ejb3_overview_meta_manytoone"><classname>
ManyToOne</classname></link>. Defaults to empty array.
</para>
</listitem>
<listitem>
<para>
<literal>boolean keyEmbedded</literal>: Set this property to <literal>true
</literal> if the map keys are stored as embedded objects.
</para>
</listitem>
<listitem>
<para>
<literal>boolean elementEmbedded</literal>: Set this property to <literal>
true</literal> if the map values are stored as embedded objects.
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section id="ref_guide_meta_ext">
<title>