From bdae6535ecc59a972cc27a9ca65971d063512f41 Mon Sep 17 00:00:00 2001 From: "A. Abram White" Date: Mon, 2 Oct 2006 22:22:18 +0000 Subject: [PATCH] Miscellaneous cleanup and fixes. Some documentation review. git-svn-id: https://svn.apache.org/repos/asf/incubator/openjpa/trunk@452243 13f79535-47bb-0310-9956-ffa450edef68 --- .../kernel/PreparedStatementManagerImpl.java | 5 +- .../jdbc/schema/DataSourceFactory.java | 28 +- .../openjpa/jdbc/schema/DriverDataSource.java | 3 +- .../jdbc/schema/SimpleDriverDataSource.java | 69 +- .../apache/openjpa/kernel/AttachStrategy.java | 2 - .../org/apache/openjpa/kernel/BrokerImpl.java | 8 +- .../openjpa/kernel/SingleFieldManager.java | 34 +- .../openjpa/kernel/StateManagerImpl.java | 4 +- .../openjpa/meta/MetaDataRepository.java | 9 +- .../apache/openjpa/event/localizer.properties | 3 +- .../AnnotationPersistenceMetaDataParser.java | 86 +- .../openjpa/persistence/MetaDataParsers.java | 88 ++ .../OpenJPAEntityManagerFactory.java | 11 +- .../PersistenceMetaDataDefaults.java | 64 +- .../PersistenceMetaDataFactory.java | 28 +- .../PersistenceProductDerivation.java | 35 +- .../XMLPersistenceMetaDataParser.java | 78 +- .../openjpa/persistence/localizer.properties | 20 +- .../src/doc/manual/jpa_overview_arch.xml | 48 +- .../doc/manual/jpa_overview_conclusion.xml | 10 +- .../src/doc/manual/jpa_overview_em.xml | 147 +-- .../src/doc/manual/jpa_overview_emfactory.xml | 64 +- .../src/doc/manual/jpa_overview_mapping.xml | 413 ++++---- .../src/doc/manual/jpa_overview_meta.xml | 235 ++--- .../src/doc/manual/jpa_overview_pc.xml | 162 ++- .../doc/manual/jpa_overview_persistence.xml | 35 +- .../src/doc/manual/jpa_overview_query.xml | 736 ++++++------- .../src/doc/manual/jpa_overview_sqlquery.xml | 23 +- .../src/doc/manual/jpa_overview_trans.xml | 42 +- .../src/doc/manual/jpa_overview_why.xml | 4 +- .../src/doc/manual/jpa_resources.xml | 2 +- openjpa-project/src/doc/manual/manual.xml | 11 +- .../src/doc/manual/openjpa_intro.xml | 41 +- .../src/doc/manual/ref_guide_caching.xml | 21 +- .../src/doc/manual/ref_guide_conf.xml | 546 +++++----- .../src/doc/manual/ref_guide_dbsetup.xml | 964 +++--------------- .../src/doc/manual/ref_guide_deploy.xml | 12 +- .../src/doc/manual/ref_guide_integration.xml | 2 +- .../src/doc/manual/ref_guide_intro.xml | 13 +- .../src/doc/manual/ref_guide_logging.xml | 43 +- .../src/doc/manual/ref_guide_mapping.xml | 21 +- .../src/doc/manual/ref_guide_meta.xml | 290 +----- .../src/doc/manual/ref_guide_optimization.xml | 12 +- .../src/doc/manual/ref_guide_pc.xml | 410 +++----- .../src/doc/manual/ref_guide_remote.xml | 10 +- .../src/doc/manual/ref_guide_runtime.xml | 64 +- .../src/doc/manual/supported_databases.xml | 12 +- 47 files changed, 1878 insertions(+), 3090 deletions(-) create mode 100644 openjpa-persistence/src/main/java/org/apache/openjpa/persistence/MetaDataParsers.java diff --git a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/PreparedStatementManagerImpl.java b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/PreparedStatementManagerImpl.java index 16658795b..06ab0b927 100644 --- a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/PreparedStatementManagerImpl.java +++ b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/kernel/PreparedStatementManagerImpl.java @@ -102,10 +102,7 @@ class PreparedStatementManagerImpl } catch (SQLException se) { throw SQLExceptions.getStore(se, row.getFailedObject(), _dict); } finally { - try { - stmnt.close(); - } catch (SQLException se) { - } + try { stmnt.close(); } catch (SQLException se) {} } // set auto assign values diff --git a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java index 90ba0c539..5ccdf2b97 100644 --- a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java +++ b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DataSourceFactory.java @@ -60,8 +60,7 @@ public class DataSourceFactory { */ public static DataSource newDataSource(JDBCConfiguration conf, boolean factory2) { - String driver = (factory2) - ? conf.getConnection2DriverName() + String driver = (factory2) ? conf.getConnection2DriverName() : conf.getConnectionDriverName(); if (driver == null || driver.length() == 0) throw new UserException(_loc.get("no-driver", driver)). @@ -69,12 +68,10 @@ public class DataSourceFactory { ClassLoader loader = conf.getClassResolverInstance(). getClassLoader(DataSourceFactory.class, null); - String props = (factory2) - ? conf.getConnection2Properties() + String props = (factory2) ? conf.getConnection2Properties() : conf.getConnectionProperties(); try { Class driverClass; - try { driverClass = Class.forName(driver, true, loader); } catch (ClassNotFoundException cnfe) { @@ -86,25 +83,23 @@ public class DataSourceFactory { DriverDataSource ds = conf.newDriverDataSourceInstance(); ds.setClassLoader(loader); ds.setConnectionDriverName(driver); - ds.setConnectionProperties - (Configurations.parseProperties(props)); + ds.setConnectionProperties(Configurations. + parseProperties(props)); if (!factory2) { - ds.setConnectionFactoryProperties - (Configurations.parseProperties - (conf.getConnectionFactoryProperties())); + ds.setConnectionFactoryProperties(Configurations. + parseProperties(conf.getConnectionFactoryProperties())); ds.setConnectionURL(conf.getConnectionURL()); ds.setConnectionUserName(conf.getConnectionUserName()); ds.setConnectionPassword(conf.getConnectionPassword()); } else { ds.setConnectionFactoryProperties - (Configurations.parseProperties - (conf.getConnectionFactory2Properties())); + (Configurations.parseProperties(conf. + getConnectionFactory2Properties())); ds.setConnectionURL(conf.getConnection2URL()); ds.setConnectionUserName(conf.getConnection2UserName()); ds.setConnectionPassword(conf.getConnection2Password()); } - return ds; } @@ -121,8 +116,7 @@ public class DataSourceFactory { } // not a driver or a data source; die - throw new UserException(_loc.get("bad-driver", driver)). - setFatal(true); + throw new UserException(_loc.get("bad-driver", driver)).setFatal(true); } /** @@ -186,7 +180,6 @@ public class DataSourceFactory { DecoratingDataSource ds, final JDBCConfiguration conf, boolean factory2) { DataSource inner = ds.getInnermostDelegate(); - if (inner instanceof DriverDataSource) ((DriverDataSource) inner).initDBDictionary(dict); @@ -204,8 +197,7 @@ public class DataSourceFactory { // transaction isolation, etc) ConfiguringConnectionDecorator ccd = new ConfiguringConnectionDecorator(); - ccd.setTransactionIsolation - (conf.getTransactionIsolationConstant()); + ccd.setTransactionIsolation(conf.getTransactionIsolationConstant()); if (factory2 || !conf.isConnectionFactoryModeManaged()) { if (!dict.supportsMultipleNontransactionalResultSets) ccd.setAutoCommit(Boolean.FALSE); diff --git a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java index 433892537..b6719e822 100644 --- a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java +++ b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/DriverDataSource.java @@ -20,7 +20,6 @@ import java.util.Properties; import javax.sql.DataSource; import org.apache.openjpa.jdbc.sql.DBDictionary; -import org.apache.openjpa.lib.conf.Configurable; /** * A DataSource that allows additional configuration options to be set @@ -29,7 +28,7 @@ import org.apache.openjpa.lib.conf.Configurable; * @author Marc Prud'hommeaux */ public interface DriverDataSource - extends DataSource, Configurable { + extends DataSource { public void setConnectionURL(String connectionURL); diff --git a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java index 618bec618..dde074676 100644 --- a/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java +++ b/openjpa-jdbc/src/main/java/org/apache/openjpa/jdbc/schema/SimpleDriverDataSource.java @@ -25,10 +25,15 @@ 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 { + implements DriverDataSource, Configurable { private String _connectionDriverName; private String _connectionURL; @@ -40,38 +45,6 @@ public class SimpleDriverDataSource private Driver _driver; private ClassLoader _classLoader; - private synchronized Driver getDriver() - throws SQLException { - if (_driver == null) - _driver = DriverManager.getDriver(_connectionURL); - - if (_driver == null) { - try { - Class.forName(_connectionDriverName, true, _classLoader); - } catch (Exception e) { - } - - _driver = DriverManager.getDriver(_connectionURL); - } - - if (_driver == null) { - try { - _driver = (Driver) Class.forName(_connectionDriverName, - true, _classLoader).newInstance(); - } catch (Exception e) { - if (e instanceof SQLException) - throw(SQLException) e; - - if (e instanceof RuntimeException) - throw(RuntimeException) e; - - throw new SQLException(e.getClass() + ": " + e.getMessage()); - } - } - - return _driver; - } - public Connection getConnection() throws SQLException { return getConnection(null); @@ -80,16 +53,13 @@ public class SimpleDriverDataSource public Connection getConnection(String username, String password) throws SQLException { Properties props = new Properties(); - if (username == null) username = _connectionUserName; - if (username != null) props.put("user", username); if (password == null) password = _connectionPassword; - if (password != null) props.put("password", password); @@ -98,7 +68,7 @@ public class SimpleDriverDataSource public Connection getConnection(Properties props) throws SQLException { - return getDriver().connect(_conf.getConnectionURL(), props); + return _driver.connect(_conf.getConnectionURL(), props); } public int getLoginTimeout() { @@ -115,14 +85,31 @@ public class SimpleDriverDataSource public void setLogWriter(PrintWriter out) { } + public void setConfiguration(Configuration conf) { + _conf = (JDBCConfiguration) conf; + } + public void startConfiguration() { } public void endConfiguration() { - } - - public void setConfiguration(Configuration conf) { - _conf = (JDBCConfiguration) conf; + 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) { diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/AttachStrategy.java b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/AttachStrategy.java index f6dc12fd6..26a9b0986 100644 --- a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/AttachStrategy.java +++ b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/AttachStrategy.java @@ -202,8 +202,6 @@ abstract class AttachStrategy break; case JavaTypes.COLLECTION: Collection frmc = (Collection) fetchObjectField(i); - System.out.println("Fetch:" + fmd + ":" + frmc - + ":" + nullLoaded); if (frmc == null && !nullLoaded) return false; Collection toc = (Collection) sm.fetchObjectField(i); diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/BrokerImpl.java b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/BrokerImpl.java index cbd9a438d..6a3322d51 100644 --- a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/BrokerImpl.java +++ b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/BrokerImpl.java @@ -1233,10 +1233,7 @@ public class BrokerImpl catch (RuntimeException re) { if (!rollback) { forcedRollback = true; - try { - _store.rollback(); - } catch (RuntimeException re2) { - } + try { _store.rollback(); } catch (RuntimeException re2) {} } err = re; } finally { @@ -3794,8 +3791,7 @@ public class BrokerImpl _transAdditions = new HashSet(); _transAdditions.add(sm); } - } - finally { + } finally { unlock(); } } diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/SingleFieldManager.java b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/SingleFieldManager.java index b1a07b770..cb2fb1e6f 100644 --- a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/SingleFieldManager.java +++ b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/SingleFieldManager.java @@ -250,22 +250,22 @@ class SingleFieldManager case JavaTypes.PC_UNTYPED: if (!_broker.isDetachedNew() && _broker.isDetached(objval)) return; // allow but ignore - _broker.persist(objval, false, call); + _broker.persist(objval, true, call); break; case JavaTypes.ARRAY: - _broker.persistAll(Arrays.asList((Object[]) objval), false, + _broker.persistAll(Arrays.asList((Object[]) objval), true, call); break; case JavaTypes.COLLECTION: - _broker.persistAll((Collection) objval, false, call); + _broker.persistAll((Collection) objval, true, call); break; case JavaTypes.MAP: if (fmd.getKey().getCascadePersist() == ValueMetaData.CASCADE_IMMEDIATE) - _broker.persistAll(((Map) objval).keySet(), false, call); + _broker.persistAll(((Map) objval).keySet(), true, call); if (fmd.getElement().getCascadePersist() == ValueMetaData.CASCADE_IMMEDIATE) - _broker.persistAll(((Map) objval).values(), false, call); + _broker.persistAll(((Map) objval).values(), true, call); break; } } @@ -615,8 +615,8 @@ class SingleFieldManager if (external) val = fmd.getExternalValue(val, _broker); else if (val instanceof Proxy) { - // shortcut change trackers; also ensures we don't iterate - // lrs fields + // shortcut change trackers; also ensures we don't + // iterate lrs fields ChangeTracker ct = ((Proxy) val).getChangeTracker(); if (ct != null && ct.isTracking()) { preFlushPCs(fmd.getElement(), ct.getAdded(), @@ -646,8 +646,8 @@ class SingleFieldManager val = fmd.getExternalValue(val, _broker); external = false; } else if (val instanceof Proxy) { - // shortcut change trackers; also ensures we don't iterate - // lrs fields + // shortcut change trackers; also ensures we don't + // iterate lrs fields MapChangeTracker ct = (MapChangeTracker) ((Proxy) val). getChangeTracker(); if (ct != null && ct.isTracking() && ct.getTrackKeys()) @@ -670,8 +670,8 @@ class SingleFieldManager if (external) val = fmd.getExternalValue(val, _broker); else if (val instanceof Proxy) { - // shortcut change trackers; also ensures we don't iterate - // lrs fields + // shortcut change trackers; also ensures we don't + // iterate lrs fields MapChangeTracker ct = (MapChangeTracker) ((Proxy) val). getChangeTracker(); if (ct != null && ct.isTracking()) { @@ -743,10 +743,9 @@ class SingleFieldManager sm = _broker.getStateManager(obj); if (sm == null || !sm.isPersistent()) - throw new InvalidStateException - (_loc.get("cant-cascade-persist", - Exceptions.toString(obj), vmd, - Exceptions.toString(_sm.getManagedInstance()))). + throw new InvalidStateException(_loc.get("cant-cascade-persist", + Exceptions.toString(obj), vmd, + Exceptions.toString(_sm.getManagedInstance()))). setFailedObject(obj); } else { sm = _broker.getStateManager(obj); @@ -763,8 +762,9 @@ class SingleFieldManager Exceptions.toString(_sm.getManagedInstance()))). setFailedObject(obj); - ((StateManagerImpl) sm).nonprovisional(logical, call); - ((StateManagerImpl) sm).setDereferencedDependent(false, true); + StateManagerImpl smimpl = (StateManagerImpl) sm; + smimpl.nonprovisional(logical, call); + smimpl.setDereferencedDependent(false, true); } } diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/StateManagerImpl.java b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/StateManagerImpl.java index 3550af077..d44495b7e 100644 --- a/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/StateManagerImpl.java +++ b/openjpa-kernel/src/main/java/org/apache/openjpa/kernel/StateManagerImpl.java @@ -486,8 +486,8 @@ public class StateManagerImpl * @param recache whether to recache ourself on the new oid */ private void assertObjectIdAssigned(boolean recache) { - if (!isNew() || isDeleted() || isProvisional() || - (_flags & FLAG_OID_ASSIGNED) > 0) + if (!isNew() || isDeleted() || isProvisional() + || (_flags & FLAG_OID_ASSIGNED) != 0) return; if (_oid == null) { if (_meta.getIdentityType() == ClassMetaData.ID_DATASTORE) diff --git a/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java b/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java index ab755d4b0..d0245f7b6 100644 --- a/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java +++ b/openjpa-kernel/src/main/java/org/apache/openjpa/meta/MetaDataRepository.java @@ -340,8 +340,7 @@ public class MetaDataRepository classList.add(cls); break; } - } - catch (Throwable t) { + } catch (Throwable t) { // this happens when the class is not loadable by // the environment class loader, so it was probably // listed elsewhere; also ignore linkage failures and @@ -364,8 +363,7 @@ public class MetaDataRepository if (!mustExist) return null; - throw new MetaDataException(_loc.get("no-alias-meta", alias, - _aliases)); + throw new MetaDataException(_loc.get("no-alias-meta", alias, _aliases)); } /** @@ -408,8 +406,7 @@ public class MetaDataRepository // class never registers itself with the system if ((_validate & VALIDATE_RUNTIME) != 0) { try { - Class.forName(cls.getName(), true, - cls.getClassLoader()); + Class.forName(cls.getName(), true, cls.getClassLoader()); } catch (Throwable t) { } } diff --git a/openjpa-kernel/src/main/resources/org/apache/openjpa/event/localizer.properties b/openjpa-kernel/src/main/resources/org/apache/openjpa/event/localizer.properties index ef0994dc4..0984a4633 100644 --- a/openjpa-kernel/src/main/resources/org/apache/openjpa/event/localizer.properties +++ b/openjpa-kernel/src/main/resources/org/apache/openjpa/event/localizer.properties @@ -74,6 +74,7 @@ tcp-close-sending-socket: Closing transmission connection to "{0}" that was \ tcp-close-pool-error: Exception thrown while closing connection pool. tcp-wrong-version-error: Received packet from "{0}" with invalid version \ number. Check if a prior release of OpenJPA is being used on this host. -bean-constructor: Could not instantiate class {0}. +bean-constructor: Could not instantiate class {0}. Make sure it has an \ + accessible no-args constructor. method-notfound: Method "{1}" with arguments of type: {2} \ not found in class "{0}". diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AnnotationPersistenceMetaDataParser.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AnnotationPersistenceMetaDataParser.java index 7e8e85d43..9160923e5 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AnnotationPersistenceMetaDataParser.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/AnnotationPersistenceMetaDataParser.java @@ -84,7 +84,6 @@ import org.apache.openjpa.kernel.jpql.JPQLParser; import org.apache.openjpa.lib.conf.Configurations; import org.apache.openjpa.lib.log.Log; import org.apache.openjpa.lib.util.Localizer; -import org.apache.openjpa.lib.util.Localizer.Message; import org.apache.openjpa.meta.ClassMetaData; import org.apache.openjpa.meta.DelegatingMetaDataFactory; import org.apache.openjpa.meta.FieldMetaData; @@ -580,14 +579,14 @@ public class AnnotationPersistenceMetaDataParser highs[i] = listeners[i].size(); } recordCallbacks(meta, parseCallbackMethods(_cls, listeners, false, - false), highs, false); + false, getRepository()), highs, false); // scan possibly non-PC hierarchy for callbacks. // redundant for PC superclass but we don't know that yet // so let LifecycleMetaData determine that if (!Object.class.equals(_cls.getSuperclass())) { - recordCallbacks(meta, parseCallbackMethods(_cls. - getSuperclass(), null, true, false), null, true); + recordCallbacks(meta, parseCallbackMethods(_cls.getSuperclass(), + null, true, false, getRepository()), null, true); } } @@ -759,7 +758,8 @@ public class AnnotationPersistenceMetaDataParser Class[] classes = listeners.value(); Collection[] parsed = null; for (Class cls : classes) - parsed = parseCallbackMethods(cls, parsed, true, true); + parsed = parseCallbackMethods(cls, parsed, true, true, + getRepository()); return parsed; } @@ -771,9 +771,9 @@ public class AnnotationPersistenceMetaDataParser * @param sups whether to scan superclasses * @param listener whether this is a listener or not */ - public Collection[] parseCallbackMethods + public static Collection[] parseCallbackMethods (Class cls, Collection[] callbacks, boolean sups, - boolean listener) { + boolean listener, MetaDataRepository repos) { // first sort / filter based on inheritance Set methods = new TreeSet(MethodComparator. getInstance()); @@ -796,16 +796,15 @@ public class AnnotationPersistenceMetaDataParser } } sup = sup.getSuperclass(); - } - while (sups && !Object.class.equals(sup)); + } while (sups && !Object.class.equals(sup)); + MetaDataDefaults def = repos.getMetaDataFactory().getDefaults(); for (Method m : methods) { for (Annotation anno : m.getDeclaredAnnotations()) { MetaDataTag tag = _tags.get(anno.annotationType()); if (tag == null) continue; - - int[] events = XMLPersistenceMetaDataParser.getEventTypes(tag); + int[] events = MetaDataParsers.getEventTypes(tag); if (events == null) continue; @@ -813,18 +812,13 @@ public class AnnotationPersistenceMetaDataParser callbacks = (Collection[]) new Collection[LifecycleEvent.ALL_EVENTS.length]; - for (int i = 0; events != null && i < events.length; i++) { + for (int i = 0; i < events.length; i++) { int e = events[i]; - if (!verifyHasNoArgConstructor(cls)) - continue; - if (!verifyMultipleMethodsOnSameEvent(cls, callbacks[e], m, - tag)) - continue; - if (callbacks[e] == null) - callbacks[e] = new ArrayList(3); - + callbacks[e] = new ArrayList(3); if (listener) { + MetaDataParsers.validateMethodsForSameCallback(cls, + callbacks[e], m, tag, def, repos.getLog()); callbacks[e].add(new BeanLifecycleCallbacks(cls, m, false)); } else { @@ -836,58 +830,6 @@ public class AnnotationPersistenceMetaDataParser } return callbacks; } - - private boolean verifyMultipleMethodsOnSameEvent(Class cls, - Collection callbacks, Method method, - MetaDataTag tag) { - boolean result = true; - if (callbacks == null || callbacks.isEmpty()) - return true; - for (LifecycleCallbacks lc: callbacks) { - if (!(lc instanceof MethodLifecycleCallbacks)) - continue; - Method exists = ((MethodLifecycleCallbacks)lc).getCallbackMethod(); - if (exists.getDeclaringClass().equals(method.getDeclaringClass())) { - result = false; - Object[] args = new Object[]{method.getDeclaringClass() - .getName(), method.getName(), exists.getName(), - tag.toString()}; - PersistenceMetaDataDefaults defaults = getDefaults(); - if (defaults == null || - defaults.getAllowsMultipleMethodsOnSameCallback()) { - _log.warn(_loc.get("multiple-methods-on-callback", args)); - } else { - throw new UserException( - _loc.get("multiple-methods-on-callback-error", args)); - } - } - } - return result; - } - - private boolean verifyHasNoArgConstructor(Class cls) { - try { - cls.getConstructor(new Class[]{}); - return true; - } catch (Throwable t) { - PersistenceMetaDataDefaults defaults = getDefaults(); - Message msg = _loc.get("missing-no-arg-constructor", cls.getName()); - if (defaults == null || - defaults.getAllowsMissingCallbackConstructor()) - _log.warn(msg); - else - throw new UserException(msg, t); - } - return false; - } - - private PersistenceMetaDataDefaults getDefaults() { - MetaDataDefaults defaults = getRepository().getMetaDataFactory(). - getDefaults(); - if (defaults instanceof PersistenceMetaDataDefaults) - return (PersistenceMetaDataDefaults)defaults; - return null; - } /** * Store lifecycle metadata. diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/MetaDataParsers.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/MetaDataParsers.java new file mode 100644 index 000000000..3477b6f6e --- /dev/null +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/MetaDataParsers.java @@ -0,0 +1,88 @@ +package org.apache.openjpa.persistence; + +import java.lang.reflect.Method; +import java.util.Collection; + +import org.apache.openjpa.event.LifecycleCallbacks; +import org.apache.openjpa.event.LifecycleEvent; +import org.apache.openjpa.event.MethodLifecycleCallbacks; +import org.apache.openjpa.lib.log.Log; +import org.apache.openjpa.lib.util.Localizer; +import org.apache.openjpa.meta.MetaDataDefaults; +import org.apache.openjpa.util.UserException; + +/** + * Common utilities for persistence metadata parsers. + * + * @author Abe White + */ +class MetaDataParsers { + + private static final Localizer _loc = Localizer.forPackage + (MetaDataParsers.class); + + /** + * Return the event type constants for the given tag, or null if none. + */ + public static int[] getEventTypes(MetaDataTag tag) { + switch (tag) { + case PRE_PERSIST: + return new int[]{ LifecycleEvent.BEFORE_PERSIST }; + case POST_PERSIST: + return new int[]{ LifecycleEvent.AFTER_PERSIST }; + case PRE_REMOVE: + return new int[]{ LifecycleEvent.BEFORE_DELETE }; + case POST_REMOVE: + return new int[]{ LifecycleEvent.AFTER_DELETE }; + case PRE_UPDATE: + return new int[]{ LifecycleEvent.BEFORE_STORE }; + case POST_UPDATE: + return new int[]{ LifecycleEvent.AFTER_STORE }; + case POST_LOAD: + return new int[]{ LifecycleEvent.AFTER_LOAD, + LifecycleEvent.AFTER_REFRESH }; + default: + return null; + } + } + + /** + * Validate that the given listener class does not have multiple methods + * listening for the same lifecycle event, which is forbidden by the spec. + */ + public static void validateMethodsForSameCallback(Class cls, + Collection callbacks, Method method, + MetaDataTag tag, MetaDataDefaults def, Log log) { + if (callbacks == null || callbacks.isEmpty()) + return; + + for (LifecycleCallbacks lc: callbacks) { + if (!(lc instanceof MethodLifecycleCallbacks)) + continue; + Method exists = ((MethodLifecycleCallbacks)lc).getCallbackMethod(); + if (!exists.getDeclaringClass().equals(method.getDeclaringClass())) + continue; + + PersistenceMetaDataDefaults defaults = getPersistenceDefaults(def); + Localizer.Message msg = _loc.get("multiple-methods-on-callback", + new Object[] { method.getDeclaringClass().getName(), + method.getName(), exists.getName(), tag.toString() }); + if (defaults == null + || defaults.getAllowsMultipleMethodsForSameCallback()) + log.warn(msg); + else + throw new UserException(msg); + } + } + + /** + * Return the {@link PersistenceMetaDataDefaults} in use, or null if not + * using JPA defaults. + */ + private static PersistenceMetaDataDefaults getPersistenceDefaults + (MetaDataDefaults def) { + if (def instanceof PersistenceMetaDataDefaults) + return (PersistenceMetaDataDefaults) def; + return null; + } +} diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.java index 7f0ddacb3..f64aefb03 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.java @@ -78,10 +78,10 @@ public interface OpenJPAEntityManagerFactory * settings. OpenJPA recognizes the following configuration settings in this * method: *
    - *
  • org.apache.openjpa.ConnectionUsername
    • - *
  • org.apache.openjpa.ConnectionPassword
    • - *
  • org.apache.openjpa.ConnectionRetainMode
    • - *
  • org.apache.openjpa.TransactionMode
    • + *
  • openjpa.ConnectionUsername
    • + *
  • openjpa.ConnectionPassword
    • + *
  • openjpa.ConnectionRetainMode
    • + *
  • openjpa.TransactionMode
    • *
*/ public OpenJPAEntityManager createEntityManager(Map props); @@ -90,7 +90,8 @@ public interface OpenJPAEntityManagerFactory * Register a listener for lifecycle-related events on the specified * classes. If the classes are null, all events will be propagated to * the listener. The listener will be passed on to all new entity - * managers. See the org.apache.openjpa.event package for listener types. + * managers. See the org.apache.openjpa.event package for + * listener types. * * @since 0.3.3 */ diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataDefaults.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataDefaults.java index 7cec059c4..e9f6a6009 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataDefaults.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataDefaults.java @@ -53,17 +53,15 @@ import static org.apache.openjpa.persistence.PersistenceStrategy.*; import org.apache.openjpa.util.MetaDataException; /** - * Javax persistence-based metadata defaults. + * JPA-based metadata defaults. * * @author Patrick Linskey * @author Abe White - * @nojavadoc */ public class PersistenceMetaDataDefaults extends AbstractMetaDataDefaults { - private boolean _allowsMultipleMethodsOnSameCallback; - private boolean _allowsMissingCallbackConstructor; + private boolean _allowsMultipleMethodsForSameCallback = true; private static Localizer _loc = Localizer.forPackage (PersistenceMetaDataDefaults.class); @@ -97,8 +95,6 @@ public class PersistenceMetaDataDefaults public PersistenceMetaDataDefaults() { setCallbackMode(CALLBACK_RETHROW | CALLBACK_ROLLBACK | CALLBACK_FAIL_FAST); - _allowsMultipleMethodsOnSameCallback = true; - _allowsMissingCallbackConstructor = true; } /** @@ -182,6 +178,35 @@ public class PersistenceMetaDataDefaults return BASIC; return null; } + + /** + * Flags if multiple methods of the same class can handle the same + * callback event. + */ + public boolean getAllowsMultipleMethodsForSameCallback() { + return _allowsMultipleMethodsForSameCallback; + } + + /** + * Flags if multiple methods of the same class can handle the same + * callback event. + */ + public void setAllowsMultipleMethodsForSameCallback(boolean flag) { + _allowsMultipleMethodsForSameCallback = flag; + } + + /** + * Auto-configuration method for the default access type of base classes + * with ACCESS_UNKNOWN + */ + public void setDefaultAccessType(String type) { + if (type == null) + return; + if ("PROPERTY".equals(type.toUpperCase())) + setDefaultAccessType(ClassMetaData.ACCESS_PROPERTY); + else + setDefaultAccessType(ClassMetaData.ACCESS_FIELD); + } @Override public void populate(ClassMetaData meta, int access) { @@ -271,31 +296,4 @@ public class PersistenceMetaDataDefaults return false; return true; } - - /** - * Flags if multiple methods of the same class can handle the same - * callback event. - */ - public boolean getAllowsMultipleMethodsOnSameCallback() { - return _allowsMultipleMethodsOnSameCallback; - } - - public void setAllowsMultipleMethodsOnSameCallback(boolean flag) { - _allowsMultipleMethodsOnSameCallback = flag; - } - - /** - * Flags if it allowed for the callback listener class not to have a no-arg - * constructor. - */ - - public boolean getAllowsMissingCallbackConstructor() { - return _allowsMissingCallbackConstructor; - } - - public void setAllowsMissingCallbackConstructor(boolean flag) { - _allowsMissingCallbackConstructor = flag; - } - - } diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataFactory.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataFactory.java index c2ec4f2e9..eedfbbd02 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataFactory.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceMetaDataFactory.java @@ -35,11 +35,13 @@ import javax.persistence.NamedNativeQuery; import org.apache.openjpa.lib.conf.Configurable; import org.apache.openjpa.lib.conf.Configuration; +import org.apache.openjpa.lib.conf.GenericConfigurable; import org.apache.openjpa.lib.meta.ClassAnnotationMetaDataFilter; import org.apache.openjpa.lib.meta.ClassArgParser; import org.apache.openjpa.lib.meta.MetaDataFilter; import org.apache.openjpa.lib.meta.MetaDataParser; import org.apache.openjpa.lib.util.Localizer; +import org.apache.openjpa.lib.util.Options; import org.apache.openjpa.meta.AbstractCFMetaDataFactory; import org.apache.openjpa.meta.ClassMetaData; import org.apache.openjpa.meta.FieldMetaData; @@ -58,18 +60,18 @@ import org.apache.openjpa.util.MetaDataException; */ public class PersistenceMetaDataFactory extends AbstractCFMetaDataFactory - implements Configurable { + implements Configurable, GenericConfigurable { private static final Localizer _loc = Localizer.forPackage (PersistenceMetaDataFactory.class); + private final PersistenceMetaDataDefaults _def = + new PersistenceMetaDataDefaults(); private AnnotationPersistenceMetaDataParser _annoParser = null; private XMLPersistenceMetaDataParser _xmlParser = null; - private PersistenceMetaDataDefaults _def = null; private Map _xml = null; // xml rsrc -> class names private Set _unparsed = null; // xml rsrc private boolean _fieldOverride = true; - private int _access = ClassMetaData.ACCESS_FIELD; /** * Whether to use field-level override or class-level override. @@ -87,18 +89,6 @@ public class PersistenceMetaDataFactory return _fieldOverride; } - /** - * The default access type for base classes with ACCESS_UNKNOWN - */ - public void setDefaultAccessType(String type) { - if (type == null) - return; - if ("PROPERTY".equals(type.toUpperCase())) - _access = ClassMetaData.ACCESS_PROPERTY; - else - _access = ClassMetaData.ACCESS_FIELD; - } - /** * Return metadata parser, creating it if it does not already exist. */ @@ -333,10 +323,6 @@ public class PersistenceMetaDataFactory } public MetaDataDefaults getDefaults() { - if (_def == null) { - _def = new PersistenceMetaDataDefaults(); - _def.setDefaultAccessType(_access); - } return _def; } @@ -415,4 +401,8 @@ public class PersistenceMetaDataFactory else rsrcs.add ("META-INF/orm.xml"); } + + public void setInto(Options opts) { + opts.keySet().retainAll(opts.setInto(_def).keySet()); + } } diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceProductDerivation.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceProductDerivation.java index a47986ec9..fd4908dea 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceProductDerivation.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/PersistenceProductDerivation.java @@ -113,9 +113,10 @@ public class PersistenceProductDerivation throws IOException { if (pinfo == null) return null; - - if (!isOpenJPAPersistenceProvider(pinfo, null)) + if (!isOpenJPAPersistenceProvider(pinfo, null)) { + warnUnknownProvider(pinfo); return null; + } ConfigurationProviderImpl cp = new ConfigurationProviderImpl(); cp.addProperties(PersistenceUnitInfoImpl.toOpenJPAProperties(pinfo)); @@ -148,8 +149,10 @@ public class PersistenceProductDerivation // persistence.xml does not exist; just load map PersistenceUnitInfoImpl pinfo = new PersistenceUnitInfoImpl(); pinfo.fromUserProperties(m); - if (!isOpenJPAPersistenceProvider(pinfo, null)) + if (!isOpenJPAPersistenceProvider(pinfo, null)) { + warnUnknownProvider(pinfo); return null; + } cp.addProperties(pinfo.toOpenJPAProperties()); return cp; } @@ -248,8 +251,10 @@ public class PersistenceProductDerivation rsrc, String.valueOf(name)).getMessage(), getClass().getName(), rsrc); } else if (!isOpenJPAPersistenceProvider(pinfo, loader)) { - if (!explicit) + if (!explicit) { + warnUnknownProvider(pinfo); return Boolean.FALSE; + } throw new MissingResourceException(_loc.get("unknown-provider", rsrc, name, pinfo.getPersistenceProviderClassName()). getMessage(), getClass().getName(), rsrc); @@ -319,20 +324,30 @@ public class PersistenceProductDerivation try { if (PersistenceProviderImpl.class.isAssignableFrom (Class.forName(provider, false, loader))) { - // log not configured yet - warn(_loc.get("extended-provider", provider).getMessage()); + log(_loc.get("extended-provider", provider).getMessage()); return true; } } catch (Throwable t) { - warn(_loc.get("unloadable-provider", provider, t). - getMessage()); + log(_loc.get("unloadable-provider", provider, t).getMessage()); return false; } - warn(_loc.get("unrecognized-provider", provider).getMessage()); return false; } + + /** + * Warn the user that we could only find an unrecognized persistence + * provider. + */ + private static void warnUnknownProvider(PersistenceUnitInfo pinfo) { + log(_loc.get("unrecognized-provider", + pinfo.getPersistenceProviderClassName()).getMessage()); + } - private static void warn(String msg) { + /** + * Log a message. + */ + private static void log(String msg) { + // at this point logging isn't configured yet System.err.println(msg); } diff --git a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/XMLPersistenceMetaDataParser.java b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/XMLPersistenceMetaDataParser.java index e4bda5684..01ca9be5a 100644 --- a/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/XMLPersistenceMetaDataParser.java +++ b/openjpa-persistence/src/main/java/org/apache/openjpa/persistence/XMLPersistenceMetaDataParser.java @@ -48,6 +48,7 @@ import org.apache.openjpa.meta.DelegatingMetaDataFactory; import org.apache.openjpa.meta.FieldMetaData; import org.apache.openjpa.meta.JavaTypes; import org.apache.openjpa.meta.LifecycleMetaData; +import org.apache.openjpa.meta.MetaDataDefaults; import org.apache.openjpa.meta.MetaDataFactory; import static org.apache.openjpa.meta.MetaDataModes.*; import org.apache.openjpa.meta.MetaDataRepository; @@ -196,8 +197,7 @@ public class XMLPersistenceMetaDataParser * The annotation parser. When class is discovered in an XML file, * we first parse any annotations present, then override with the XML. */ - public void setAnnotationParser( - AnnotationPersistenceMetaDataParser parser) { + public void setAnnotationParser(AnnotationPersistenceMetaDataParser parser){ _parser = parser; } @@ -588,9 +588,10 @@ public class XMLPersistenceMetaDataParser warnUnsupportedTag(name); } } else if (tag instanceof PersistenceStrategy) { - ret = startStrategy((PersistenceStrategy) tag, attrs); + PersistenceStrategy ps = (PersistenceStrategy) tag; + ret = startStrategy(ps, attrs); if (ret) - _strategy = (PersistenceStrategy) tag; + _strategy = ps; } else if (tag == ELEM_LISTENER) ret = startEntityListener(attrs); else if (tag == ELEM_ATTRS) @@ -819,8 +820,7 @@ public class XMLPersistenceMetaDataParser if (log.isInfoEnabled()) log.info(_loc.get("parse-sequence", name)); - SequenceMetaData meta = getRepository().getCachedSequenceMetaData - (name); + SequenceMetaData meta = getRepository().getCachedSequenceMetaData(name); if (meta != null && log.isWarnEnabled()) log.warn(_loc.get("override-sequence", name)); @@ -835,8 +835,7 @@ public class XMLPersistenceMetaDataParser if (seq == null || seq.indexOf('(') == -1) { clsName = SequenceMetaData.IMPL_NATIVE; props = null; - } else // plugin - { + } else { // plugin clsName = Configurations.getClassName(seq); props = Configurations.getProperties(seq); seq = null; @@ -1075,8 +1074,7 @@ public class XMLPersistenceMetaDataParser field = meta.addDeclaredField(name, type); PersistenceMetaDataDefaults.setCascadeNone(field); PersistenceMetaDataDefaults.setCascadeNone(field.getKey()); - PersistenceMetaDataDefaults.setCascadeNone - (field.getElement()); + PersistenceMetaDataDefaults.setCascadeNone(field.getElement()); } field.backingMember(member); } else if (field == null) { @@ -1342,8 +1340,7 @@ public class XMLPersistenceMetaDataParser if (log.isInfoEnabled()) log.info(_loc.get("parse-query", name)); - QueryMetaData meta = getRepository().getCachedQueryMetaData - (null, name); + QueryMetaData meta = getRepository().getCachedQueryMetaData(null, name); if (meta != null && log.isWarnEnabled()) log.warn(_loc.get("override-query", name, currentLocation())); @@ -1398,8 +1395,7 @@ public class XMLPersistenceMetaDataParser if (log.isInfoEnabled()) log.info(_loc.get("parse-native-query", name)); - QueryMetaData meta = getRepository().getCachedQueryMetaData - (null, name); + QueryMetaData meta = getRepository().getCachedQueryMetaData(null, name); if (meta != null && log.isWarnEnabled()) log.warn(_loc.get("override-query", name, currentLocation())); @@ -1486,8 +1482,8 @@ public class XMLPersistenceMetaDataParser _listener = classForName(attrs.getValue("class")); boolean system = currentElement() == null; Collection[] parsed = - new AnnotationPersistenceMetaDataParser(_conf).parseCallbackMethods - (_listener, null, true, true); + AnnotationPersistenceMetaDataParser.parseCallbackMethods(_listener, + null, true, true, _repos); if (parsed == null) return true; @@ -1526,8 +1522,11 @@ public class XMLPersistenceMetaDataParser throws SAXException { if (!isMetaDataMode()) return false; - boolean system = currentElement() == null; + int[] events = MetaDataParsers.getEventTypes(callback); + if (events == null) + return false; + boolean system = currentElement() == null; Class type = currentElement() == null ? null : ((ClassMetaData) currentElement()).getDescribedType(); if (type == null) @@ -1540,6 +1539,7 @@ public class XMLPersistenceMetaDataParser _highs = new int[LifecycleEvent.ALL_EVENTS.length]; } + MetaDataDefaults def = _repos.getMetaDataFactory().getDefaults(); LifecycleCallbacks adapter; if (_listener != null) adapter = new BeanLifecycleCallbacks(_listener, @@ -1548,12 +1548,13 @@ public class XMLPersistenceMetaDataParser adapter = new MethodLifecycleCallbacks(_cls, attrs.getValue("method-name"), false); - int[] events = getEventTypes(callback); - if (events == null) - return true; - for (int i = 0; i < events.length; i++) { int event = events[i]; + if (_listener != null) { + MetaDataParsers.validateMethodsForSameCallback(_listener, + _callbacks[event], ((BeanLifecycleCallbacks) adapter). + getCallbackMethod(), callback, def, getLog()); + } if (_callbacks[event] == null) _callbacks[event] = new ArrayList(3); _callbacks[event].add(adapter); @@ -1563,28 +1564,6 @@ public class XMLPersistenceMetaDataParser return true; } - static int[] getEventTypes(MetaDataTag tag) { - switch (tag) { - case PRE_PERSIST: - return new int[]{ LifecycleEvent.BEFORE_PERSIST }; - case POST_PERSIST: - return new int[]{ LifecycleEvent.AFTER_PERSIST }; - case PRE_REMOVE: - return new int[]{ LifecycleEvent.BEFORE_DELETE }; - case POST_REMOVE: - return new int[]{ LifecycleEvent.AFTER_DELETE }; - case PRE_UPDATE: - return new int[]{ LifecycleEvent.BEFORE_STORE }; - case POST_UPDATE: - return new int[]{ LifecycleEvent.AFTER_STORE }; - case POST_LOAD: - return new int[]{ LifecycleEvent.AFTER_LOAD, - LifecycleEvent.AFTER_REFRESH }; - default: - return null; - } - } - /** * Store lifecycle metadata. */ @@ -1593,8 +1572,8 @@ public class XMLPersistenceMetaDataParser Class supCls = cls.getDescribedType().getSuperclass(); Collection[] supCalls = null; if (!Object.class.equals(supCls)) { - supCalls = new AnnotationPersistenceMetaDataParser(_conf). - parseCallbackMethods(supCls, null, true, false); + supCalls = AnnotationPersistenceMetaDataParser.parseCallbackMethods + (supCls, null, true, false, _repos); } if (supCalls != null) { for (int event : LifecycleEvent.ALL_EVENTS) { @@ -1622,11 +1601,10 @@ public class XMLPersistenceMetaDataParser /** * Instantiate the given class, taking into account the default package. */ - protected Class classForName (String name) - throws SAXException - { - if ("Entity".equals (name)) + protected Class classForName(String name) + throws SAXException { + if ("Entity".equals(name)) return PersistenceCapable.class; - return super.classForName (name, isRuntime ()); + return super.classForName(name, isRuntime()); } } diff --git a/openjpa-persistence/src/main/resources/org/apache/openjpa/persistence/localizer.properties b/openjpa-persistence/src/main/resources/org/apache/openjpa/persistence/localizer.properties index 7d7355b22..51e4e3828 100644 --- a/openjpa-persistence/src/main/resources/org/apache/openjpa/persistence/localizer.properties +++ b/openjpa-persistence/src/main/resources/org/apache/openjpa/persistence/localizer.properties @@ -60,7 +60,7 @@ missing-xml-config: The specified XML resource "{0}" for persistence unit \ "{1}" can''t be found in your class path. cantload-xml-config: The specified XML resource "{0}" for persistence unit \ "{1}" can''t be parsed. -unknown-provider: Persistence Provider "{2}" specified in persistence unit \ +unknown-provider: Persistence provider "{2}" specified in persistence unit \ "{1}" in "{0}" is not a recognized provider. illegal-index: The parameter index {0} is invalid. Parameters must be \ integers starting at 1. @@ -86,19 +86,11 @@ system-listener-err: An error occurred invoking system entity listener \ no-transaction: Cannot perform operation with no transaction. multiple-methods-on-callback: Class "{0}" declares method "{1}" as well \ as "{2}" for handling the same "{3}" callback. -multiple-methods-on-callback-error: Class "{0}" declares method "{1}" as well \ - as "{2}" for handling the same "{3}" callback. \ - "AllowsMultipleMethodsOnSameCallback" property of MetaDataDefaults can be \ - set to true to supress this exception. -missing-no-arg-constructor: Entity listener class "{0}" must declare a no-arg \ - constructor. "AllowsNoArgConstructorCallback" property of MetaDataDefaults \ - can be set to true to ignore this exception. -extended-provider: WARNING: Configured to use extended Persistence Provider \ - "{0}". -unloadable-provider: WARNING: Can not load configured Persistence Provider \ - "{0}" due to "{1}" -unrecognized-provider: WARNING: Configured to use non-recognized Persistence \ - Provider "{0}" +extended-provider: NOTE: Found extended persistence provider "{0}". +unloadable-provider: WARNING: Unable to load persistence provider "{0}" due \ + to "{1}" +unrecognized-provider: WARNING: Found unrecognized persistence provider "{0}" \ + in place of OpenJPA provider. This provider's properties will not be used. EntityManagerFactory-name: EntityManagerFactory implementation EntityManagerFactory-desc: Allows extension of standard \ org.apache.openjpa.persistence.EntityManagerFactoryImpl for custom behavior. diff --git a/openjpa-project/src/doc/manual/jpa_overview_arch.xml b/openjpa-project/src/doc/manual/jpa_overview_arch.xml index 4bd8d95d3..c2154f0e8 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_arch.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_arch.xml @@ -105,11 +105,11 @@ datastore records. EntityTransaction: Each EntityManager has a one-to-one relation with a single -javax.persistence.EntityTransaction. EntityTransaction -s allow operations on persistent data to be grouped into units of -work that either completely succeed or completely fail, leaving the datastore in -its original state. These all-or-nothing operations are important for -maintaining data integrity. +javax.persistence.EntityTransaction. +EntityTransactions allow operations on persistent data to be +grouped into units of work that either completely succeed or completely fail, +leaving the datastore in its original state. These all-or-nothing operations +are important for maintaining data integrity. @@ -178,38 +178,37 @@ container. // get an EntityManagerFactory using the Persistence class; typically // the factory is cached for easy repeated use -EntityManagerFactory factory = Persistence.createEntityManagerFactory (null); +EntityManagerFactory factory = Persistence.createEntityManagerFactory(null); // get an EntityManager from the factory -EntityManager em = factory.createEntityManager (PersistenceContextType.EXTENDED); +EntityManager em = factory.createEntityManager(PersistenceContextType.EXTENDED); // updates take place within transactions -EntityTransaction tx = em.getTransaction (); -tx.begin (); +EntityTransaction tx = em.getTransaction(); +tx.begin(); // query for all employees who work in our research division // and put in over 40 hours a week average -Query query = em.createQuery ("select e from Employee e where " +Query query = em.createQuery("select e from Employee e where " + "e.division.name = 'Research' AND e.avgHours > 40"); List results = query.getResultList (); // give all those hard-working employees a raise -for (Object res : results) -{ +for (Object res : results) { Employee emp = (Employee) res; - emp.setSalary (emp.getSalary () * 1.1); + emp.setSalary(emp.getSalary() * 1.1); } // commit the updates and free resources -tx.commit (); -em.close (); -factory.close (); +tx.commit(); +em.close(); +factory.close(); Within a container, the EntityManager will be injected -and transactional handled declaratively. Thus, the in-container version of the -example consists entirely of business logic: +and transactions will be handled declaratively. Thus, the in-container version +of the example consists entirely of business logic: @@ -219,15 +218,14 @@ example consists entirely of business logic: // query for all employees who work in our research division // and put in over 40 hours a week average - note that the EntityManager em // is injected using a @Resource annotation -Query query = em.createQuery ("select e from Employee e where " +Query query = em.createQuery("select e from Employee e where " + "e.division.name = 'Research' and e.avgHours > 40"); -List results = query.getResultList (); +List results = query.getResultList(); // give all those hard-working employees a raise -for (Object res : results) -{ +for (Object res : results) { emp = (Employee) res; - emp.setSalary (emp.getSalary () * 1.1); + emp.setSalary(emp.getSalary() * 1.1); } </programlisting> </example> @@ -274,8 +272,8 @@ application. <para> The diagram above depicts the JPA exception architecture. All exceptions are unchecked. JPA uses standard exceptions where -appropriate, most notably <classname> IllegalArgumentException</classname>s and -<classname> IllegalStateException</classname> s. The specification also provides +appropriate, most notably <classname>IllegalArgumentException</classname>s and +<classname>IllegalStateException</classname>s. The specification also provides a few JPA-specific exceptions in the <literal>javax.persistence</literal> package. These exceptions should be self-explanatory. See the <ulink url="http://java.sun.com/javaee/5/docs/api">Javadoc</ulink> for diff --git a/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml b/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml index 37e0945c1..33df684db 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_conclusion.xml @@ -3,10 +3,14 @@ Conclusion -This concludes our overview of the JPA specification. The -OpenJPA Tutorials continue your +This concludes our overview of the JPA specification. + +The OpenJPA Reference Guide contains detailed documentation on all aspects of the OpenJPA implementation and core development tools. diff --git a/openjpa-project/src/doc/manual/jpa_overview_em.xml b/openjpa-project/src/doc/manual/jpa_overview_em.xml index 67810e7ae..53aaf625f 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_em.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_em.xml @@ -18,14 +18,15 @@ The diagram above presents an overview of the EntityManager interface. For a complete treatment of the EntityManager API, see the - Javadoc -documentation. Methods whose parameter signatures consist of an ellipsis (...) -are overloaded to take multiple parameter types. + +Javadoc documentation. Methods whose parameter signatures consist of +an ellipsis (...) are overloaded to take multiple parameter types. OpenJPA extends the standard EntityManager interface with -the +the + org.apache.openjpa.persistence.OpenJPAEntityManager interface to provide additional functionality. @@ -100,7 +101,7 @@ Every EntityManager has a one-to-one relation with an instance. In fact, many vendors use a single class to implement both the EntityManager and EntityTransaction interfaces. If your application requires multiple concurrent -transactions, you will use multiple EntityManager s. +transactions, you will use multiple EntityManagers. You can retrieve the EntityTransaction associated with an @@ -129,7 +130,7 @@ demarcation or through the Java Transaction API (JTA) rather than through the lifecycle state of entity instances. -public void persist (Object entity); +public void persist(Object entity); @@ -198,7 +199,7 @@ whose cascades include This action can only be used in the context of an active transaction. -public void remove (Object entity); +public void remove(Object entity); @@ -268,7 +269,7 @@ whose cascades include This action can only be used in the context of an active transaction. -public void refresh (Object entity); +public void refresh(Object entity); @@ -345,7 +346,7 @@ whose cascades include -public Object merge (Object entity); +public Object merge(Object entity); @@ -562,27 +563,27 @@ well as all transaction demarcation code. // create some objects -Magazine mag = new Magazine ("1B78-YU9L", "JavaWorld"); +Magazine mag = new Magazine("1B78-YU9L", "JavaWorld"); -Company pub = new Company ("Weston House"); -pub.setRevenue (1750000D); -mag.setPublisher (pub); -pub.addMagazine (mag); +Company pub = new Company("Weston House"); +pub.setRevenue(1750000D); +mag.setPublisher(pub); +pub.addMagazine(mag); -Article art = new Article ("JPA Rules!", "Transparent Object Persistence"); -art.addAuthor (new Author ("Fred", "Hoyle")); -mag.addArticle (art); +Article art = new Article("JPA Rules!", "Transparent Object Persistence"); +art.addAuthor(new Author("Fred", "Hoyle")); +mag.addArticle(art); // persist -EntityManager em = emf.createEntityManager (); -em.getTransaction ().begin (); -em.persist (mag); -em.persist (pub); -em.persist (art); -em.getTransaction ().commit (); +EntityManager em = emf.createEntityManager(); +em.getTransaction().begin(); +em.persist(mag); +em.persist(pub); +em.persist(art); +em.getTransaction().commit(); // or we could continue using the EntityManager... -em.close (); +em.close(); @@ -601,23 +602,23 @@ em.close (); -Magazine.MagazineId mi = new Magazine.MagazineId (); +Magazine.MagazineId mi = new Magazine.MagazineId(); mi.isbn = "1B78-YU9L"; mi.title = "JavaWorld"; // updates should always be made within transactions; note that // there is no code explicitly linking the magazine or company // with the transaction; JPA automatically tracks all changes -EntityManager em = emf.createEntityManager (); -em.getTransaction ().begin (); -Magazine mag = em.find (Magazine.class, mi); -mag.setPrice (5.99); -Company pub = mag.getPublisher (); -pub.setRevenue (1750000D); -em.getTransaction ().commit (); +EntityManager em = emf.createEntityManager(); +em.getTransaction().begin(); +Magazine mag = em.find(Magazine.class, mi); +mag.setPrice(5.99); +Company pub = mag.getPublisher(); +pub.setRevenue(1750000D); +em.getTransaction().commit(); // or we could continue using the EntityManager... -em.close (); +em.close(); @@ -641,16 +642,16 @@ em.close (); Object oid = ...; // deletes should always be made within transactions -EntityManager em = emf.createEntityManager (); -em.getTransaction ().begin (); -Company pub = (Company) em.find (Company.class, oid); -for (Subscription sub : pub.getSubscriptions ()) - em.remove (sub); -pub.getSubscriptions ().clear (); -em.getTransaction ().commit (); +EntityManager em = emf.createEntityManager(); +em.getTransaction().begin(); +Company pub = (Company) em.find(Company.class, oid); +for (Subscription sub : pub.getSubscriptions()) + em.remove(sub); +pub.getSubscriptions().clear(); +em.getTransaction().commit(); // or we could continue using the EntityManager... -em.close (); +em.close(); @@ -665,37 +666,37 @@ and transactions. // CLIENT: // requests an object with a given oid -Record detached = (Record) getFromServer (oid); +Record detached = (Record) getFromServer(oid); ... // SERVER: // send object to client; object detaches on EM close -Object oid = processClientRequest (); -EntityManager em = emf.createEntityManager (); -Record record = em.find (Record.class, oid); -em.close (); -sendToClient (record); +Object oid = processClientRequest(); +EntityManager em = emf.createEntityManager(); +Record record = em.find(Record.class, oid); +em.close(); +sendToClient(record); ... // CLIENT: // makes some modifications and sends back to server -detached.setSomeField ("bar"); -sendToServer (detached); +detached.setSomeField("bar"); +sendToServer(detached); ... // SERVER: // merges the instance and commit the changes -Record modified = (Record) processClientRequest (); -EntityManager em = emf.createEntityManager (); -em.getTransaction ().begin (); -Record merged = (Record) em.merge (modified); -merged.setLastModified (System.currentTimeMillis ()); -merged.setModifier (getClientIdentityCode ()); -em.getTransaction ().commit (); -em.close (); +Record modified = (Record) processClientRequest(); +EntityManager em = emf.createEntityManager(); +em.getTransaction().begin(); +Record merged = (Record) em.merge(modified); +merged.setLastModified(System.currentTimeMillis()); +merged.setModifier(getClientIdentityCode()); +em.getTransaction().commit(); +em.close(); @@ -713,7 +714,7 @@ context type of the EntityManager; see persistence contexts. -public <T> T find (Class<T> cls, Object oid); +public <T> T find(Class<T> cls, Object oid); @@ -751,7 +752,7 @@ entity with the given type and identity exists in the datastore, this method returns null. -public <T> T getReference (Class<T> cls, Object oid); +public <T> T getReference(Class<T> cls, Object oid); @@ -794,11 +795,11 @@ gets loaded when you attempt to access a persistent field. At that time, the implementation may throw an EntityNotFoundException if it discovers that the entity does not exist in the datastore. The implementation may also throw an EntityNotFoundException from the -getReference method itself. Unlike find -, getReference does not return null. +getReference method itself. Unlike +find, getReference does not return null. -public boolean contains (Object entity); +public boolean contains(Object entity); @@ -835,7 +836,7 @@ persistence context. -public void flush (); +public void flush(); @@ -875,8 +876,8 @@ progress, the flush method throws a TransactionRequiredException. -public FlushModeType getFlushMode (); -public void setFlushMode (FlushModeType flushMode); +public FlushModeType getFlushMode(); +public void setFlushMode(FlushModeType flushMode); @@ -928,7 +929,7 @@ control over flushing behavior. See the Reference Guide's -public void clear (); +public void clear(); @@ -976,7 +977,7 @@ persistence context. All entities managed by the EntityManager -public Query createQuery (String query); +public Query createQuery(String query); Query objects are used to find entities matching certain @@ -985,7 +986,7 @@ the given Java Persistence Query Language (JPQL) string. See for details. -public Query createNamedQuery (String name); +public Query createNamedQuery(String name); This method retrieves a query defined in metadata by name. The returned @@ -994,9 +995,9 @@ declared in metadata. For more information on named queries, read . -public Query createNativeQuery (String sql); -public Query createNativeQuery (String sql, Class resultCls); -public Query createNativeQuery (String sql, String resultMapping); +public Query createNativeQuery(String sql); +public Query createNativeQuery(String sql, Class resultCls); +public Query createNativeQuery(String sql, String resultMapping); Native queries are queries in the datastore's native @@ -1018,8 +1019,8 @@ native query support. -public boolean isOpen (); -public void close (); +public boolean isOpen(); +public void close(); When an EntityManager is no longer needed, you should diff --git a/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml b/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml index c4134a0ae..b8e54df1b 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_emfactory.xml @@ -22,7 +22,7 @@ EntityManager instances for application use. OpenJPA extends the standard EntityManagerFactory interface with the - + OpenJPAEntityManagerFactory to provide additional functionality. @@ -73,9 +73,9 @@ vendors to pool factories, cutting down on resource utilization. JNDI -JPA allows you to create and configure an EntityManagerFactory -, then store it in a Java Naming and Directory Interface (JNDI) -tree for later retrieval and use. +JPA allows you to create and configure an +EntityManagerFactory, then store it in a Java Naming and Directory +Interface (JNDI) tree for later retrieval and use.
@@ -102,8 +102,8 @@ tree for later retrieval and use. -public EntityManager createEntityManager (); -public EntityManager createEntityManager (Map map); +public EntityManager createEntityManager(); +public EntityManager createEntityManager(Map map); The two createEntityManager methods above create a new @@ -144,8 +144,8 @@ createEntityManager: openjpa.<property>, where <property> is any JavaBean property of the - org.apache.openjpa.persistence.OpenJPAEntityManager -. + +org.apache.openjpa.persistence.OpenJPAEntityManager. @@ -217,7 +217,7 @@ merging detached entities. Injected EntityManagers have use a transaction , while EntityManagers obtained through the -EntityManagerFactory have an extended +EntityManagerFactory have an extended persistence context. We describe these persistence context types below. @@ -276,9 +276,9 @@ EntityManager em; // injected // each operation occurs in a separate persistence context, and returns // a new detached instance -Magazine mag1 = em.find (Magazine.class, magId); -Magazine mag2 = em.find (Magazine.class, magId); -assertTrue (mag2 != mag1); +Magazine mag1 = em.find(Magazine.class, magId); +Magazine mag2 = em.find(Magazine.class, magId); +assertTrue(mag2 != mag1); ... // transaction begins: @@ -287,17 +287,17 @@ assertTrue (mag2 != mag1); // detached objects. however, two lookups within the same transaction // return the same instance, because the persistence context spans the // transaction -Magazine mag3 = em.find (Magazine.class, magId); -assertTrue (mag3 != mag1 && mag3 != mag2); -Magazine mag4 = em.find (Magazine.class (magId); -assertTrue (mag4 == mag3); +Magazine mag3 = em.find(Magazine.class, magId); +assertTrue(mag3 != mag1 && mag3 != mag2); +Magazine mag4 = em.find(Magazine.class (magId); +assertTrue(mag4 == mag3); ... // transaction commits: // once again, each operation returns a new instance -Magazine mag5 = em.find (Magazine.class, magId); -assertTrue (mag5 != mag3); +Magazine mag5 = em.find(Magazine.class, magId); +assertTrue(mag5 != mag3);
@@ -324,30 +324,30 @@ EntityManager using an extended persistence context. EntityManagerFactory emf = ... -EntityManager em = emf.createEntityManager (PersistenceContextType.EXTENDED); +EntityManager em = emf.createEntityManager(); // persistence context active for entire life of EM, so only one entity // for a given persistent identity -Magazine mag1 = em.find (Magazine.class, magId); -Magazine mag2 = em.find (Magazine.class, magId); -assertTrue (mag2 == mag1); +Magazine mag1 = em.find(Magazine.class, magId); +Magazine mag2 = em.find(Magazine.class, magId); +assertTrue(mag2 == mag1); -em.getTransaction ().begin (); +em.getTransaction().begin(); // same persistence context active within the transaction -Magazine mag3 = em.find (Magazine.class, magId); -assertTrue (mag3 == mag1); -Magazine mag4 = em.find (Magazine.class (magId); -assertTrue (mag4 == mag1); +Magazine mag3 = em.find(Magazine.class, magId); +assertTrue(mag3 == mag1); +Magazine mag4 = em.find(Magazine.class (magId); +assertTrue(mag4 == mag1); em.getTransaction.commit (); // when the transaction commits, instance still managed -Magazine mag5 = em.find (Magazine.class, magId); -assertTrue (mag5 == mag1); +Magazine mag5 = em.find(Magazine.class, magId); +assertTrue(mag5 == mag1); // instance finally becomes detached when EM closes -em.close (); +em.close(); @@ -389,8 +389,8 @@ close the factory, or only close it when the application is exiting. Only applications that require multiple factories with different configurations have an obvious reason to create and close multiple EntityManagerFactory instances. Once a factory is closed, all methods except -isOpen throw an IllegalStateException -. +isOpen throw an +IllegalStateException. diff --git a/openjpa-project/src/doc/manual/jpa_overview_mapping.xml b/openjpa-project/src/doc/manual/jpa_overview_mapping.xml index 86cec09f8..7ba370908 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_mapping.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_mapping.xml @@ -192,20 +192,17 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) @Table(name="MAG") -public class Magazine -{ +public class Magazine { ... - public static class MagazineId - { + public static class MagazineId { ... } } @Entity @Table(name="ART") -public class Article -{ +public class Article { ... } @@ -214,21 +211,18 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { ... } @Entity @Table(name="AUTH") -public class Author -{ +public class Author { ... } @Embeddable -public class Address -{ +public class Address { ... } @@ -236,45 +230,39 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { ... } @Entity @Table(schema="CNTRCT") public class Contract - extends Document -{ + extends Document { ... } @Entity @Table(name="SUB", schema="CNTRCT") -public class Subscription -{ +public class Subscription { ... @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { ... } } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -396,8 +384,7 @@ column of the ART table: @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) -public class Article -{ +public class Article { ... } @@ -721,24 +708,23 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) @Table(name="MAG") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; ... - public static class MagazineId - { + public static class MagazineId { ... } } @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) -public class Article -{ +public class Article { + @Id private long id; ... @@ -749,8 +735,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -759,8 +745,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Column(name="AID", columnDefinition="INTEGER64") @Id private long id; @@ -768,8 +754,7 @@ public class Author } @Embeddable -public class Address -{ +public class Address { ... } @@ -777,8 +762,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -789,15 +774,14 @@ public abstract class Document @Entity @Table(schema="CNTRCT") public class Contract - extends Document -{ + extends Document { ... } @Entity @Table(name="SUB", schema="CNTRCT") -public class Subscription -{ +public class Subscription { + @Id private long id; ... @@ -805,23 +789,20 @@ public class Subscription @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { ... } } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -1253,16 +1234,15 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) @Table(name="MAG") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; ... - public static class MagazineId - { + public static class MagazineId { ... } } @@ -1270,8 +1250,8 @@ public class Magazine @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") -public class Article -{ +public class Article { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") private long id; @@ -1284,8 +1264,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -1294,8 +1274,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", @@ -1307,8 +1287,7 @@ public class Author } @Embeddable -public class Address -{ +public class Address { ... } @@ -1316,8 +1295,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(generate=GenerationType.IDENTITY) private long id; @@ -1328,15 +1307,15 @@ public abstract class Document @Entity @Table(schema="CNTRCT") public class Contract - extends Document -{ + extends Document { + ... } @Entity @Table(name="SUB", schema="CNTRCT") -public class Subscription -{ +public class Subscription { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -1346,23 +1325,20 @@ public class Subscription @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { ... } } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -1545,15 +1521,13 @@ as well. @Entity @Table(name="SUB", schema="CNTRCT") @Inheritance(strategy=InheritanceType.SINGLE_TABLE) -public class Subscription -{ +public class Subscription { ... } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @@ -1774,21 +1748,18 @@ we include the primary key join column for illustrative purposes. @Table(schema="CNTRCT") @Inheritance(strategy=InheritanceType.JOINED) public class Contract - extends Document -{ + extends Document { ... } -public class Subscription -{ +public class Subscription { ... @Entity @Table(name="LINE_ITEM", schema="CNTRCT") @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") public static class LineItem - extends Contract - { + extends Contract { ... } } @@ -1823,8 +1794,7 @@ array of PrimaryKeyJoinColumn s. We could rewrite @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") }) public static class LineItem - extends Contract -{ + extends Contract { ... } @@ -1977,16 +1947,14 @@ s to override superclass field mappings. @Entity @Table(name="MAG") @Inheritance(strategy=InheritanceType.TABLE_PER_CLASS) -public class Magazine -{ +public class Magazine { ... } @Entity @Table(name="TABLOID") public class Tabloid - extends Magazine -{ + extends Magazine { ... } @@ -2088,16 +2056,15 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) @Table(name="MAG") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; ... - public static class MagazineId - { + public static class MagazineId { ... } } @@ -2105,8 +2072,8 @@ public class Magazine @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") -public class Article -{ +public class Article { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") private long id; @@ -2119,8 +2086,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -2129,8 +2096,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", @@ -2142,8 +2109,7 @@ public class Author } @Embeddable -public class Address -{ +public class Address { ... } @@ -2151,8 +2117,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -2164,16 +2130,15 @@ public abstract class Document @Table(schema="CNTRCT") @Inheritance(strategy=InheritanceType.JOINED) public class Contract - extends Document -{ + extends Document { ... } @Entity @Table(name="SUB", schema="CNTRCT") @Inheritance(strategy=InheritanceType.SINGLE_TABLE) -public class Subscription -{ +public class Subscription { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -2184,23 +2149,20 @@ public class Subscription @Table(name="LINE_ITEM", schema="CNTRCT") @PrimaryKeyJoinColumn(name="ID", referencedColumnName="ID") public static class LineItem - extends Contract - { + extends Contract { ... } } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -2485,16 +2447,15 @@ package org.mag; @IdClass(Magazine.MagazineId.class) @Table(name="MAG") @DiscriminatorValue("Mag") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; ... - public static class MagazineId - { + public static class MagazineId { ... } } @@ -2502,8 +2463,8 @@ public class Magazine @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") -public class Article -{ +public class Article { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") private long id; @@ -2516,8 +2477,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -2526,8 +2487,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", @@ -2539,8 +2500,7 @@ public class Author } @Embeddable -public class Address -{ +public class Address { ... } @@ -2548,8 +2508,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -2562,8 +2522,7 @@ public abstract class Document @Inheritance(strategy=InheritanceType.JOINED) @DiscriminatorColumn(name="CTYPE") public class Contract - extends Document -{ + extends Document { ... } @@ -2571,8 +2530,8 @@ public class Contract @Table(name="SUB", schema="CNTRCT") @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) @DiscriminatorValue("1") -public class Subscription -{ +public class Subscription { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -2582,8 +2541,7 @@ public class Subscription @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { ... } } @@ -2591,16 +2549,14 @@ public class Subscription @Entity(name="Lifetime") @DiscriminatorValue("2") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") @DiscriminatorValue("3") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -2983,8 +2939,8 @@ package org.mag; @IdClass(Magazine.MagazineId.class) @Table(name="MAG") @DiscriminatorValue("Mag") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; @@ -3000,8 +2956,7 @@ public class Magazine ... - public static class MagazineId - { + public static class MagazineId { ... } } @@ -3009,8 +2964,8 @@ public class Magazine @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") -public class Article -{ +public class Article { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") private long id; @@ -3029,8 +2984,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -3047,8 +3002,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") @TableGenerator(name="AuthorGen", table="AUTH_GEN", pkColumnName="PK", @@ -3069,16 +3024,15 @@ public class Author } @Embeddable -public class Address -{ +public class Address { ... } package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -3094,8 +3048,8 @@ public abstract class Document @Inheritance(strategy=InheritanceType.JOINED) @DiscriminatorColumn(name="CTYPE") public class Contract - extends Document -{ + extends Document { + @Lob private String terms; @@ -3106,8 +3060,8 @@ public class Contract @Table(name="SUB", schema="CNTRCT") @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) @DiscriminatorValue("1") -public class Subscription -{ +public class Subscription { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -3126,8 +3080,8 @@ public class Subscription @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { + @Column(name="COMM") private String comments; @@ -3140,8 +3094,8 @@ public class Subscription @Entity(name="Lifetime") @DiscriminatorValue("2") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { + @Basic(fetch=FetchType.LAZY) @Column(name="ELITE") private boolean getEliteClub () { ... } @@ -3153,8 +3107,8 @@ public class LifetimeSubscription @Entity(name="Trial") @DiscriminatorValue("3") public class TrialSubscription - extends Subscription -{ + extends Subscription { + @Column(name="END") public Date getEndDate () { ... } public void setEndDate (Date end) { ... } @@ -3405,8 +3359,8 @@ package org.mag; @Table(name="ART") @SecondaryTable(name="ART_DATA", pkJoinColumns=@PrimaryKeyJoinColumn(name="ART_ID", referencedColumnName="ID")) -public class Article -{ +public class Article { + @Id private long id; @Column(table="ART_DATA") @@ -3550,8 +3504,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Embedded @AttributeOverrides({ @AttributeOverride(name="street", column=@Column(name="STRT")), @@ -3564,8 +3518,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + // use all defaults from Address class mappings private Address address; @@ -3573,8 +3527,8 @@ public class Author } @Embeddable -public class Address -{ +public class Address { + private String street; private String city; @Column(columnDefinition="CHAR(2)") @@ -3632,8 +3586,8 @@ Contract table's CVERSION column. @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Column(name="VERS") @Version private int version; @@ -3646,8 +3600,7 @@ public abstract class Document @DiscriminatorColumn(name="CTYPE") @AttributeOverride(name="version", column=@Column(name="CVERSION")) public class Contract - extends Document -{ + extends Document { ... } @@ -3840,8 +3793,8 @@ Guide for details. package org.mag; @Table(name="AUTH") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; @@ -3858,8 +3811,8 @@ public class Magazine } @Table(name="ART") -public class Article -{ +public class Article { + @Id private long id; ... @@ -3869,8 +3822,8 @@ public class Article package org.mag.pub; @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -3880,14 +3833,13 @@ public class Company package org.mag.subscribe; -public class Subscription -{ +public class Subscription { ... @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { + @ManyToOne @JoinColumns({ @JoinColumn(name="MAG_ISBN" referencedColumnName="ISBN"), @@ -4092,8 +4044,8 @@ package org.mag; @Entity @Table(name="MAG") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; @@ -4113,8 +4065,8 @@ public class Magazine @Entity @Table(name="ART") -public class Article -{ +public class Article { + @Id private long id; @ManyToMany(cascade=CascadeType.PERSIST) @@ -4132,8 +4084,8 @@ package org.mag.pub; @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Column(name="AID", columnDefinition="INTEGER64") @Id private long id; @@ -4273,26 +4225,26 @@ package org.mag.subscribe; @Entity @Table(name="SUB", schema="CNTRCT") -public class Subscription -{ -@OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) -@MapKey(name="num") -@JoinTable(name="SUB_ITEMS", schema="CNTRCT", - joinColumns=@JoinColumn(name="SUB_ID"), - inverseJoinColumns=@JoinColumn(name="ITEM_ID")) -private Map<Long,LineItem> items; +public class Subscription { -... - -@Entity -@Table(name="LINE_ITEM", schema="CNTRCT") -public static class LineItem - extends Contract -{ - private long num; + @OneToMany(cascade={CascadeType.PERSIST,CascadeType.REMOVE}) + @MapKey(name="num") + @JoinTable(name="SUB_ITEMS", schema="CNTRCT", + joinColumns=@JoinColumn(name="SUB_ID"), + inverseJoinColumns=@JoinColumn(name="ITEM_ID")) + private Map<Long,LineItem> items; ... -} + + @Entity + @Table(name="LINE_ITEM", schema="CNTRCT") + public static class LineItem + extends Contract { + + private long num; + + ... + } } @@ -4370,8 +4322,8 @@ package org.mag; @IdClass(Magazine.MagazineId.class) @Table(name="MAG") @DiscriminatorValue("Mag") -public class Magazine -{ +public class Magazine { + @Column(length=9) @Id private String isbn; @Id private String title; @@ -4409,8 +4361,7 @@ public class Magazine ... - public static class MagazineId - { + public static class MagazineId { ... } } @@ -4418,8 +4369,8 @@ public class Magazine @Entity @Table(name="ART", uniqueConstraints=@Unique(columnNames="TITLE")) @SequenceGenerator(name="ArticleSeq", sequenceName="ART_SEQ") -public class Article -{ +public class Article { + @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="ArticleSeq") private long id; @@ -4445,8 +4396,8 @@ package org.mag.pub; @Entity @Table(name="COMP") -public class Company -{ +public class Company { + @Column(name="CID") @Id private long id; @@ -4479,8 +4430,8 @@ public class Company @Entity @Table(name="AUTH") -public class Author -{ +public class Author { + @Id @GeneratedValue(strategy=GenerationType.TABLE, generator="AuthorGen") @TableGenerator(name="AuthorGen", tableName="AUTH_GEN", pkColumnName="PK", @@ -4506,8 +4457,8 @@ public class Author } @Embeddable -public class Address -{ +public class Address { + private String street; private String city; @Column(columnDefinition="CHAR(2)") @@ -4519,8 +4470,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -4536,8 +4487,8 @@ public abstract class Document @Inheritance(strategy=InheritanceType.JOINED) @DiscriminatorColumn(name="CTYPE") public class Contract - extends Document -{ + extends Document { + @Lob private String terms; @@ -4548,8 +4499,8 @@ public class Contract @Table(name="SUB", schema="CNTRCT") @DiscriminatorColumn(name="KIND", discriminatorType=DiscriminatorType.INTEGER) @DiscriminatorValue("1") -public class Subscription -{ +public class Subscription { + @Id @GeneratedValue(strategy=GenerationType.IDENTITY) private long id; @@ -4575,8 +4526,8 @@ public class Subscription @Entity @Table(name="LINE_ITEM", schema="CNTRCT") public static class LineItem - extends Contract - { + extends Contract { + @Column(name="COMM") private String comments; @@ -4596,8 +4547,8 @@ public class Subscription @Entity(name="Lifetime") @DiscriminatorValue("2") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { + @Basic(fetch=FetchType.LAZY) @Column(name="ELITE") private boolean getEliteClub () { ... } @@ -4609,8 +4560,8 @@ public class LifetimeSubscription @Entity(name="Trial") @DiscriminatorValue("3") public class TrialSubscription - extends Subscription -{ + extends Subscription { + @Column(name="END") public Date getEndDate () { ... } public void setEndDate (Date end) { ... } diff --git a/openjpa-project/src/doc/manual/jpa_overview_meta.xml b/openjpa-project/src/doc/manual/jpa_overview_meta.xml index 7e369e314..57e85da12 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_meta.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_meta.xml @@ -56,9 +56,9 @@ strategies: -In a resource named orm.xml placed in the -META-INF directory of the classpath or the jar archive containing -your persistent classes. +In a resource named orm.xml placed in a +META-INF directory within a directory in your classpath or within a +jar archive containing your persistent classes. @@ -221,7 +221,7 @@ attribute: -class: This required attribute lists the class name for the +class: Set this required attribute to the name of the identity class. @@ -413,19 +413,16 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) -public class Magazine -{ +public class Magazine { ... - public static class MagazineId - { + public static class MagazineId { ... } } @Entity -public class Article -{ +public class Article { ... } @@ -433,20 +430,17 @@ public class Article package org.mag.pub; @Entity -public class Company -{ +public class Company { ... } @Entity -public class Author -{ +public class Author { ... } @Embeddable -public class Address -{ +public class Address { ... } @@ -454,42 +448,36 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { ... } @Entity public class Contract - extends Document -{ + extends Document { ... } @Entity -public class Subscription -{ +public class Subscription { ... @Entity public static class LineItem - extends Contract - { + extends Contract { ... } } @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ + extends Subscription { ... } @@ -587,19 +575,19 @@ Property access, on the other hand, retrieves and loads state through JavaBean T, you must define the following getter method: -T getP (); +T getP(); For boolean properties, this is also acceptable: -boolean isP (); +boolean isP(); You must also define the following setter method: -void setP (T value); +void setP(T value); To use property access, set your entity element's @@ -608,9 +596,9 @@ metadata and mapping annotations on the getter method: @ManyToOne -private Company getPublisher () { ... } +private Company getPublisher() { ... } -private void setPublisher (Company publisher) { ... } +private void setPublisher(Company publisher) { ... } @@ -662,7 +650,7 @@ either a persistent field or a persistent property. The Transient annotation specifies that a field is non-persistent. Use it to exclude fields from management that would otherwise be -persistent. Transient is a marker annotation only; it +persistent. Transient is a marker annotation only; it has no properties. @@ -873,8 +861,8 @@ represents the UUID as a 32-character hexadecimal string. These string constants are defined in - -org.apache.openjpa.persistence.Generator. + +org.apache.openjpa.persistence.Generator. @@ -998,13 +986,13 @@ attribute is required. Basic signifies a standard value persisted as-is to the datastore. You can use the Basic annotation on persistent fields of the following types: primitives, primitive wrappers, -java.lang.String, byte[], Byte[] -, char[], Character[] -, java.math.BigDecimal, java.math.BigInteger -, java.util.Date, -java.util.Calendar, java.sql.Date, -java.sql.Timestamp, Enum s, and -Serializable types. +java.lang.String, byte[], +Byte[], char[], +Character[], java.math.BigDecimal, +java.math.BigInteger, +java.util.Date, java.util.Calendar, +java.sql.Date, java.sql.Timestamp, +Enums, and Serializable types. Basic declares these properties: @@ -1012,9 +1000,9 @@ java.util.Calendar, java.sql.Date, -FetchType fetch: Whether to load the field eagerly ( -FetchType.EAGER) or lazily ( FetchType.LAZY - ). Defaults to FetchType.EAGER. +FetchType fetch: Whether to load the field eagerly +(FetchType.EAGER) or lazily ( +FetchType.LAZY). Defaults to FetchType.EAGER. @@ -1187,8 +1175,8 @@ required. -When an entity A references a single entity B -, and other As might also reference the same +When an entity A references a single entity +B, and other As might also reference the same B, we say there is a many to one relation from A to B. In our sample model, for example, each magazine has a reference to its publisher. Multiple @@ -1214,18 +1202,18 @@ behavior for this field. We explore cascades below. Defaults to an empty array. -FetchType fetch: Whether to load the field eagerly ( -FetchType.EAGER) or lazily ( FetchType.LAZY - ). Defaults to FetchType.EAGER. See - above for details on fetch -types. +FetchType fetch: Whether to load the field eagerly +(FetchType.EAGER) or lazily +(FetchType.LAZY). Defaults to +FetchType.EAGER. See above +for details on fetch types. boolean optional: Whether the related object must exist. If -false, this field cannot be null. Defaults to true -. +false, this field cannot be null. Defaults to +true. @@ -1247,8 +1235,8 @@ required. -fetch: One of EAGER or LAZY -. +fetch: One of EAGER or +LAZY. @@ -1279,7 +1267,7 @@ null. We introduce the JPA EntityManager in . The EntityManager has APIs to persist new entities, remove (delete) existing -entities, refresh entity state from the datastore, and merge detached +entities, refresh entity state from the datastore, and merge detached entity state back into the persistence context. We explore all of these APIs in detail later in the overview. @@ -1386,8 +1374,8 @@ equivalent: When an entity A references multiple B -entities, and no two As reference the same B -, we say there is a one to many relation from +entities, and no two As reference the same +B, we say there is a one to many relation from A to B. @@ -1428,11 +1416,11 @@ behavior for the collection elements. We explore cascades above in -FetchType fetch: Whether to load the field eagerly ( -FetchType.EAGER) or lazily ( FetchType.LAZY - ). Defaults to FetchType.LAZY. See - above for details on fetch -types. +FetchType fetch: Whether to load the field eagerly +(FetchType.EAGER) or lazily +(FetchType.LAZY). Defaults to +FetchType.LAZY. See above +for details on fetch types. @@ -1454,8 +1442,8 @@ required. -fetch: One of EAGER or LAZY -. +fetch: One of EAGER or +LAZY. @@ -1578,8 +1566,8 @@ Reference Guide for details. -When an entity A references a single entity B -, and no other As can reference the same +When an entity A references a single entity +B, and no other As can reference the same B, we say there is a one to one relation between A and B. In our sample model, Magazine has a one to one relation to Article @@ -1615,18 +1603,18 @@ array. -FetchType fetch: Whether to load the field eagerly ( -FetchType.EAGER) or lazily ( FetchType.LAZY - ). Defaults to FetchType.EAGER. See - above for details on fetch -types. +FetchType fetch: Whether to load the field eagerly +(FetchType.EAGER) or lazily +(FetchType.LAZY). Defaults to +FetchType.EAGER. See above +for details on fetch types. boolean optional: Whether the related object must exist. If -false, this field cannot be null. Defaults to true -. +false, this field cannot be null. Defaults to +true. @@ -1648,8 +1636,8 @@ required. -fetch: One of EAGER or LAZY -. +fetch: One of EAGER or +LAZY. @@ -1692,7 +1680,7 @@ one-to-one element. When an entity A references multiple B entities, and other As might reference some of the same -B s, we say there is a many to many +Bs, we say there is a many to many relation between A and B. In our sample model, for example, each article has a reference to all the authors that contributed to the article. Other articles might have some of the same authors. @@ -1730,11 +1718,11 @@ behavior for the collection elements. We explore cascades above in -FetchType fetch: Whether to load the field eagerly ( -FetchType.EAGER) or lazily ( FetchType.LAZY - ). Defaults to FetchType.LAZY. See - above for details on fetch -types. +FetchType fetch: Whether to load the field eagerly +(FetchType.EAGER) or lazily +(FetchType.LAZY). Defaults to +FetchType.LAZY. See above +for details on fetch types. @@ -1756,8 +1744,8 @@ required. -fetch: One of EAGER or LAZY -. +fetch: One of EAGER or +LAZY. @@ -1905,21 +1893,21 @@ Fields declared static, transient, or final Fields of any primitive type, primitive wrapper type, -java.lang.String, byte[], Byte[] -, char[], Character[] -, java.math.BigDecimal, java.math.BigInteger -, java.util.Date, -java.util.Calendar, java.sql.Date, -java.sql.Timestamp, or any Serializable - type default to persistent, as if annotated with -@Basic. +java.lang.String, byte[], +Byte[], char[], +Character[], java.math.BigDecimal, +java.math.BigInteger, +java.util.Date, java.util.Calendar, +java.sql.Date, java.sql.Timestamp, +or any Serializable type default to persistent, as if +annotated with +@Basic. Fields of an embeddable type default to persistent, as if annotated with - @Embedded -. +@Embedded. @@ -3500,8 +3488,8 @@ package org.mag; @Entity @IdClass(Magazine.MagazineId.class) -public class Magazine -{ +public class Magazine { + @Id private String isbn; @Id private String title; @Version private int version; @@ -3524,15 +3512,14 @@ public class Magazine ... - public static class MagazineId - { + public static class MagazineId { ... } } @Entity -public class Article -{ +public class Article { + @Id private long id; @Version private int version; @@ -3550,8 +3537,8 @@ public class Article package org.mag.pub; @Entity -public class Company -{ +public class Company { + @Id private long id; @Version private int version; @@ -3569,8 +3556,8 @@ public class Company } @Entity -public class Author -{ +public class Author { + @Id private long id; @Version private int version; @@ -3585,8 +3572,8 @@ public class Author } @Embeddable -public class Address -{ +public class Address { + private String street; // defaults to @Basic private String city; // defaults to @Basic private String state; // defaults to @Basic @@ -3599,8 +3586,8 @@ public class Address package org.mag.subscribe; @MappedSuperclass -public abstract class Document -{ +public abstract class Document { + @Id private long id; @Version private int version; @@ -3609,16 +3596,16 @@ public abstract class Document @Entity public class Contract - extends Document -{ + extends Document { + private String terms; // defaults to @Basic ... } @Entity -public class Subscription -{ +public class Subscription { + @Id private long id; @Version private int version; @@ -3633,8 +3620,8 @@ public class Subscription @Entity public static class LineItem - extends Contract - { + extends Contract { + private String comments; // defaults to @Basic private double price; // defaults to @Basic private long num; // defaults to @Basic @@ -3648,21 +3635,21 @@ public class Subscription @Entity(name="Lifetime") public class LifetimeSubscription - extends Subscription -{ + extends Subscription { + @Basic(fetch=FetchType.LAZY) - private boolean getEliteClub () { ... } - public void setEliteClub (boolean elite) { ... } + private boolean getEliteClub() { ... } + public void setEliteClub(boolean elite) { ... } ... } @Entity(name="Trial") public class TrialSubscription - extends Subscription -{ - public Date getEndDate () { ... } - public void setEndDate (Date end) { ... } + extends Subscription { + + public Date getEndDate() { ... } + public void setEndDate(Date end) { ... } ... } diff --git a/openjpa-project/src/doc/manual/jpa_overview_pc.xml b/openjpa-project/src/doc/manual/jpa_overview_pc.xml index 21d56ff59..2a3e2d762 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_pc.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_pc.xml @@ -35,7 +35,7 @@ -JPA recognizes two types of persistent classes: entity +JPA recognizes two types of persistent classes: entity classes and embeddable classes. Each persistent instance of an entity class - each entity - represents a unique datastore record. You can use the EntityManager to find @@ -49,9 +49,9 @@ never returned directly from the EntityManager or from a Query. -Despite these differences, there are few differences between entity classes and -embeddable classes. In fact, writing either type of persistent class is little -different than writing any other class. There are no special parent classes to +Despite these differences, there are few distinctions between entity classes and +embeddable classes. In fact, writing either type of persistent class is a lot +like writing any other class. There are no special parent classes to extend from, field types to use, or methods to write. This is one important way in which JPA makes persistence transparent to you, the developer. @@ -73,43 +73,38 @@ package org.mag; * Example persistent class. Notice that it looks exactly like any other * class. JPA makes writing persistent classes completely transparent. */ -public class Magazine -{ - private String isbn; - private String title; - private Set articles = new HashSet (); - private Article coverArticle; - private int copiesSold; - private double price; - private Company publisher; - private int version; +public class Magazine { - protected Magazine () - { + private String isbn; + private String title; + private Set articles = new HashSet(); + private Article coverArticle; + private int copiesSold; + private double price; + private Company publisher; + private int version; + + protected Magazine() { } - public Magazine (String title, String isbn) - { + public Magazine(String title, String isbn) { this.title = title; this.isbn = isbn; } - public void publish (Company publisher, double price) - { + public void publish(Company publisher, double price) { this.publisher = publisher; - publisher.addMagazine (this); + publisher.addMagazine(this); this.price = price; } - public void sell () - { + public void sell() { copiesSold++; - publisher.addRevenue (price); + publisher.addRevenue(price); } - public void addArticle (Article article) - { - articles.add (article); + public void addArticle(Article article) { + articles.add(article); } // rest of methods omitted @@ -210,7 +205,7 @@ are identity fields, because no two magazine records in the datastore can have the same isbn and title values. will show you how to denote your identity fields in JPA metadata. - below examines persistent identity. +below examines persistent identity. @@ -241,24 +236,24 @@ OpenJPA fully supports identity fields, but does not require them. See The version field in our Magazine -class may seem out of place. JPA uses a version field in your entity to detect +class may seem out of place. JPA uses a version field in your entities to detect concurrent modifications to the same datastore record. When the JPA runtime detects an attempt to concurrently modify the same record, it throws an exception to the transaction attempting to commit last. This prevents overwriting the previous commit with stale data. -The version field is not required, but without one concurrent threads or +A version field is not required, but without one concurrent threads or processes might succeed in making conflicting changes to the same record at the same time. This is unacceptable to most applications. shows you how to designate a version field in JPA metadata. -The version field must be an integral type ( int, -Long, etc) or a java.sql.Timestamp -. You should consider version fields immutable. Changing the field value has -undefined results. +The version field must be an integral type ( int, +Long, etc) or a +java.sql.Timestamp. You should consider version fields immutable. +Changing the field value has undefined results. @@ -391,12 +386,12 @@ the field. JPA supports the following immutable types: -All primitives ( int, float, byte, etc) +All primitives (int, float, byte, etc) -All primitive wrappers ( java.lang.Integer, java.lang.Float, +All primitive wrappers (java.lang.Integer, java.lang.Float, java.lang.Byte, etc) @@ -527,7 +522,7 @@ Embeddable types java.util.Maps in which each entry maps the value of one -of an entity's fields to that entity. +of a related entity's fields to that entity. @@ -560,10 +555,9 @@ information on persisting serializable types. -OpenJPA also supports arrays, java.lang.Number, - java.util.Locale, all JDK 1.2 Set -, List, and Map -types, collections and maps of immutable and embedded as well as entity types, +OpenJPA also supports arrays, java.lang.Number, +java.util.Locale, all JDK 1.2 Set, +List, and Map types, and many other mutable and immutable field types. OpenJPA also allows you to plug in support for custom types. @@ -688,10 +682,10 @@ in the datastore. Each entity's identity field values must be unique among all other entites of the same type. -Identity fields must be primitives, primitive wrappers, String - s, Date s, Timestamp -s, or embeddable types. Notably, other entities instances can not - be used as identity fields. +Identity fields must be primitives, primitive wrappers, +Strings, Dates, +Timestamps, or embeddable types. Notably, other entities instances +can not be used as identity fields. @@ -726,7 +720,7 @@ as immutable objects in your applications. If you are dealing with a single persistence context (see - ), then you do not +), then you do not have to compare identity fields to test whether two entity references represent the same state in the datastore. There is a much easier way: the == operator. JPA requires that each persistence context maintain only @@ -811,7 +805,7 @@ If the class is an inner class, it must be static. All entity classes related by inheritance must use the same identity class, or else each entity class must have its own identity class whose inheritance hierarchy mirrors the inheritance hierarchy of the owning entity classes (see - ). +). @@ -835,8 +829,8 @@ identity fields. /** * Persistent class using application identity. */ -public class Magazine -{ +public class Magazine { + private String isbn; // identity field private String title; // identity field @@ -846,8 +840,8 @@ public class Magazine /** * Application identity class for Magazine. */ - public static class MagazineId - { + public static class MagazineId { + // each identity field in the Magazine class must have a // corresponding field in the identity class public String isbn; @@ -859,8 +853,7 @@ public class Magazine * classes directly (some JPA implementations may subclass the * identity class). */ - public boolean equals (Object other) - { + public boolean equals(Object other) { if (other == this) return true; if (!(other instanceof MagazineId)) @@ -868,22 +861,20 @@ public class Magazine MagazineId mi = (MagazineId) other; return (isbn == mi.isbn - || (isbn != null && isbn.equals (mi.isbn))) + || (isbn != null && isbn.equals(mi.isbn))) && (title == mi.title - || (title != null && title.equals (mi.title))); + || (title != null && title.equals(mi.title))); } /** * Hashcode must also depend on identity values. */ - public int hashCode () - { - return ((isbn == null) ? 0 : isbn.hashCode ()) - ^ ((title == null) ? 0 : title.hashCode ()); + public int hashCode() { + return ((isbn == null) ? 0 : isbn.hashCode()) + ^ ((title == null) ? 0 : title.hashCode()); } - public String toString () - { + public String toString() { return isbn + ":" + title; } } @@ -954,7 +945,7 @@ more identity fields. All subclasses of a concrete identity class must be equals - and hashCode -compatible with the + and hashCode-compatible with the concrete superclass. This means that in our example, a ManagerId instance and a FullTimeEmployeeId instance with the same identity field values should have the same hash code, and should @@ -1106,8 +1097,8 @@ datastructure. PreUpdate: Methods marked with this annotation will be invoked just the persistent values in your objects are flushed to the -datastore. This is equivalent to the XML element tag pre-update -. +datastore. This is equivalent to the XML element tag +pre-update. PreUpdate is the complement to PostLoad @@ -1131,8 +1122,7 @@ persistent fields with information cached in non-persistent data. PostUpdate: Methods marked with this annotation will be invoked after changes to a given instance have been stored to the datastore. This is useful for clearing stale data cached at the application -layer. This is equivalent to the XML element tag post-update -. +layer. This is equivalent to the XML element tag post-update. @@ -1150,8 +1140,8 @@ layer. This is equivalent to the XML element tag post-update will be invoked before an object transactions to the deleted state. Access to persistent fields is valid within this method. You might use this method to cascade the deletion to related objects based on complex criteria, or to perform -other cleanup. This is equivalent to the XML element tag pre-remove -. +other cleanup. This is equivalent to the XML element tag +pre-remove. @@ -1189,8 +1179,8 @@ Below is an example of how to declare callback methods on persistent classes: * Example persistent class declaring our entity listener. */ @Entity -public class Magazine -{ +public class Magazine { + @Transient private byte[][] data; @@ -1198,17 +1188,15 @@ public class Magazine private List<Photo> photos; @PostLoad - public void convertPhotos () - { - data = new byte[photos.size ()][]; - for (int i = 0; i < photos.size (); i++) - data[i] = photos.get (i).toByteArray (); + public void convertPhotos() { + data = new byte[photos.size()][]; + for (int i = 0; i < photos.size(); i++) + data[i] = photos.get(i).toByteArray(); } @PreDelete - public void logMagazineDeletion () - { - getLog ().debug ("deleting magazine containing" + photos.size () + public void logMagazineDeletion() { + getLog().debug("deleting magazine containing" + photos.size() + " photos."); } } @@ -1258,8 +1246,8 @@ classes. */ @Entity @EntityListeners({ MagazineLogger.class, ... }) -public class Magazine -{ +public class Magazine { + // ... // } @@ -1267,20 +1255,18 @@ public class Magazine /** * Example entity listener. */ -public class MagazineLogger -{ +public class MagazineLogger { + @PostPersist - public void logAddition (Object pc) - { + public void logAddition(Object pc) { getLog ().debug ("Added new magazine:" + ((Magazine) pc).getTitle ()); } @PreRemove - public void logDeletion (Object pc) - { - getLog ().debug ("Removing from circulation:" + - ((Magazine) pc).getTitle ()); + public void logDeletion(Object pc) { + getLog().debug("Removing from circulation:" + + ((Magazine) pc).getTitle()); } } diff --git a/openjpa-project/src/doc/manual/jpa_overview_persistence.xml b/openjpa-project/src/doc/manual/jpa_overview_persistence.xml index a3e92a8c4..910c85553 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_persistence.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_persistence.xml @@ -35,15 +35,14 @@ - OpenJPA also includes the - -OpenJPAPersistence helper class to provide additional -utility methods. + +OpenJPAPersistence helper class to provide +additional utility methods. @@ -55,8 +54,8 @@ of a container, however, can use the EntityManagerFactory objects in a vendor-neutral fashion. -public static EntityManagerFactory createEntityManagerFactory (String name); -public static EntityManagerFactory createEntityManagerFactory (String name, Map props); +public static EntityManagerFactory createEntityManagerFactory(String name); +public static EntityManagerFactory createEntityManagerFactory(String name, Map props); Each createEntityManagerFactory method searches the @@ -67,8 +66,8 @@ factory. persistence.xml files define -EntityManagerFactories. The createEntityManagerFactory - methods search for persistence.xml files +EntityManagerFactories. The createEntityManagerFactory + methods search for persistence.xml files within the META-INF directory of any CLASSPATH element. For example, if your CLASSPATH contains the conf directory, you could place an @@ -120,9 +119,9 @@ name attribute is required. -transaction-type: Whether to use managed ( JTA -) or local ( RESOURCE_LOCAL) transaction -management. Defaults to JTA. +transaction-type: Whether to use managed +(JTA) or local (RESOURCE_LOCAL) +transaction management. @@ -144,7 +143,7 @@ OpenJPA. jta-data-source: The JNDI name of a JDBC DataSource that is automatically enlisted in JTA transactions. This -may be an XA DataSource. +may be an XA DataSource. @@ -155,22 +154,22 @@ DataSource that is not enlisted in JTA transactions. -mapping-file *: The resource names of XML mapping files for +mapping-file*: The resource names of XML mapping files for entities and embeddable classes. You can also specify mapping information in an - orm.xml file in your META-INF +orm.xml file in your META-INF directory. If present, the orm.xml mapping file will be read automatically. -jar-file *: The names of jar files containing entities and +jar-file*: The names of jar files containing entities and embeddable classes. The implementation will scan the jar for annotated classes. -class *: The class names of entities and embeddable classes. +class*: The class names of entities and embeddable classes. @@ -234,11 +233,11 @@ EntityManagerFactories are typically injected. // if your persistence.xml file does not contain all settings already, you // can add vendor settings to a map -Properties props = new Properties (); +Properties props = new Properties(); ... // create the factory defined by the "openjpa" entity-manager entry -EntityManagerFactory emf = Persistence.createEntityManagerFactory ("openjpa", props); +EntityManagerFactory emf = Persistence.createEntityManagerFactory("openjpa", props); diff --git a/openjpa-project/src/doc/manual/jpa_overview_query.xml b/openjpa-project/src/doc/manual/jpa_overview_query.xml index 236dd2a33..894995ce4 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_query.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_query.xml @@ -51,7 +51,7 @@ The preceding is a simple JPQL query for all Magazine entities. -public Query createQuery (String jpql); +public Query createQuery(String jpql); The @@ -60,7 +60,7 @@ The Query instance from a given JPQL string. -public List getResultList (); +public List getResultList(); Invoking @@ -71,8 +71,8 @@ following example executes our Magazine query above: EntityManager em = ... -Query q = em.createQuery ("SELECT x FROM Magazine x"); -List<Magazine> results = q.getResultList (); +Query q = em.createQuery("SELECT x FROM Magazine x"); +List<Magazine> results = (List<Magazine>) q.getResultList(); A JPQL query has an internal namespace declared in the from @@ -105,20 +105,17 @@ OBJECT(x) are synonymous. The optional where clause places criteria on matching results. For example: -SELECT x FROM Magazine x WHERE x.title = 'JDJ' - +SELECT x FROM Magazine x WHERE x.title = 'JDJ' Keywords in JPQL expressions are case-insensitive, but entity, identifier, and member names are not. For example, the expression above could also be expressed as: -SELECT x FROM Magazine x WHERE x.title = 'JDJ' - +SELECT x FROM Magazine x WHERE x.title = 'JDJ' But it could not be expressed as: -SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ' - +SELECT x FROM Magazine x WHERE x.TITLE = 'JDJ' As with the select clause, alias names in the where clause are resolved to the entity declared in the from @@ -568,8 +565,7 @@ example, the following query may return instances of Magazine instances, where Tabloid and Digest are Magazine subclasses. -SELECT x FROM Magazine x WHERE x.price < 5 - +SELECT x FROM Magazine x WHERE x.price < 5
@@ -594,9 +590,9 @@ instance for optional method chaining. </para> <programlisting> EntityManager em = ... -Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = ?1 and x.price > ?2"); -q.setParameter (1, "JDJ").setParameter (2, 5.0); -List<Magazine> results = q.getResultList (); +Query q = em.createQuery("SELECT x FROM Magazine x WHERE x.title = ?1 and x.price > ?2"); +q.setParameter(1, "JDJ").setParameter(2, 5.0); +List<Magazine> results = (List<Magazine>) q.getResultList(); </programlisting> <para> This code will substitute <literal>JDJ</literal> for the <literal>?1</literal> @@ -604,7 +600,7 @@ parameter and <literal>5.0</literal> for the <literal>?2</literal> parameter, then execute the query with those values. </para> <programlisting> -public Query setParameter (String name, Object value); +public Query setParameter(String name, Object value); </programlisting> <para> Named parameter are denoted by prefixing an arbitrary name with a colon in your @@ -615,9 +611,9 @@ method chaining. </para> <programlisting> EntityManager em = ... -Query q = em.createQuery ("SELECT x FROM Magazine x WHERE x.title = :titleParam and x.price > :priceParam"); -q.setParameter ("titleParam", "JDJ").setParameter ("priceParam", 5.0); -List<Magazine> results = q.getResultList (); +Query q = em.createQuery("SELECT x FROM Magazine x WHERE x.title = :titleParam and x.price > :priceParam"); +q.setParameter("titleParam", "JDJ").setParameter("priceParam", 5.0); +List<Magazine> results = (List<Magazine>) q.getResultList(); </programlisting> <para> This code substitutes <literal>JDJ</literal> for the <literal> :titleParam @@ -663,8 +659,8 @@ magazines: </para> <programlisting> EntityManager em = ... -Query q = em.createQuery ("SELECT AVG(x.price) FROM Magazine x"); -Number result = (Number) q.getSingleResult (); +Query q = em.createQuery("SELECT AVG(x.price) FROM Magazine x"); +Number result = (Number) q.getSingleResult(); </programlisting> <para> The following query will return the highest price of all the magazines titled @@ -672,8 +668,8 @@ The following query will return the highest price of all the magazines titled </para> <programlisting> EntityManager em = ... -Query q = em.createQuery ("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'"); -Number result = (Number) q.getSingleResult (); +Query q = em.createQuery("SELECT MAX(x.price) FROM Magazine x WHERE x.title = 'JDJ'"); +Number result = (Number) q.getSingleResult(); </programlisting> </section> <section id="jpa_overview_query_named"> @@ -692,8 +688,7 @@ Query templates can be statically declared using the <literal> NamedQuery @NamedQuery(name="magsByTitle", query="SELECT x FROM Magazine x WHERE x.title = :titleParam") }) -public class Magazine -{ +public class Magazine { ... } </programlisting> @@ -702,7 +697,7 @@ These declarations will define two named queries called <literal>magsOverPrice </literal> and <literal>magsByTitle</literal>. </para> <programlisting> -public Query createNamedQuery (String name); +public Query createNamedQuery(String name); </programlisting> <para> You retrieve named queries with the above <classname>EntityManager</classname> @@ -710,15 +705,15 @@ method. For example: </para> <programlisting> EntityManager em = ... -Query q = em.createNamedQuery ("magsOverPrice"); -q.setParameter (1, 5.0f); -List<Magazine> results = q.getResultList (); +Query q = em.createNamedQuery("magsOverPrice"); +q.setParameter(1, 5.0f); +List<Magazine> results = q.getResultList(); </programlisting> <programlisting> EntityManager em = ... -Query q = em.createNamedQuery ("magsByTitle"); -q.setParameter ("titleParam", "JDJ"); -List<Magazine> results = q.getResultList (); +Query q = em.createNamedQuery("magsByTitle"); +q.setParameter("titleParam", "JDJ"); +List<Magazine> results = q.getResultList(); </programlisting> </section> <section id="jpa_overview_query_delete"> @@ -738,7 +733,7 @@ the <literal>select</literal> keyword. To then execute the delete, you call the following <classname>Query</classname> method: </para> <programlisting> -public int executeUpdate (); +public int executeUpdate(); </programlisting> <para> This method returns the number of objects deleted. The following example deletes @@ -749,9 +744,9 @@ all subscriptions whose expiration date has passed. Delete by Query -Query q = em.createQuery ("DELETE s FROM Subscription s WHERE s.subscriptionDate < :today"); -q.setParameter ("today", new Date ()); -int deleted = q.executeUpdate (); +Query q = em.createQuery("DELETE s FROM Subscription s WHERE s.subscriptionDate < :today"); +q.setParameter("today", new Date()); +int deleted = q.executeUpdate();
@@ -773,7 +768,7 @@ query string begins with the update keyword instead of Query method: -public int executeUpdate (); +public int executeUpdate(); This method returns the number of objects updated. The following example updates @@ -785,10 +780,10 @@ to true.. Update by Query -Query q = em.createQuery ("UPDATE Subscription s SET s.paid = :paid WHERE s.subscriptionDate < :today"); -q.setParameter ("today", new Date ()); -q.setParameter ("paid", true); -int updated = q.executeUpdate (); +Query q = em.createQuery("UPDATE Subscription s SET s.paid = :paid WHERE s.subscriptionDate < :today"); +q.setParameter("today", new Date()); +q.setParameter("paid", true); +int updated = q.executeUpdate(); @@ -806,11 +801,14 @@ query language, EJB QL, adding operations such as bulk deletes and updates, join operations, aggregates, projections, and subqueries. Furthermore, JPQL queries can be declared statically in metadata, or can be dynamically built in code. This chapter provides the full definition of the -language. Much of this section is paraphrased or taken directly -from Chapter 4 of the JSR 220 specification. - - +language. + + +Much of this section is paraphrased or taken directly from Chapter 4 of the +JSR 220 specification. + +
JPQL Statement Types @@ -820,28 +818,20 @@ A JPQL statement may be either a <literal>SELECT</literal> statement, an <literal>UPDATE</literal> statement, or a <literal>DELETE</literal> statement. This chapter refers to all such statements as "queries". Where it is important to distinguish among statement types, the specific statement type is referenced. -In BNF syntax, a query language statement is defined as: <itemizedlist> -<listitem><para>QL_statement ::= select_statement | update_statement | -delete_statement - </para> - </listitem> - </itemizedlist> - - - The complete BNF for JPQL is defined in - <xref linkend="jpa_langref_bnf"/> - - . - - Any JPQL statement may be constructed - dynamically or may be statically defined in a metadata annotation or - XML descriptor element. All statement types may have parameters, as - discussed in - <xref linkend="jpa_langref_input_params"/> - - . - - +In BNF syntax, a query language statement is defined as: + </para> + <itemizedlist> + <listitem> + <para> +QL_statement ::= select_statement | update_statement | delete_statement + </para> + </listitem> + </itemizedlist> + <para> +The complete BNF for JPQL is defined in <xref linkend="jpa_langref_bnf"/>. +Any JPQL statement may be constructed dynamically or may be statically defined +in a metadata annotation or XML descriptor element. All statement types may +have parameters, as discussed in <xref linkend="jpa_langref_input_params"/>. </para> <section id="jpa_langref_select"> <title> @@ -849,71 +839,61 @@ delete_statement A select statement is a string which consists of the following clauses: - a SELECT clause, which -determines the type of the objects or values to be selected. - - - - + + + + +a SELECT clause, which determines the type of the objects +or values to be selected. + + + + a FROM clause, which provides declarations that designate the domain to which the expressions specified in the other clauses of the query apply. - - - - + + + + an optional WHERE clause, which may be used to restrict the results that are returned by the query. - - - - + + + + an optional GROUP BY clause, which allows query results to be aggregated in terms of groups. - - - - + + + + an optional HAVING clause, which allows filtering over aggregated groups. - - - - + + + + an optional ORDER BY clause, which may be used to order the results that are returned by the query. - - - - - - In BNF syntax, a select statement is defined as: - - - - + + + + +In BNF syntax, a select statement is defined as: + + + + select_statement ::= select_clause from_clause [where_clause] [groupby_clause] [having_clause] [orderby_clause] - - - - - - - A select statement - must always have a - - SELECT - - - and a - - FROM - - clause. The square brackets [] - indicate that the other clauses are optional. - - + + + + +A select statement must always have a SELECT and a +FROM clause. The square brackets [] indicate that the other +clauses are optional.
@@ -922,32 +902,25 @@ select_statement ::= select_clause from_clause [where_clause] [groupby_clause] Update and delete statements provide bulk operations over sets of entities. In -BNF syntax, these operations are defined as: +BNF syntax, these operations are defined as: + + + + update_statement ::= update_clause [where_clause] - - - - + + + + delete_statement ::= delete_clause [where_clause] - - - - - - The update and delete clauses determine - the type of the entities to be updated or deleted. - The - - WHERE - - clause may - be used to restrict the scope of the update or delete operation. Update - and delete statements are described further in - - - - . - + + + + +The update and delete clauses determine the type of the entities to be updated +or deleted. The WHERE clause may be used to restrict the +scope of the update or delete operation. Update and delete statements are +described further in .
@@ -966,14 +939,19 @@ language annotations or in the XML descriptor. Informally, the abstract schema type of an entity can be characterized as -follows: For every persistent field or get +follows: + + + + +For every persistent field or get accessor method (for a persistent property) of the entity class, there is a field ("state-field") whose abstract schema type corresponds to that of the field or the result type of the accessor method. - - - - + + + + For every persistent relationship field or get accessor method (for a persistent relationship property) of the entity class, there is a field ("association-field") whose type is the abstract schema type of the related @@ -987,10 +965,9 @@ entity on which it is based. The association-fields of an entity's abstract schema type determine navigability. Using the association-fields and their values, a query can select related entities and use their abstract schema types in the query. - - - - + + +
JPQL Entity Naming @@ -1025,27 +1002,35 @@ in a one-to-one relationship. Queries to select magazines can be defined by navigating over the association-fields and state-fields defined by Magazine and Author. A query to find all magazines that have unpublished articles is as follows: -<programlisting>SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE -</programlisting> This query navigates over the association-field authors of the + </para> +<programlisting> +SELECT DISTINCT mag FROM Magazine AS mag JOIN mag.articles AS art WHERE art.published = FALSE +</programlisting> + <para> +This query navigates over the association-field authors of the abstract schema type <literal>Magazine</literal> to find articles, and uses the state-field <literal>published</literal> of <literal>Article</literal> to select those magazines that have at least one article that is published. Although predefined reserved identifiers, such as <literal>DISTINCT</literal>, <literal> -FROM</literal>, <literal>AS</literal>, <literal>JOIN</literal>, <literal>WHERE -</literal>, and <literal>FALSE</literal> appear in upper case in this example, -predefined reserved identifiers are case insensitive. The <literal>SELECT -</literal> clause of this example designates the return type of this query to be -of type Magazine. Because the same persistence unit defines the abstract -persistence schemas of the related entities, the developer can also specify a -query over <literal>articles</literal> that utilizes the abstract schema type -for products, and hence the state-fields and association-fields of both the -abstract schema types Magazine and Author. For example, if the abstract schema -type Author has a state-field named firstName, a query over articles can be -specified using this state-field. Such a query might be to find all magazines -that have articles authored by someone with the first name "John". -<programlisting>SELECT DISTINCT mag FROM Magazine mag - JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John' -</programlisting> Because Magazine is related to Author by means of the +FROM</literal>, <literal>AS</literal>, <literal>JOIN</literal>, <literal> +WHERE</literal>, and <literal>FALSE</literal> appear in upper case in this +example, predefined reserved identifiers are case insensitive. The <literal> +SELECT</literal> clause of this example designates the return type of this +query to be of type Magazine. Because the same persistence unit defines the +abstract persistence schemas of the related entities, the developer can also +specify a query over <literal>articles</literal> that utilizes the abstract +schema type for products, and hence the state-fields and association-fields of +both the abstract schema types Magazine and Author. For example, if the +abstract schema type Author has a state-field named firstName, a query over +articles can be specified using this state-field. Such a query might be to +find all magazines that have articles authored by someone with the first name +"John". + </para> +<programlisting> +SELECT DISTINCT mag FROM Magazine mag JOIN mag.articles art JOIN art.author auth WHERE auth.firstName = 'John' +</programlisting> + <para> +Because Magazine is related to Author by means of the relationships between Magazine and Article and between Article and Author, navigation using the association-fields authors and product is used to express the query. This query is specified by using the abstract schema name Magazine, @@ -1068,41 +1053,42 @@ instances of a particular entity abstract schema type. The <literal>FROM </literal> clause can contain multiple identification variable declarations separated by a comma (,). </para> - <para> -<itemizedlist><listitem><para>from_clause ::= FROM -identification_variable_declaration {, {identification_variable_declaration | -collection_member_declaration}}* - </para> - </listitem> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> +from_clause ::= FROM identification_variable_declaration {, +{identification_variable_declaration | collection_member_declaration}}* + </para> + </listitem> + <listitem> + <para> identification_variable_declaration ::= range_variable_declaration { join | fetch_join }* - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> range_variable_declaration ::= abstract_schema_name [AS] identification_variable - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> join ::= join_spec join_association_path_expression [AS] identification_variable - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> fetch_join ::= join_spec FETCH join_association_path_expression - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> join_association_path_expression ::= join_collection_valued_path_expression | join_single_valued_association_path_expression - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> join_spec ::= [ LEFT [OUTER] | INNER ] JOIN </para> </listitem> @@ -1110,10 +1096,9 @@ join_spec ::= [ LEFT [OUTER] | INNER ] JOIN <para> collection_member_declaration ::= IN (collection_valued_path_expression) [AS] identification_variable - </para> - </listitem> - </itemizedlist> - </para> + </para> + </listitem> + </itemizedlist> <section id="jpa_langref_from_identifiers"> <title> JPQL FROM Identifiers @@ -1128,157 +1113,161 @@ This includes the underscore (_) character and the dollar sign ($) character. An identifier part character is any character for which the method <methodname> Character.isJavaIdentifierPart</methodname> returns <literal>true</literal>. The question mark (?) character is reserved for use by the Java Persistence -query language. The following are reserved identifiers: <itemizedlist> -<listitem><para><literal>SELECT</literal> - </para> - </listitem> - <listitem> - <para> +query language. The following are reserved identifiers: + </para> + <itemizedlist> + <listitem> + <para> + <literal>SELECT</literal> + </para> + </listitem> + <listitem> + <para> <literal>FROM</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>WHERE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>UPDATE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>DELETE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>JOIN</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>OUTER</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>INNER</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>LEFT</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>GROUP</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>BY</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>HAVING</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>FETCH</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>DISTINCT</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>OBJECT</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>NULL</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>TRUE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>FALSE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>NOT</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>AND</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>OR</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>BETWEEN</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>LIKE</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>IN</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>AS</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>UNKNOWN</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>EMPTY</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>MEMBER</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>OF</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>IS</literal> - </para> - </listitem> - <listitem> - <para> + </para> + </listitem> + <listitem> + <para> <literal>AVG</literal> </para> </listitem> @@ -1400,18 +1389,14 @@ query language. The following are reserved identifiers: <itemizedlist> <listitem> <para> <literal>SOME</literal> - </para> - </listitem> - </itemizedlist> - - - Reserved identifiers are - case insensitive. Reserved identifiers must not be used as identification - variables. It is recommended that other SQL reserved words also not - be as identification variables in queries because they may be used as - reserved identifiers in future releases of the specification. - - + </para> + </listitem> + </itemizedlist> + <para> +Reserved identifiers are case insensitive. Reserved identifiers must not be +used as identification variables. It is recommended that other SQL reserved +words also not be as identification variables in queries because they may be +used as reserved identifiers in future releases of the specification. </para> </section> <section id="jpa_langref_from_vars"> @@ -1453,13 +1438,16 @@ preceding identification variable declaration of the query string. The syntax for declaring an identification variable as a range variable is -similar to that of SQL; optionally, it uses the AS keyword. -range_variable_declaration ::= abstract_schema_name [AS] -identification_variable - - - +similar to that of SQL; optionally, it uses the AS keyword. + + + +range_variable_declaration ::= abstract_schema_name [AS] +identification_variable + + + Range variable declarations allow the developer to designate a "root" for objects which may not be reachable by navigation. In order to select values by @@ -1473,10 +1461,12 @@ magazines published by "Adventure" publishers. This example illustrates the use of two different identification variables in the FROM clause, both of the abstract schema type Magazine. The SELECT clause of this query determines that it is the magazines with prices greater than those -of "Adventure" publisher's that are returned. SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2 +of "Adventure" publisher's that are returned. + + +SELECT DISTINCT mag1 FROM Magazine mag1, Magazine mag2 WHERE mag1.price > mag2.price AND mag2.publisher.name = 'Adventure' -
@@ -1497,9 +1487,11 @@ considered to have no value, and does not participate in the determination of the result. The syntax for single-valued path expressions and collection valued path expressions is as follows: </para> - <para> -<itemizedlist><listitem><para>single_valued_path_expression ::= -state_field_path_expression | single_valued_association_path_expression + <itemizedlist> + <listitem> + <para> +single_valued_path_expression ::= state_field_path_expression | +single_valued_association_path_expression </para> </listitem> <listitem> @@ -1523,10 +1515,9 @@ identification_variable.{single_valued_association_field.}*collection_valued_ass <listitem> <para> state_field ::= {embedded_class_state_field.}*simple_state_field - </para> - </listitem> - </itemizedlist> - </para> + </para> + </listitem> + </itemizedlist> <para> A single_valued_association_field is designated by the name of an association-field in a one-to-one or many-to-one relationship. The type of a @@ -1569,13 +1560,14 @@ the <literal>FROM</literal> clause and a join condition in the <literal>WHERE <para> The syntax for explicit join operations is as follows: </para> - <para> -<itemizedlist><listitem><para>join ::= join_spec -join_association_path_expression [AS] identification_variable - </para> - </listitem> - <listitem> - <para> + <itemizedlist> + <listitem> + <para> +join ::= join_spec join_association_path_expression [AS] identification_variable + </para> + </listitem> + <listitem> + <para> fetch_join ::= join_spec FETCH join_association_path_expression </para> </listitem> @@ -1588,10 +1580,9 @@ join_single_valued_association_path_expression <listitem> <para> join_spec ::= [ LEFT [OUTER] | INNER ] JOIN - </para> - </listitem> - </itemizedlist> - </para> + </para> + </listitem> + </itemizedlist> <para> The following inner and outer join operation types are supported. </para> @@ -1604,16 +1595,25 @@ The syntax for the inner join operation is <programlisting> [ INNER ] JOIN join_association_path_expression [AS] identification_variable </programlisting> For example, the query below joins over the relationship between publishers and magazines. This type of join typically equates to a join -over a foreign key relationship in the database. <programlisting>SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue > 1000000 -</programlisting> +over a foreign key relationship in the database. </para> +<programlisting> +SELECT pub FROM Publisher pub JOIN pub.magazines mag WHERE pub.revenue > 1000000 +</programlisting> <para> -The keyword <literal>INNER</literal> may optionally be used: <programlisting>SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue > 1000000 -</programlisting> This is equivalent to the following query using the earlier -<literal>IN</literal> construct. It selects those publishers with revenue of -over 1 million for which at least one magazine exists: <programlisting>SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue > 1000000 -</programlisting> +The keyword <literal>INNER</literal> may optionally be used: </para> +<programlisting> +SELECT pub FROM Publisher pub INNER JOIN pub.magazines mag WHERE pub.revenue > 1000000 +</programlisting> + <para> +This is equivalent to the following query using the earlier +<literal>IN</literal> construct. It selects those publishers with revenue of +over 1 million for which at least one magazine exists: + </para> +<programlisting> +SELECT OBJECT(pub) FROM Publisher pub, IN(pub.magazines) mag WHERE pub.revenue > 1000000 +</programlisting> </section> <section id="jpa_langref_outer_joins"> <title> diff --git a/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml b/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml index 86365668a..abe99278e 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_sqlquery.xml @@ -81,8 +81,8 @@ The <classname>EntityManager</classname> has two factory methods suitable for creating SQL queries: </para> <programlisting> -public Query createNativeQuery (String sqlString, Class resultClass); -public Query createNativeQuery (String sqlString, String resultSetMapping); +public Query createNativeQuery(String sqlString, Class resultClass); +public Query createNativeQuery(String sqlString, String resultSetMapping); </programlisting> <para> The first method is used to create a new <classname>Query</classname> instance @@ -99,8 +99,8 @@ action. EntityManager em = ...; -Query query = em.createNativeQuery ("SELECT * FROM MAG", Magazine.class); -processMagazines (query.getResultList ()); +Query query = em.createNativeQuery("SELECT * FROM MAG", Magazine.class); +processMagazines(query.getResultList()); @@ -182,7 +182,6 @@ simple mapping between a class and the database: - @@ -190,11 +189,11 @@ simple mapping between a class and the database: Retrieving Persistent Objects -Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, " +Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, " + "VERS FROM MAG WHERE PRICE > 5 AND PRICE < 10", Magazine.class); -List<Magazine> results = query.getResultList (); +List<Magazine> results = (List<Magazine>) query.getResultList(); for (Magazine mag : results) - processMagazine (mag); + processMagazine(mag); @@ -207,13 +206,13 @@ magazines in any price range: SQL Query Parameters -Query query = em.createNativeQuery ("SELECT ISBN, TITLE, PRICE, " +Query query = em.createNativeQuery("SELECT ISBN, TITLE, PRICE, " + "VERS FROM MAG WHERE PRICE > ?1 AND PRICE < ?2", Magazine.class); -query.setParameter (1, 5d); -query.setParameter (2, 10d); +query.setParameter(1, 5d); +query.setParameter(2, 10d); -List<Magazine> results = query.getResultList (); +List<Magazine> results = (List<Magazine>) query.getResultList(); for (Magazine mag : results) processMagazine (mag); diff --git a/openjpa-project/src/doc/manual/jpa_overview_trans.xml b/openjpa-project/src/doc/manual/jpa_overview_trans.xml index 7aa352cb6..984378dbf 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_trans.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_trans.xml @@ -140,10 +140,9 @@ includes a method to transfer funds from one user to another, and it looks something like this: -public void transferFunds (User from, User to, double amnt) -{ - from.decrementAccount (amnt); - to.incrementAccount (amnt); +public void transferFunds(User from, User to, double amnt) { + from.decrementAccount(amnt); + to.incrementAccount(amnt); } @@ -280,8 +279,8 @@ of hanging due to deadlock. OpenJPA uses optimistic semantics by default, but supports both optimistic and datastore transactions. OpenJPA also offers advanced locking and versioning APIs for fine-grained control over database resource allocation and object -versioning. See of the Reference Guide for details -on locking. +versioning. See of the Reference Guide for +details on locking. of this document covers standard object versioning, while of the Reference Guide discusses additional versioning strategies available in OpenJPA. @@ -312,13 +311,13 @@ JPA integrates with your container's managed transactions, allowing you to use the container's declarative transaction demarcation and its Java Transaction API (JTA) implementation for transaction management. Outside of a container, though, you must demarcate transactions manually through JPA. The - EntityTransaction interface controls unmanaged +EntityTransaction interface controls unmanaged transactions in JPA. -public void begin (); -public void commit (); -public void rollback (); +public void begin(); +public void commit(); +public void rollback(); @@ -376,7 +375,7 @@ also ends the persistence context. All managed entites will be detached from the EntityManager. -public boolean isActive (); +public boolean isActive(); @@ -388,31 +387,30 @@ public boolean isActive (); Finally, the isActive method returns true - if the transaction is in progress ( begin + if the transaction is in progress (begin has been called more recently than commit or -rollback ), and false otherwise. +rollback), and false otherwise. Grouping Operations with Transactions -public void transferFunds (EntityManager em, User from, User to, double amnt) -{ +public void transferFunds(EntityManager em, User from, User to, double amnt) { // note: it would be better practice to move the transaction demarcation // code out of this method, but for the purposes of example... - Transaction trans = em.getTransaction (); - trans.begin (); + Transaction trans = em.getTransaction(); + trans.begin(); try { - from.decrementAccount (amnt); - to.incrementAccount (amnt); - trans.commit (); + from.decrementAccount(amnt); + to.incrementAccount(amnt); + trans.commit(); } catch (RuntimeException re) { - if (trans.isActive ()) - trans.rollback (); // or could attempt to fix error and retry + if (trans.isActive()) + trans.rollback(); // or could attempt to fix error and retry throw re; } } diff --git a/openjpa-project/src/doc/manual/jpa_overview_why.xml b/openjpa-project/src/doc/manual/jpa_overview_why.xml index 79b4ea5aa..7433a04a8 100644 --- a/openjpa-project/src/doc/manual/jpa_overview_why.xml +++ b/openjpa-project/src/doc/manual/jpa_overview_why.xml @@ -287,9 +287,7 @@ by the table below. - - Relational and Non-Relational Stores - + Relational and Non-Relational Stores No diff --git a/openjpa-project/src/doc/manual/jpa_resources.xml b/openjpa-project/src/doc/manual/jpa_resources.xml index 4d42fe7d6..1928bf873 100644 --- a/openjpa-project/src/doc/manual/jpa_resources.xml +++ b/openjpa-project/src/doc/manual/jpa_resources.xml @@ -22,7 +22,7 @@ javax.persistence Javadoc -OpenJPA API Javadoc +OpenJPA API Javadoc diff --git a/openjpa-project/src/doc/manual/manual.xml b/openjpa-project/src/doc/manual/manual.xml index 8f9ac054c..cf8216075 100644 --- a/openjpa-project/src/doc/manual/manual.xml +++ b/openjpa-project/src/doc/manual/manual.xml @@ -37,7 +37,7 @@ ]> - OpenJPA Developers Guide + OpenJPA User's Guide @@ -62,13 +62,16 @@ &jpa_overview_conclusion.xml; + - OpenJPA <phrase>JPA</phrase> Reference Guide + Reference Guide &ref_guide_intro.xml; &ref_guide_conf.xml; &ref_guide_logging.xml; @@ -84,10 +87,12 @@ &ref_guide_optimization.xml; + &jpa_resources.xml; &supported_databases.xml; diff --git a/openjpa-project/src/doc/manual/openjpa_intro.xml b/openjpa-project/src/doc/manual/openjpa_intro.xml index 06a00b7cf..06d686656 100644 --- a/openjpa-project/src/doc/manual/openjpa_intro.xml +++ b/openjpa-project/src/doc/manual/openjpa_intro.xml @@ -1,30 +1,27 @@ OpenJPA - <phrase> - JPA - </phrase> OpenJPA - - JPA - -OpenJPA is Apache's implementation of Sun's Java Persistence API (JPA) -specification for the transparent persistence of Java objects. This -document provides an overview of the JPA standard and technical +OpenJPA is Apache's implementation of Sun's Java Persistence API (JPA) +specification for the transparent persistence of Java objects. This +document provides an overview of the JPA standard and technical details on the use of OpenJPA. +
About This Document @@ -36,25 +33,27 @@ This document is intended for OpenJPA users. It is divided into several parts: <listitem> <para> The <link linkend="jpa_overview_intro">JPA Overview</link> describes the -fundamentals of JPA. +fundamentals of the JPA specification. </para> </listitem> +<!-- +### TUTORIAL <listitem> <para> -In the <link linkend="tutorials">OpenJPA <phrase>JPA</phrase> Tutorials</link> -you will develop simple persistent applications using OpenJPA. Through the +In the <link linkend="tutorials">OpenJPA Tutorials</link> you will develop +simple persistent applications using OpenJPA. Through the tutorials' hands-on approach, you will become comfortable with the core tools -and development processes under OpenJPA <phrase>JPA</phrase>. +and development processes under OpenJPA. </para> </listitem> +--> <listitem> <para> -The <link linkend="ref_guide_intro">OpenJPA <phrase>JPA</phrase> Reference Guide -</link> contains detailed documentation on all aspects of OpenJPA <phrase>JPA -</phrase>. Browse through this guide to familiarize yourself with the many -advanced features and customization opportunities OpenJPA provides. Later, you -can use the guide when you need details on a specific aspect of OpenJPA <phrase> -JPA</phrase>. +The <link linkend="ref_guide_intro">OpenJPA Reference Guide</link> contains +detailed documentation on all aspects of OpenJPA. Browse through this guide +to familiarize yourself with the many advanced features and customization +opportunities OpenJPA provides. Later, you can use the guide when you need +details on a specific aspect of OpenJPA. </para> </listitem> </itemizedlist> diff --git a/openjpa-project/src/doc/manual/ref_guide_caching.xml b/openjpa-project/src/doc/manual/ref_guide_caching.xml index 486c60bc1..1d631ebf8 100644 --- a/openjpa-project/src/doc/manual/ref_guide_caching.xml +++ b/openjpa-project/src/doc/manual/ref_guide_caching.xml @@ -289,7 +289,8 @@ tips on how to use this package to extend OpenJPA's caching service yourself. <para> Rather than use the low-level <literal>org.apache.openjpa.datacache</literal> package APIs, JPA users should typically access the data cache through OpenJPA's -high-level <ulink url="../../api/openjpa/persistence/StoreCache.html"> +high-level +<ulink url="../apidocs/org/apache/openjpa/persistence/StoreCache.html"> <classname>org.apache.openjpa.persistence.StoreCache</classname></ulink> facade. This facade has methods to pin and unpin records, evict data from the cache, and more. @@ -309,7 +310,7 @@ corresponding persistent class, and dynamically delegates to that cache. </para> <para> If you know that you want to access a certain data cache and no others, the -<ulink url="../../api/openjpa/persistence/OpenJPAEntityManagerFactory.html"> +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManagerFactory.html"> <methodname>OpenJPAEntityManagerFactory.getStoreCache(String name)</methodname> </ulink> method returns a <classname>StoreCache</classname> interface to a particular named data cache. @@ -381,8 +382,8 @@ cache.evict (Magazine.class, changedMag.getId ()); </example> <para> See the <classname>StoreCache</classname> -<ulink url="../../api/openjpa/persistence/StoreCache.html">Javadoc</ulink> for -information on additional functionality it provides. Also, +<ulink url="../apidocs/org/apache/openjpa/persistence/StoreCache.html"> +Javadoc</ulink> for information on additional functionality it provides. Also, <xref linkend="ref_guide_runtime"/> discusses OpenJPA's other extensions to the standard set of JPA runtime interfaces. </para> @@ -445,10 +446,10 @@ execution time is fully traversed. </para> <para> OpenJPA exposes a high-level interface to the query cache through the -<ulink url="../../api/openjpa/persistence/QueryResultCache.html"><classname> -org.apache.openjpa.persistence.QueryResultCache</classname></ulink> class. You -can access this class through the <classname> OpenJPAEntityManagerFactory -</classname>. +<ulink url="../apidocs/org/apache/openjpa/persistence/QueryResultCache.html"> +<classname>org.apache.openjpa.persistence.QueryResultCache</classname></ulink> +class. You can access this class through the <classname> +OpenJPAEntityManagerFactory</classname>. </para> <example id="ref_guide_cache_queryaccess"> <title> @@ -825,8 +826,8 @@ instead. <listitem> <para> <literal>ClearOnClose</literal>: Whether the Tangosol named cache should be -completely cleared when the <phrase><classname>EntityManagerFactory</classname> -</phrase> is closed. Defaults to <literal>false</literal>. +completely cleared when the <classname>EntityManagerFactory</classname> +is closed. Defaults to <literal>false</literal>. </para> </listitem> </itemizedlist> diff --git a/openjpa-project/src/doc/manual/ref_guide_conf.xml b/openjpa-project/src/doc/manual/ref_guide_conf.xml index 2fc6f91fb..61ed7773e 100644 --- a/openjpa-project/src/doc/manual/ref_guide_conf.xml +++ b/openjpa-project/src/doc/manual/ref_guide_conf.xml @@ -101,7 +101,7 @@ configuration resource to use, and to override any property. </itemizedlist> <note> <para> -Internally, the OpenJPA <phrase>JPA</phrase> runtime environment and development +Internally, the OpenJPA runtime environment and development tools manipulate property settings through a general <ulink url="../apidocs/ResultObjectProvider/lib/conf/Configuration.html"> <classname>Configuration</classname></ulink> interface, and in particular its @@ -143,11 +143,11 @@ do not have a default resource in place, or when you wish to override the defaults. The given value can be the path to a file, or the resource name of a file somewhere in the <literal>CLASSPATH</literal>. OpenJPA will search the given location as well as the location prefixed by <filename> META-INF/ -</filename>. Thus, to point a OpenJPA tool at <phrase><filename> -META-INF/persistence.xml</filename>,</phrase> you can use: +</filename>. Thus, to point a OpenJPA tool at <filename> +META-INF/my-persistence.xml</filename>, you can use: </para> <programlisting> -<tool> -p persistence.xml +<tool> -p my-persistence.xml </programlisting> </listitem> <listitem> @@ -232,10 +232,10 @@ number of lines to skip between sections of code. Defaults to 2. </itemizedlist> <example id="ref_guide_conf_devtools_format_ex"> <title> - Code Formatting with the Reverse Mapping Tool + Code Formatting with the Application Id Tool -java org.apache.openjpa.jdbc.meta.ReverseMappingTool -cf.spaceBeforeParen true -cf.tabSpaces 4 +java org.apache.openjpa.enhance.ApplicationIdTool -cf.spaceBeforeParen true -cf.tabSpaces 4
@@ -353,6 +353,7 @@ majority of developers can omit them. The following properties apply to any OpenJPA back-end, though the given descriptions are tailored to OpenJPA's default JDBC store. +
openjpa.AutoClear @@ -418,7 +420,7 @@ standard set of listeners. See <xref linkend="ref_guide_enterprise_queryext"/> </tertiary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.AutoClear +<emphasis role="bold">Property name: </emphasis><literal>openjpa.AutoClear </literal> </para> <para> @@ -428,14 +430,14 @@ standard set of listeners. See <xref linkend="ref_guide_enterprise_queryext"/> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> AutoClear</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>datastore</literal> +<emphasis role="bold">Default: </emphasis><literal>datastore</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>datastore</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>datastore</literal>, <literal>all</literal> </para> <para> @@ -465,7 +467,7 @@ transaction. </tertiary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.AutoDetach +<emphasis role="bold">Property name: </emphasis><literal>openjpa.AutoDetach </literal> </para> <para> @@ -475,14 +477,14 @@ transaction. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> AutoDetach</literal> </para> <para> <emphasis role="bold">Default:</emphasis> - </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>close</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>close</literal>, <literal>commit</literal>, <literal>nontx-read</literal> </para> <para> @@ -500,7 +502,7 @@ when managed instances will be automatically detached. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.BrokerFactory +<emphasis role="bold">Property name: </emphasis><literal>openjpa.BrokerFactory </literal> </para> <para> @@ -510,14 +512,14 @@ when managed instances will be automatically detached. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> BrokerFactory</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>jdbc</literal> +<emphasis role="bold">Default: </emphasis><literal>jdbc</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>jdbc</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>jdbc</literal>, <literal>abstractstore</literal>, <literal>remote</literal> </para> <para> @@ -546,7 +548,7 @@ use. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.BrokerImpl +<emphasis role="bold">Property name: </emphasis><literal>openjpa.BrokerImpl </literal> </para> <para> @@ -556,11 +558,11 @@ use. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> BrokerImpl</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>default</literal> +<emphasis role="bold">Default: </emphasis><literal>default</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -588,7 +590,7 @@ org.apache.openjpa.kernel.Broker</classname></ulink> type to use at runtime. See </see> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.ClassResolver +<emphasis role="bold">Property name: </emphasis><literal>openjpa.ClassResolver </literal> </para> <para> @@ -598,11 +600,11 @@ org.apache.openjpa.kernel.Broker</classname></ulink> type to use at runtime. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ClassResolver</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>default</literal> +<emphasis role="bold">Default: </emphasis><literal>default</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -628,7 +630,7 @@ special classloading needs. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Compatibility +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Compatibility </literal> </para> <para> @@ -638,7 +640,7 @@ special classloading needs. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Compatibility</literal> </para> <para> @@ -667,7 +669,7 @@ behavior of previous OpenJPA releases. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionDriverName</literal> </para> <para> @@ -678,7 +680,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionDriverName </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionDriverName</literal> </para> <para> @@ -709,7 +711,7 @@ database. See <xref linkend="ref_guide_dbsetup"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.Connection2DriverName</literal> </para> <para> @@ -720,7 +722,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2DriverName </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Connection2DriverName</literal> </para> <para> @@ -752,7 +754,7 @@ alternate connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactory</literal> </para> <para> @@ -762,7 +764,7 @@ openjpa.ConnectionFactory</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactory</literal> </para> <para> @@ -792,7 +794,7 @@ ConnectionFactory</literal> </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactory2</literal> </para> <para> @@ -802,7 +804,7 @@ openjpa.ConnectionFactory2</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactory2</literal> </para> <para> @@ -832,7 +834,7 @@ javax.sql.DataSource</classname> to use to connect to the database. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactoryName</literal> </para> <para> @@ -843,7 +845,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryName </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactoryName</literal> </para> <para> @@ -873,7 +875,7 @@ javax.sql.DataSource</classname> to use to connect to the database. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactory2Name</literal> </para> <para> @@ -884,7 +886,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Name </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactory2Name</literal> </para> <para> @@ -914,7 +916,7 @@ See <xref linkend="ref_guide_enterprise_xa"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactoryMode</literal> </para> <para> @@ -925,14 +927,14 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryMode </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactoryMode</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>local</literal> +<emphasis role="bold">Default: </emphasis><literal>local</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>local</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>local</literal>, <literal>managed</literal> </para> <para> @@ -959,7 +961,7 @@ when integrating with the application server's managed transactions. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactoryProperties</literal> </para> <para> @@ -970,7 +972,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactoryProperties </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactoryProperties</literal> </para> <para> @@ -979,7 +981,7 @@ ConnectionFactoryProperties</literal> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see <xref linkend="ref_guide_conf_plugins"/>) listing properties for -configuration of the <classname>javax.sql.DataSource</classname> in use. See the +configuration of the datasource in use. See the <xref linkend="ref_guide_dbsetup"/> for details. </para> </section> @@ -1001,7 +1003,7 @@ configuration of the <classname>javax.sql.DataSource</classname> in use. See the </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionFactory2Properties</literal> </para> <para> @@ -1012,7 +1014,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionFactory2Properties </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionFactory2Properties</literal> </para> <para> @@ -1044,7 +1046,7 @@ alternate connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionPassword</literal> </para> <para> @@ -1054,7 +1056,7 @@ openjpa.ConnectionPassword</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionPassword</literal> </para> <para> @@ -1084,7 +1086,7 @@ specified in the <literal>ConnectionUserName</literal> property. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.Connection2Password</literal> </para> <para> @@ -1094,7 +1096,7 @@ openjpa.Connection2Password</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Connection2Password</literal> </para> <para> @@ -1126,7 +1128,7 @@ alternate connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionProperties</literal> </para> <para> @@ -1137,7 +1139,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionProperties </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionProperties</literal> </para> <para> @@ -1168,7 +1170,7 @@ described below. See <xref linkend="ref_guide_dbsetup"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.Connection2Properties</literal> </para> <para> @@ -1179,7 +1181,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnection2Properties </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Connection2Properties</literal> </para> <para> @@ -1211,7 +1213,7 @@ alternate connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.ConnectionURL +<emphasis role="bold">Property name: </emphasis><literal>openjpa.ConnectionURL </literal> </para> <para> @@ -1221,7 +1223,7 @@ alternate connection factory used for unmanaged connections. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionURL</literal> </para> <para> @@ -1250,7 +1252,7 @@ ConnectionURL</literal> </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Connection2URL +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Connection2URL </literal> </para> <para> @@ -1260,7 +1262,7 @@ ConnectionURL</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Connection2URL</literal> </para> <para> @@ -1292,7 +1294,7 @@ connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionUserName</literal> </para> <para> @@ -1302,7 +1304,7 @@ openjpa.ConnectionUserName</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionUserName</literal> </para> <para> @@ -1332,7 +1334,7 @@ for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.Connection2UserName</literal> </para> <para> @@ -1342,7 +1344,7 @@ openjpa.Connection2UserName</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Connection2UserName</literal> </para> <para> @@ -1374,7 +1376,7 @@ alternate connection factory used for unmanaged connections. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.ConnectionRetainMode</literal> </para> <para> @@ -1385,11 +1387,11 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getConnectionRetainMode </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ConnectionRetainMode</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>on-demand</literal> +<emphasis role="bold">Default: </emphasis><literal>on-demand</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Controls how OpenJPA uses @@ -1415,7 +1417,7 @@ sessions. See <xref linkend="ref_guide_dbsetup_retain"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.DataCache +<emphasis role="bold">Property name: </emphasis><literal>openjpa.DataCache </literal> </para> <para> @@ -1425,11 +1427,11 @@ sessions. See <xref linkend="ref_guide_dbsetup_retain"/> for details. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> DataCache</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin list string (see @@ -1457,7 +1459,7 @@ caching. See <xref linkend="ref_guide_cache_conf"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.DataCacheManager</literal> </para> <para> @@ -1467,11 +1469,11 @@ openjpa.DataCacheManager</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> DataCacheManager</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>default</literal> +<emphasis role="bold">Default: </emphasis><literal>default</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -1500,7 +1502,7 @@ on data caching. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.DataCacheTimeout</literal> </para> <para> @@ -1510,11 +1512,11 @@ openjpa.DataCacheTimeout</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> DataCacheTimeout</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>-1</literal> +<emphasis role="bold">Default: </emphasis><literal>-1</literal> </para> <para> <emphasis role="bold">Description:</emphasis> The number of milliseconds that @@ -1544,7 +1546,7 @@ classes. See <xref linkend="ref_guide_cache_conf"/> for details. </tertiary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.DetachState +<emphasis role="bold">Property name: </emphasis><literal>openjpa.DetachState </literal> </para> <para> @@ -1554,14 +1556,14 @@ classes. See <xref linkend="ref_guide_cache_conf"/> for details. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> DetachState</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>loaded</literal> +<emphasis role="bold">Default: </emphasis><literal>loaded</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>loaded</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>loaded</literal>, <literal>fgs</literal>, <literal>all</literal> </para> <para> @@ -1596,7 +1598,7 @@ of the detached graph and related options. For more details, see </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.DynamicDataStructs</literal> </para> <para> @@ -1606,11 +1608,11 @@ openjpa.DynamicDataStructs</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> DynamicDataStructs</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether to dynamically generate @@ -1643,7 +1645,7 @@ memory and speed optimization over time. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.FetchBatchSize +<emphasis role="bold">Property name: </emphasis><literal>openjpa.FetchBatchSize </literal> </para> <para> @@ -1653,11 +1655,11 @@ memory and speed optimization over time. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> FetchBatchSize</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>-1</literal> +<emphasis role="bold">Default: </emphasis><literal>-1</literal> </para> <para> <emphasis role="bold">Description:</emphasis> The number of rows to fetch at @@ -1678,7 +1680,7 @@ runtime. See <xref linkend="ref_guide_dbsetup_lrs"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.FetchGroups +<emphasis role="bold">Property name: </emphasis><literal>openjpa.FetchGroups </literal> </para> <para> @@ -1688,7 +1690,7 @@ runtime. See <xref linkend="ref_guide_dbsetup_lrs"/> for details. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> FetchGroups</literal> </para> <para> @@ -1701,6 +1703,7 @@ Fetch groups can also be set at runtime. See <xref linkend="ref_guide_fetch"/> for details. </para> </section> + <!-- <section id="openjpa.FilterListeners"> <title> openjpa.FilterListeners @@ -1719,7 +1722,7 @@ Fetch groups can also be set at runtime. See <xref linkend="ref_guide_fetch"/> </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.FilterListeners +<emphasis role="bold">Property name: </emphasis><literal>openjpa.FilterListeners </literal> </para> <para> @@ -1729,7 +1732,7 @@ Fetch groups can also be set at runtime. See <xref linkend="ref_guide_fetch"/> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> FilterListeners</literal> </para> <para> @@ -1745,6 +1748,7 @@ listeners. You can also add filter listeners to individual queries. See <xref linkend="ref_guide_enterprise_queryext"/> for details. </para> </section> + --> <section id="openjpa.FlushBeforeQueries"> <title> openjpa.FlushBeforeQueries @@ -1771,11 +1775,11 @@ listeners. You can also add filter listeners to individual queries. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.FlushBeforeQueries</literal> </para> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.FlushBeforeQueries</literal> </para> <para> @@ -1785,11 +1789,11 @@ openjpa.FlushBeforeQueries</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> FlushBeforeQueries</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal> +<emphasis role="bold">Default: </emphasis><literal>true</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether or not to flush any @@ -1807,7 +1811,7 @@ query. See <xref linkend="ref_guide_dbsetup_retain"/> for details. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.IgnoreChanges +<emphasis role="bold">Property name: </emphasis><literal>openjpa.IgnoreChanges </literal> </para> <para> @@ -1817,11 +1821,11 @@ query. See <xref linkend="ref_guide_dbsetup_retain"/> for details. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> IgnoreChanges</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether to consider modifications @@ -1851,7 +1855,7 @@ or flush before running it against the datastore. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.InverseManager +<emphasis role="bold">Property name: </emphasis><literal>openjpa.InverseManager </literal> </para> <para> @@ -1861,14 +1865,14 @@ or flush before running it against the datastore. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> InverseManager</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>false</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>false</literal>, <literal>true</literal> </para> <para> @@ -1898,7 +1902,7 @@ for managing bidirectional relations upon a flush. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.LockManager +<emphasis role="bold">Property name: </emphasis><literal>openjpa.LockManager </literal> </para> <para> @@ -1908,14 +1912,14 @@ for managing bidirectional relations upon a flush. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> LockManager</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>pessimistic</literal> +<emphasis role="bold">Default: </emphasis><literal>pessimistic</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>none</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>none</literal>, <literal>sjvm</literal>, <literal>pessimistic</literal> </para> <para> @@ -1944,7 +1948,7 @@ locks on persistent instances during transactions. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.LockTimeout +<emphasis role="bold">Property name: </emphasis><literal>openjpa.LockTimeout </literal> </para> <para> @@ -1954,11 +1958,11 @@ locks on persistent instances during transactions. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> LockTimeout</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>-1</literal> +<emphasis role="bold">Default: </emphasis><literal>-1</literal> </para> <para> <emphasis role="bold">Description:</emphasis> The number of milliseconds to wait @@ -1984,7 +1988,7 @@ for an object lock before throwing an exception, or -1 for no limit. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Log</literal> +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Log</literal> </para> <para> <emphasis role="bold">Configuration API:</emphasis> @@ -1993,14 +1997,14 @@ for an object lock before throwing an exception, or -1 for no limit. See </ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal>Log +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal>Log </literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal> +<emphasis role="bold">Default: </emphasis><literal>true</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>openjpa</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>openjpa</literal>, <literal>commons</literal>, <literal>log4j</literal>, <literal>none</literal> </para> <para> @@ -2032,7 +2036,7 @@ For details on logging, see <xref linkend="ref_guide_logging"/>. </tertiary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.ManagedRuntime +<emphasis role="bold">Property name: </emphasis><literal>openjpa.ManagedRuntime </literal> </para> <para> @@ -2042,11 +2046,11 @@ For details on logging, see <xref linkend="ref_guide_logging"/>. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ManagedRuntime</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>auto</literal> +<emphasis role="bold">Default: </emphasis><literal>auto</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -2067,7 +2071,7 @@ enterprise environment. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Mapping +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Mapping </literal> </para> <para> @@ -2077,7 +2081,7 @@ enterprise environment. </ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Mapping</literal> </para> <para> @@ -2106,7 +2110,7 @@ object-to-datastore mapping to use. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.MaxFetchDepth +<emphasis role="bold">Property name: </emphasis><literal>openjpa.MaxFetchDepth </literal> </para> <para> @@ -2116,11 +2120,11 @@ object-to-datastore mapping to use. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> MaxFetchDepth</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>-1</literal> +<emphasis role="bold">Default: </emphasis><literal>-1</literal> </para> <para> <emphasis role="bold">Description:</emphasis> The maximum depth of relations to @@ -2146,7 +2150,7 @@ traverse when eager fetching. Use -1 for no limit. Defaults to no limit. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.MetaDataFactory +<emphasis role="bold">Property name: </emphasis><literal>openjpa.MetaDataFactory </literal> </para> <para> @@ -2156,15 +2160,11 @@ traverse when eager fetching. Use -1 for no limit. Defaults to no limit. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> MetaDataFactory</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>jdo</literal> - </para> - <para> -<emphasis role="bold">Possible values:</emphasis><literal>jdo</literal>, -<literal>jpa</literal>, <literal>openjpa3</literal> +<emphasis role="bold">Default:</emphasis> <literal>jpa</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -2193,7 +2193,7 @@ retrieve metadata for your persistent classes. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Multithreaded +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Multithreaded </literal> </para> <para> @@ -2203,15 +2203,16 @@ retrieve metadata for your persistent classes. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Multithreaded</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether persistent instances and -OpenJPA components will be accessed by multiple threads at once. +OpenJPA components other than the <classname>EntityManagerFactory</classname> +will be accessed by multiple threads at once. </para> </section> <section id="openjpa.Optimistic"> @@ -2232,7 +2233,7 @@ OpenJPA components will be accessed by multiple threads at once. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.Optimistic +<emphasis role="bold">Property name: </emphasis><literal>openjpa.Optimistic </literal> </para> <para> @@ -2242,11 +2243,11 @@ OpenJPA components will be accessed by multiple threads at once. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> Optimistic</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal> +<emphasis role="bold">Default: </emphasis><literal>true</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Selects between optimistic and @@ -2271,7 +2272,7 @@ pessimistic (datastore) transactional modes. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.OrphanedKeyAction</literal> </para> <para> @@ -2281,14 +2282,14 @@ openjpa.OrphanedKeyAction</literal> </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> OrphanedKeyAction</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>log</literal> +<emphasis role="bold">Default: </emphasis><literal>log</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>log</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>log</literal>, <literal>exception</literal>, <literal>none</literal> </para> <para> @@ -2310,7 +2311,7 @@ invoke when OpenJPA discovers an orphaned datastore key. See </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.NontransactionalRead</literal> </para> <para> @@ -2321,11 +2322,11 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalRead </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> NontransactionalRead</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal> +<emphasis role="bold">Default: </emphasis><literal>true</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether the OpenJPA runtime will @@ -2342,7 +2343,7 @@ allow you to read data outside of a transaction. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.NontransactionalWrite</literal> </para> <para> @@ -2353,11 +2354,11 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getNontransactionalWrite </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> NontransactionalWrite</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default:</emphasis> <literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether you can modify persistent @@ -2383,7 +2384,7 @@ will take effect on the next transaction. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.ProxyManager +<emphasis role="bold">Property name: </emphasis><literal>openjpa.ProxyManager </literal> </para> <para> @@ -2393,11 +2394,11 @@ will take effect on the next transaction. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ProxyManager</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>default</literal> +<emphasis role="bold">Default: </emphasis><literal>default</literal> </para> <para> <emphasis role="bold">Description:</emphasis> A plugin string (see @@ -2426,7 +2427,7 @@ mutable second class objects. See </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.QueryCache +<emphasis role="bold">Property name: </emphasis><literal>openjpa.QueryCache </literal> </para> <para> @@ -2436,11 +2437,11 @@ mutable second class objects. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> QueryCache</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal>, when the data +<emphasis role="bold">Default: </emphasis><literal>true</literal>, when the data cache (see <xref linkend="openjpa.DataCache"/>) is also enabled, <literal> false</literal> otherwise. </para> @@ -2453,48 +2454,6 @@ implementation to use for caching of queries loaded from the data store. See <xref linkend="ref_guide_cache_query"/> for details. </para> </section> - <section id="openjpa.QueryCompilationCache"> - <title> - openjpa.QueryCompilationCache - - - - QueryCompilationCache - - - - - caching - - - QueryCompilationCache - - - -Property name: -openjpa.QueryCompilationCache - - -Configuration API: - - -org.apache.openjpa.conf.OpenJPAConfiguration.getQueryCompilationCache - - - -Resource adaptor config-property: -QueryCompilationCache - - -Default:true. - - -Description: A plugin string (see -) describing the -java.util.Map to use for caching of data used during query -compilation. See for details. - -
openjpa.ReadLockLevel @@ -2513,7 +2472,7 @@ compilation. See <xref linkend="ref_guide_cache_querycomp"/> for details. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.ReadLockLevel +<emphasis role="bold">Property name: </emphasis><literal>openjpa.ReadLockLevel </literal> </para> <para> @@ -2523,14 +2482,14 @@ compilation. See <xref linkend="ref_guide_cache_querycomp"/> for details. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> ReadLockLevel</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>read</literal> +<emphasis role="bold">Default: </emphasis><literal>read</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>none</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>none</literal>, <literal>read</literal>, <literal>write</literal>, numeric values for lock-manager specific lock levels </para> @@ -2567,7 +2526,7 @@ levels are equivalent. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.RemoteCommitProvider</literal> </para> <para> @@ -2578,7 +2537,7 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getRemoteCommitProvider </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> RemoteCommitProvider</literal> </para> <para> @@ -2603,7 +2562,7 @@ implementation to use for distributed event notification. See </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.RestoreState +<emphasis role="bold">Property name: </emphasis><literal>openjpa.RestoreState </literal> </para> <para> @@ -2613,14 +2572,14 @@ implementation to use for distributed event notification. See </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> RestoreState</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>none</literal> +<emphasis role="bold">Default: </emphasis><literal>none</literal> </para> <para> -<emphasis role="bold">Possible values:</emphasis><literal>none</literal>, +<emphasis role="bold">Possible values: </emphasis><literal>none</literal>, <literal>immutable</literal>, <literal>all</literal> </para> <para> @@ -2638,7 +2597,7 @@ to their pre-transaction values when a rollback occurs. </primary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal>openjpa.RetainState +<emphasis role="bold">Property name: </emphasis><literal>openjpa.RetainState </literal> </para> <para> @@ -2648,11 +2607,11 @@ to their pre-transaction values when a rollback occurs. </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> RetainState</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>true</literal> +<emphasis role="bold">Default: </emphasis><literal>true</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Whether persistent fields retain @@ -2677,7 +2636,7 @@ their values on transaction commit. </secondary> </indexterm> <para> -<emphasis role="bold">Property name:</emphasis><literal> +<emphasis role="bold">Property name: </emphasis><literal> openjpa.RetryClassRegistration</literal> </para> <para> @@ -2688,11 +2647,11 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getRetryClassRegistration </methodname></ulink> </para> <para> -<emphasis role="bold">Resource adaptor config-property:</emphasis><literal> +<emphasis role="bold">Resource adaptor config-property: </emphasis><literal> RetryClassRegistration</literal> </para> <para> -<emphasis role="bold">Default:</emphasis><literal>false</literal> +<emphasis role="bold">Default: </emphasis><literal>false</literal> </para> <para> <emphasis role="bold">Description:</emphasis> Controls whether to log a warning @@ -2708,12 +2667,12 @@ serious problems. openjpa.SavepointManager -Property name: +Property name: openjpa.SavepointManager Configuration API: - + org.apache.openjpa.conf.OpenJPAConfiguration.getSavepointManager @@ -2721,19 +2680,19 @@ org.apache.openjpa.conf.OpenJPAConfiguration.getSavepointManager SavepointManager -Default:in-mem +Default: in-mem -Possible values:in-mem, +Possible values: in-mem, jdbc, oracle Description: A plugin string (see ) describing a - -org.apache.openjpa.kernel.SavepointManager to use for -managing transaction savepoints. See - for details. + +org.apache.openjpa.kernel.SavepointManager to +use for managing transaction savepoints. See + for details.
@@ -2746,7 +2705,7 @@ managing transaction savepoints. See -Property name:openjpa.Sequence +Property name: openjpa.Sequence @@ -2756,11 +2715,11 @@ managing transaction savepoints. See -Resource adaptor config-property: +Resource adaptor config-property: Sequence -Default:table +Default: table Description: A plugin string (see @@ -2789,7 +2748,7 @@ information. -Property name:openjpa.TransactionMode +Property name: openjpa.TransactionMode @@ -2799,14 +2758,14 @@ information. -Resource adaptor config-property: +Resource adaptor config-property: TransactionMode -Default:local +Default: local -Possible values:local, +Possible values: local, managed @@ -2832,7 +2791,7 @@ use. You can override this setting per-session. -Property name:openjpa.WriteLockLevel +Property name: openjpa.WriteLockLevel @@ -2842,14 +2801,14 @@ use. You can override this setting per-session. -Resource adaptor config-property: +Resource adaptor config-property: WriteLockLevel -Default:write +Default: write -Possible values:none, +Possible values: none, read, write, numeric values for lock-manager specific lock levels @@ -2894,7 +2853,7 @@ The following properties apply exclusively to the OpenJPA JDBC back-end. -Property name: +Property name: openjpa.jdbc.ConnectionDecorators @@ -2905,7 +2864,7 @@ org.apache.openjpa.jdbc.conf.JDBCConfiguration.getConnectionDecorators -Resource adaptor config-property: +Resource adaptor config-property: ConnectionDecorators @@ -2919,7 +2878,7 @@ strings (see ) describing instances to install on the connection factory. These decorators can wrap connections passed from the underlying DataSource to add functionality. OpenJPA will pass all connections through the list of decorators -before using them. Note that by default OpenJPA JPA employs all +before using them. Note that by default OpenJPA employs all of the built-in decorators in the org.apache.openjpa.lib.jdbc package already; you do not need to list them here. @@ -2942,7 +2901,7 @@ of the built-in decorators in the org.apache.openjpa.lib.jdbc -Property name: +Property name: openjpa.jdbc.DBDictionary @@ -2952,7 +2911,7 @@ openjpa.jdbc.DBDictionary -Resource adaptor config-property: +Resource adaptor config-property: DBDictionary @@ -2969,7 +2928,7 @@ openjpa.ConnectionDriverName for database interaction. OpenJPA typically auto-configures the dictionary based on the JDBC URL, but you may have to set this property explicitly if you are using an unrecognized driver, or to plug in your own dictionary for a database -OpenJPA JPA does not support out-of-the-box. See +OpenJPA does not support out-of-the-box. See for details.
@@ -2991,7 +2950,7 @@ OpenJPA JPA does not support out-of-the-box. See -Property name: +Property name: openjpa.jdbc.DriverDataSource @@ -3001,11 +2960,11 @@ openjpa.jdbc.DriverDataSource -Resource adaptor config-property: +Resource adaptor config-property: DriverDataSource -Default:pooling +Default: pooling Description: The alias or full class name of @@ -3013,11 +2972,7 @@ the org.apache.openjpa.jdbc.schema.DriverDataSource implementation to use to wrap JDBC Driver classes with javax.sql.DataSource -instances. The provided default implementation ( - -org.apache.openjpa.jdbc.schema.OpenJPAPoolingDataSource -, will perform connection pooling as described at -. +instances.
@@ -3038,7 +2993,7 @@ instances. The provided default implementation ( -Property name: +Property name: openjpa.jdbc.EagerFetchMode @@ -3048,14 +3003,14 @@ openjpa.jdbc.EagerFetchMode -Resource adaptor config-property: +Resource adaptor config-property: EagerFetchMode -Default:parallel +Default: parallel -Possible values:parallel, +Possible values: parallel, join, none @@ -3082,7 +3037,7 @@ persistent relations. This setting can also be varied at runtime. See -Property name: +Property name: openjpa.jdbc.FetchDirection @@ -3092,14 +3047,14 @@ openjpa.jdbc.FetchDirection -Resource adaptor config-property: +Resource adaptor config-property: FetchDirection -Default:forward +Default: forward -Possible values:forward, +Possible values: forward, reverse, unknown @@ -3126,7 +3081,7 @@ result lists will be accessed. This property can also be varied at runtime. See -Property name: +Property name: openjpa.jdbc.JDBCListeners @@ -3136,7 +3091,7 @@ openjpa.jdbc.JDBCListeners -Resource adaptor config-property: +Resource adaptor config-property: JDBCListeners @@ -3169,7 +3124,7 @@ events. -Property name:openjpa.jdbc.LRSSize +Property name: openjpa.jdbc.LRSSize @@ -3179,14 +3134,14 @@ events. -Resource adaptor config-property: +Resource adaptor config-property: LRSSize -Default:query +Default: query -Possible values:query, +Possible values: query, last, unknown @@ -3213,7 +3168,7 @@ the size of a result list. This property can also be varied at runtime. See -Property name: +Property name: openjpa.jdbc.MappingDefaults @@ -3223,15 +3178,11 @@ openjpa.jdbc.MappingDefaults -Resource adaptor config-property: +Resource adaptor config-property: MappingDefaults -Default: default - - -Possible values:default, -jpa, openjpa3 +Default: jpa Description: A plugin string (see @@ -3261,7 +3212,7 @@ details. -Property name: +Property name: openjpa.jdbc.MappingFactory @@ -3271,17 +3222,13 @@ openjpa.jdbc.MappingFactory -Resource adaptor config-property: +Resource adaptor config-property: MappingFactory Default: - -Possible values:jdo-orm, -jdo-table, jpa, others - - Description: A plugin string (see ) describing the @@ -3308,7 +3255,7 @@ classes. See for details. -Property name: +Property name: openjpa.jdbc.ResultSetType @@ -3318,14 +3265,14 @@ openjpa.jdbc.ResultSetType -Resource adaptor config-property: +Resource adaptor config-property: ResultSetType -Default:forward-only +Default: forward-only -Possible values:forward-only +Possible values: forward-only , scroll-sensitive, scroll-insensitive @@ -3347,7 +3294,7 @@ when fetching result lists. This property can also be varied at runtime. See -Property name:openjpa.jdbc.Schema +Property name: openjpa.jdbc.Schema @@ -3357,7 +3304,7 @@ when fetching result lists. This property can also be varied at runtime. See -Resource adaptor config-property: +Resource adaptor config-property: Schema @@ -3387,7 +3334,7 @@ tables. See for details. -Property name: +Property name: openjpa.jdbc.SchemaFactory @@ -3397,14 +3344,14 @@ openjpa.jdbc.SchemaFactory -Resource adaptor config-property: +Resource adaptor config-property: SchemaFactory -Default:dynamic +Default: dynamic -Possible values:dynamic, +Possible values: dynamic, native, file, table, others @@ -3430,7 +3377,7 @@ use to store and retrieve information about the database schema. See -Property name:openjpa.jdbc.Schemas +Property name: openjpa.jdbc.Schemas @@ -3440,7 +3387,7 @@ use to store and retrieve information about the database schema. See -Resource adaptor config-property: +Resource adaptor config-property: Schemas @@ -3470,7 +3417,7 @@ schemas and/or tables used for your persistent data. See -Property name:openjpa.jdbc.SQLFactory +Property name: openjpa.jdbc.SQLFactory @@ -3480,19 +3427,18 @@ schemas and/or tables used for your persistent data. See -Resource adaptor config-property: +Resource adaptor config-property: SQLFactory -Default:default +Default: default Description: A plugin string (see ) describing the org.apache.openjpa.jdbc.sql.SQLFactory to use to abstract -common SQL constructs. See -for details. +common SQL constructs.
@@ -3521,7 +3467,7 @@ for details. -Property name: +Property name: openjpa.jdbc.SubclassFetchMode @@ -3531,14 +3477,14 @@ openjpa.jdbc.SubclassFetchMode -Resource adaptor config-property: +Resource adaptor config-property: SubclassFetchMode -Default:parallel +Default: parallel -Possible values:parallel, +Possible values: parallel, join, none @@ -3565,7 +3511,7 @@ it is in other tables. This setting can also be varied at runtime. See -Property name: +Property name: openjpa.jdbc.SynchronizeMappings @@ -3576,7 +3522,7 @@ org.apache.openjpa.jdbc.conf.JDBCConfiguration.getSynchronizeMappings -Resource adaptor config-property: +Resource adaptor config-property: SynchronizeMappings @@ -3615,7 +3561,7 @@ mappings and schema at runtime. Useful for rapid test/debug cycles. See -Property name: +Property name: openjpa.jdbc.TransactionIsolation @@ -3626,14 +3572,14 @@ org.apache.openjpa.jdbc.conf.JDBCConfiguration.getTransactionIsolation -Resource adaptor config-property: +Resource adaptor config-property: TransactionIsolation -Default:default +Default: default -Possible values:default, +Possible values: default, none, read-committed, read-uncommitted, repeatable-read, serializable @@ -3662,7 +3608,7 @@ details. -Property name: +Property name: openjpa.jdbc.UpdateManager @@ -3672,11 +3618,11 @@ openjpa.jdbc.UpdateManager -Resource adaptor config-property: +Resource adaptor config-property: UpdateManager -Default:default +Default: default Description: The full class name of the @@ -3684,8 +3630,8 @@ UpdateManager org.apache.openjpa.jdbc.kernel.UpdateManager to use to flush persistent object changes to the datastore. The provided default implementation is - -org.apache.openjpa.jdbc.kernel.ConstraintUpdateManager + +org.apache.openjpa.jdbc.kernel.OperationOrderUpdateManager .
diff --git a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml index 529cc8d8b..7610e7492 100644 --- a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml +++ b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml @@ -8,7 +8,7 @@ -OpenJPA JPA uses a relational database for object persistence. +OpenJPA uses a relational database for object persistence. It communicates with the database using the Java DataBase Connectivity (JDBC) APIs. This chapter describes how to configure OpenJPA to work with the JDBC driver for your database, and how to access JDBC functionality at runtime. @@ -34,9 +34,8 @@ driver for your database, and how to access JDBC functionality at runtime. -OpenJPA includes its own javax.sql.DataSource -implementation, complete with configurable connection pooling and prepared -statement caching. If you choose to use OpenJPA's DataSource +OpenJPA includes its own simple javax.sql.DataSource +implementation. If you choose to use OpenJPA's DataSource , then you must specify the following properties: @@ -84,8 +83,7 @@ user. -To configure advanced features such as connection pooling and prepared statement -caching, or to configure the underlying JDBC driver, use the following optional +To configure advanced features, use the following optional properties. The syntax of these property strings follows the syntax of OpenJPA plugin parameters described in . @@ -121,521 +119,6 @@ openjpa.ConnectionFactoryProperties: OpenJPA's built-in this plugin string: - - - - - connections - - - pooling - - - ExceptionAction - - -ExceptionAction: The action to take when when a connection -that has thrown an exception is returned to the pool. Set to destroy - to destroy the connection. Set to validate to -validate the connection (subject to the TestOnReturn, - TestOnBorrow, and other test settings). Set to -none to ignore the fact that the connection has thrown an exception, -and assume it is still usable. Defaults to destroy. - - - - - - - connections - - - pooling - - - MaxActive - - -MaxActive: The maximum number of database connections in use -at one time. A value of 0 disables connection pooling. Defaults to 8. This is -the maximum number of connections that OpenJPA will give out to your -application. If a connection is requested while MaxActive -other connections are in use, OpenJPA will wait for MaxWait -milliseconds for a connection to be returned, and will then throw an exception -if no connection was made available. - - - - - - - connections - - - pooling - - - MaxIdle - - -MaxIdle: The maximum number of idle database connections to -keep in the pool. Defaults to 8. If this number is less than MaxActive -, then OpenJPA will close extra connections that are returned to the -pool if there are already MaxIdle available connections. This -allows for unexpected or atypical load while still maintaining a relatively -small pool when there is less load on the system. - - - - - - - connections - - - pooling - - - MaxTotal - - -MaxTotal: The maximum number of database connections in the -pool, whether active or idle. Defaults to -1, meaning no limit (the limit will -be dictated by MaxActive and MaxIdle for -each unique user name). - - - - - - - connections - - - pooling - - - MaxWait - - -MaxWait: The maximum number of milliseconds to wait for a -free database connection to become available before giving up. Defaults to 3000. - - - - - - - connections - - - pooling - - - MinEvictableIdleTimeMillis - - -MinEvictableIdleTimeMillis: The minimum number of -milliseconds that a database connection can sit idle before it becomes a -candidate for eviction from the pool. Defaults to 30 minutes. Set to 0 to never -evict a connection based on idle time alone. - - - - - - - connections - - - pooling - - - RollbackOnReturn - - -RollbackOnReturn: Force all connections to be rolled back -when they are retuned to the pool. If false, the DataSource - will only roll back connections when it detects that there have -been any transactional updates on the connection. - - - - - - - connections - - - pooling - - - TestOnBorrow - - -TestOnBorrow: Whether to to validate database connections -before obtaining them from the pool. Note that validation only consists of a -call to the connection's isClosed method unless you -specify a ValidationSQL string. Defaults to true -. - - - - - - - connections - - - pooling - - - TestOnReturn - - -TestOnReturn: Set to true to validate -database connections when they are returned to the pool. Note that validation -only consists of a call to the connection's isClosed -method unless you specify a ValidationSQL string. - - - - - - - connections - - - pooling - - - TestWhileIdle - - -TestWhileIdle: Set to true to periodically -validate idle database connections. - - - - - - - connections - - - pooling - - - TimeBetweenEvictionRunsMillis - - -TimeBetweenEvictionRunsMillis: The number of milliseconds -between runs of the eviction thread. Defaults to -1, meaning -the eviction thread will never run. - - - - - - - connections - - - pooling - - - TrackParameters - - -TrackParameters: When true, OpenJPA will -track the parameters that were set for all PreparedStatement -s that are executed or batched so that they can be included in -error messages. Defaults to true. - - - - - - - connections - - - pooling - - - ValidationSQL - - -ValidationSQL: A simple SQL query to issue to validate a -database connection. If this property is not set, then the only validation -performed is to use the Connection.isClosed method. The -following table shows the default settings for different databases. If a -database is not shown, this property defaults to null. - - - - Validation SQL Defaults - - - - - - - - - - Database - - - SQL - - - - - - - DB2 - - - - SELECT DISTINCT(CURRENT TIMESTAMP) - FROM SYSIBM.SYSTABLES - - - - - - Empress - - - - SELECT DISTINCT(TODAY) - FROM SYS_TABLES - - - - - - Informix - - - - SELECT DISTINCT CURRENT TIMESTAMP - FROM INFORMIX.SYSTABLES - - - - - - MySQL - - - - SELECT NOW() - - - - - - Oracle - - - - SELECT SYSDATE FROM DUAL - - - - - - Postgres - - - - SELECT NOW() - - - - - - SQLServer - - - - SELECT GETDATE() - - - - - - Sybase - - - - SELECT GETDATE() - - - - - -
- -To disable validation SQL, set this property to an empty string, as in - - - - - - - - connections - - - pooling - - - ClosePoolSQL - - -ClosePoolSQL: A simple SQL statement to execute when the -connection pool is completely closed. This can be used, for example, to cleanly -issue a shutdown statement to a file-based database. - - - - - - - connections - - - pooling - - - ValidationTimeout - - -ValidationTimeout: The minimum number of milliseconds that -must elapse before a connection will ever be re-validated. This property is -typically used with TestOnBorrow or TestOnReturn - to reduce the number of validations performed, because the same -connection is often borrowed and returned many times in a short span. Defaults -to 300000 (5 minutes). - - - - - - - connections - - - pooling - - - WarningAction - - -WarningAction: The action to take when a -SQLWarning is detected on a connection. Possible values are: - - - - -ignore: Warnings will not be checked for, and will be -ignored. This is the default. - - - - -trace: The warning will be logged on the TRACE - channel of the JDBC log. - - - - -info: The warning will be logged on the INFO - channel of the JDBC log. - - - - -warn: The warning will be logged on the WARN - channel of the JDBC log. - - - - -error: The warning will be logged on the ERROR - channel of the JDBC log. - - - - -throw: All SQLWarning instances will -be thrown as if they were errors. - - - - -handle: The SQLWarning instance will -be passed through the handleWarning method of - -org.apache.openjpa.jdbc.sql.DBDictionary, which allows a -custom extension of the dictionary to use heuristic-based warning handling. - - - - - - - - - connections - - - pooling - - - WhenExhaustedAction - - -WhenExhaustedAction: The action to take when there are no -available database connections in the pool. Set to exception -to immediately throw an exception. Set to block to block -until a connection is available or the maximum wait time is exceeded. Set to -grow to automatically grow the pool. Defaults to -block. - - - - -Additionally, the following properties are available whether you use OpenJPA's -built-in DataSource or a third-party's: - - - - - - - prepared statement - - - pooling - - - MaxCachedStatements - - -MaxCachedStatements: The maximum number of -java.sql.PreparedStatements to cache. Statement caching can -dramatically speed up some databases. Defaults to 50 for OpenJPA's -DataSource, and 0 for third-party DataSource -s. Most third-party DataSources do not benefit from -OpenJPA's prepared statement cache, because each returned connection has a -unique hash code, making it impossible for OpenJPA to match connections to their -cached statements. - - @@ -650,6 +133,34 @@ cached statements. will wait for a statement to execute. + + + + + SQL + + + PrettyPrint + + +PrettyPrint: Boolean indicating whether to pretty-print +logged SQL statements. + + + + + + + SQL + + + PrettyPrintLineLength + + +PrettyPrintLineLength: The maximum number of characters in +each pretty-printed SQL line. + + @@ -663,7 +174,7 @@ will wait for a statement to execute. <property name="openjpa.ConnectionURL" value="jdbc:hsqldb:db-hypersonic"/> <property name="openjpa.ConnectionDriverName" value="org.hsqldb.jdbcDriver"/> <property name="openjpa.ConnectionFactoryProperties" - value="MaxActive=50, MaxIdle=10, ValidationTimeout=50000, MaxCachedStatements=100, ValidationSQL=''"/> + value="PrettyPrint=true, PrettyPrintLineLength=80"/> @@ -706,11 +217,11 @@ Persistence.createEntityManagerFactory under the Bind the DataSource into JNDI, and then specify its -location in the jta-data-source or +location in the jta-data-source or non-jta-data-source element of the JPA XML format (depending on whether the DataSource is managed by JTA), or in the - + openjpa.ConnectionFactoryName property. @@ -733,11 +244,11 @@ openjpa.ConnectionProperties setting. -Some advanced features of OpenJPA's own DataSource can +The features of OpenJPA's own DataSource can also be used with third-party implementations. OpenJPA layers on top of the third-party DataSource to provide the extra -functionality. To configure these advanced features, including prepared -statement caching, use the +functionality. To configure these features use the + openjpa.ConnectionFactoryProperties property described in the previous section. @@ -782,10 +293,12 @@ Certain application servers automatically enlist their DataSource s in global transactions. When this is the case, OpenJPA should not attempt to commit the underlying connection, leaving JDBC transaction completion to the application server. To notify OpenJPA that your third-party -DataSource is managed by the application server, set the +DataSource is managed by the application server, use the +jta-data-source element of your +persistence.xml file or set the -openjpa.ConnectionFactoryMode property to managed -. +openjpa.ConnectionFactoryMode property to +managed. Note that OpenJPA can only use managed DataSources when @@ -799,15 +312,11 @@ configure a second unmanaged DataSource that OpenJPA can use to perform tasks that are independent of the global transaction. The most common of these tasks is updating the sequence table OpenJPA uses to generate unique primary key values for your datastore identity objects. Configure the -second DataSource just as the first, but use the various +second DataSource using the non-jta-data-source + persistence.xml element, or OpenJPA's various "2" connection properties, such as openjpa.ConnectionFactory2Name or openjpa.Connection2DriverName. These -properties are outlined in . If -your second DataSource is also bound to JNDI, you can use -JPA XML's non-jta-data-source to specify its location. - Typically, though, you will use OpenJPA's built-in -implementation for the second DataSource (see - ). +properties are outlined in . @@ -822,10 +331,6 @@ implementation for the second <classname>DataSource</classname> (see <property name="openjpa.Connection2Password" value="tiger"/> <property name="openjpa.Connection2URL" value="jdbc:oracle:thin:@CROM:1521:OpenJPADB"/> <property name="openjpa.Connection2DriverName" value="oracle.jdbc.driver.OracleDriver"/> - <property name="openjpa.ConnectionFactory2Properties" value="MaxActive=20, MaxIdle=10"/> - <!-- managed transaction and enlisted configuration --> - <property name="openjpa.TransactionMode" value="managed"/> - <property name="openjpa.ConnectionFactoryMode" value="managed"/> </properties> </programlisting> </example> @@ -853,19 +358,20 @@ implementation for the second <classname>DataSource</classname> (see </indexterm> <para> The JPA standard defines how to access JDBC connections from enterprise beans. -OpenJPA also provides APIs to access an <classname> EntityManager</classname>'s +OpenJPA also provides APIs to access an <classname>EntityManager</classname>'s connection, or to retrieve a connection directly from the <classname> EntityManagerFactory</classname>'s <classname>DataSource</classname>. </para> <para> -The <ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> +The +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> <methodname>OpenJPAEntityManager.getConnection</methodname></ulink> method returns an <classname>EntityManager</classname>'s connection. If the <classname> EntityManager</classname> does not already have a connection, it will obtain one. The returned connection is only guaranteed to be transactionally consistent with other <classname>EntityManager</classname> operations if the <classname> EntityManager</classname> is in a managed or non-optimistic transaction, if the -<classname> EntityManager</classname> has flushed in the current transaction, or +<classname>EntityManager</classname> has flushed in the current transaction, or if you have used the <methodname>OpenJPAEntityManager.beginStore</methodname> method to ensure that a datastore transaction is in progress. Always close the returned connection before attempting any other <classname>EntityManager @@ -882,12 +388,12 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManager kem = OpenJPAPersistence.cast (em); -Connection conn = (Connection) kem.getConnection (); +OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); +Connection conn = (Connection) kem.getConnection(); // do JDBC stuff -conn.close (); +conn.close(); </programlisting> </example> <para> @@ -907,14 +413,14 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf); -OpenJPAConfiguration conf = kemf.getConfiguration (); -DataSource dataSource = (DataSource) conf.getConnectionFactory (); -Connection conn = dataSource.getConnection (); +OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast(emf); +OpenJPAConfiguration conf = kemf.getConfiguration(); +DataSource dataSource = (DataSource) conf.getConnectionFactory(); +Connection conn = dataSource.getConnection(); // do JDBC stuff -conn.close (); +conn.close(); </programlisting> </example> </section> @@ -939,7 +445,7 @@ conn.close (); </seealso> </indexterm> <para> -OpenJPA <phrase>JPA</phrase> can take advantage of any JDBC 2.x compliant +OpenJPA can take advantage of any JDBC 2.x compliant driver, making almost any major database a candidate for use. See our officially supported database list in <xref linkend="supported_databases"/> for more information. Typically, OpenJPA auto-configures its JDBC behavior and SQL @@ -993,7 +499,8 @@ the <ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DB2Dictionary.html"> </primary> </indexterm> <literal>derby</literal>: Dictionary for the Apache Derby database. This is an -alias for the <ulink url="javadoc/openjpa/jdbc/sql/DerbyDictionary.html"> +alias for the +<ulink url="../apidocs/org/apache/openjpa/jdbc/sql/DerbyDictionary.html"> <classname>org.apache.openjpa.jdbc.sql.DerbyDictionary</classname> class. </ulink> </para> @@ -1232,9 +739,9 @@ create database primary keys for identifiers. Defaults to <literal>true </secondary> </indexterm> <literal>ConstraintNameMode</literal>: When creating constraints, whether to -put the constraint name before the definition ( <literal>before</literal> ), -just after the constraint type name ( <literal>mid</literal> ), or after the -constraint definition ( <literal>after</literal> ). Defaults to <literal>before +put the constraint name before the definition (<literal>before</literal>), +just after the constraint type name (<literal>mid</literal>), or after the +constraint definition (<literal>after</literal>). Defaults to <literal>before </literal>. </para> </listitem> @@ -3058,147 +2565,6 @@ detects that this is the case, a warning will be logged. </itemizedlist> </section> </section> - <section id="ref_guide_dbsetup_sqlfactory"> - <title> - SQLFactory Properties - - - - SQL - - - SQLFactory - - - -Some aspects of advanced SQL aren't configured through the -DBDictionary, but through the SQLFactory. -The openjpa.jdbc.SQLFactory configuration property is a -plugin string you can use to -configure the following parameters: - - - - - - - prepared statement - - - batching - - - BatchLimit - - -BatchLimit: The maximum number of SQL update statements to -batch together. Set to 0 to disable statement batching, or -1 for no limit. See -. - - - - - - - prepared statement - - - batching - - - BatchParameterLimit - - -BatchParameterLimit: The maximum number of parameters that -can be batched together for a single batch update. Some databases can only -handle a certain total number of prepared statement parameters in a single -batch. This value will cause OpenJPA to flush a SQL batch once the number of -batched statements times the number of bound parameters per statement exceeds -this value. Set to 0 to disable SQL batching, or -1 for no limit. - - - - - - - prepared statement - - - batching - - - SupportsUpdateCountsForBatch - - -SupportsUpdateCountsForBatch: Whether the JDBC driver -correctly returns the set of update counts when a batch statement is executed. - - - - - - - prepared statement - - - batching - - - SupportsTotalCountsForBatch - - -SupportsTotalCountsForBatch: If a JDBC driver doesn't -support batch update counts, whether it at least returns the total number of -updates made when a batch statement is executed. - - - - - - - SQL - - - union - - - SupportsUnion - - -SupportsUnion: Whether the database supports SQL UNIONs. - - - - - - - SQL - - - union - - - SupportsUnionWithUnalignedOrdering - - -SupportsUnionWithUnalignedOrdering: Whether the database -supports SQL UNIONs that order on columns that are not in the same position in -all the SELECTs that make up the UNION. - - - - -The defaults for these properties depend on the database in use. - - - - Configuring SQLFactory Properties - - -<property name="openjpa.jdbc.SQLFactory" value="BatchLimit=100, SupportsUnion=true"/> - - -
Setting the Transaction Isolation @@ -3335,8 +2701,7 @@ Not all databases support this syntax. </itemizedlist> <para> You can change the join syntax at runtime through the OpenJPA fetch -configuration API, which is described in <xref linkend="ref_guide_runtime"/> -. +configuration API, which is described in <xref linkend="ref_guide_runtime"/>. </para> <example id="ref_guide_dbsetup_sql92_conf"> <title> @@ -3355,11 +2720,11 @@ import org.apache.openjpa.persistence.jdbc.*; ... -Query q = em.createQuery ("select m from Magazine m where m.title = 'JDJ'"); -OpenJPAQuery kq = OpenJPAPersistence.cast (q); +Query q = em.createQuery("select m from Magazine m where m.title = 'JDJ'"); +OpenJPAQuery kq = OpenJPAPersistence.cast(q); JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan (); -fetch.setJoinSyntax (JDBCFetchPlan.JOIN_SYNTAX_SQL92); -List results = q.getResultList (); +fetch.setJoinSyntax(JDBCFetchPlan.JOIN_SYNTAX_SQL92); +List results = q.getResultList(); </programlisting> </example> </section> @@ -3376,10 +2741,10 @@ List results = q.getResultList (); </secondary> </indexterm> <para> -Through the properties we've covered thus far, you can configure each <phrase> -<classname>EntityManagerFactory</classname></phrase> to access a different +Through the properties we've covered thus far, you can configure each +<classname>EntityManagerFactory</classname> to access a different database. If your application accesses multiple databases, we recommend that you -maintain a separate properties file for each one. This will allow you to easily +maintain a separate persistence unit for each one. This will allow you to easily load the appropriate resource for each database at runtime, and to give the correct configuration file to OpenJPA's command-line tools during development. </para> @@ -3481,8 +2846,6 @@ non-locking datastore transaction. This is the default. <literal>with-connection</literal>: Flush only if the <classname>EntityManager </classname> has already established a dedicated connection to the datastore, otherwise execute the query in-memory. - </para> - <para> This option is useful if you use long-running optimistic transactions and want to ensure that these transactions do not consume database resources until commit. OpenJPA's behavior with this option is dependent on the transaction @@ -3529,27 +2892,18 @@ results. <entry colname="col1"> </entry> <entry colname="col2"> - - FlushBeforeQueries = false - +FlushBeforeQueries = false </entry> <entry colname="col3"> - - FlushBeforeQueries = true - +FlushBeforeQueries = true </entry> <entry colname="col4"> - - FlushBeforeQueries = with-connection; - ConnectionRetainMode = on-demand - +FlushBeforeQueries = with-connection; +ConnectionRetainMode = on-demand </entry> <entry colname="col5"> - - FlushBeforeQueries = with-connection; - ConnectionRetainMode = transaction - or always - +FlushBeforeQueries = with-connection; +ConnectionRetainMode = transaction or always </entry> </row> </thead> @@ -3557,92 +2911,77 @@ results. <row> <entry colname="col1"> <emphasis role="bold"> - - IgnoreChanges = true - +IgnoreChanges = true </emphasis> </entry> <entry colname="col2"> - no flush +no flush </entry> <entry colname="col3"> - no flush +no flush </entry> <entry colname="col4"> - no flush +no flush </entry> <entry colname="col5"> - no flush +no flush </entry> </row> <row> <entry colname="col1"> <emphasis role="bold"> - - IgnoreChanges = false; no tx active - +IgnoreChanges = false; no tx active </emphasis> </entry> <entry colname="col2"> - no flush +no flush </entry> <entry colname="col3"> - no flush +no flush </entry> <entry colname="col4"> - no flush +no flush </entry> <entry colname="col5"> - no flush +no flush </entry> </row> <row> <entry colname="col1"> <emphasis role="bold"> - - IgnoreChanges = false; datastore tx active - +IgnoreChanges = false; datastore tx active </emphasis> </entry> <entry colname="col2"> - no flush +no flush </entry> <entry colname="col3"> - flush +flush </entry> <entry colname="col4"> - flush +flush </entry> <entry colname="col5"> - flush +flush </entry> </row> <row> <entry colname="col1"> <emphasis role="bold"> - - IgnoreChanges = false; optimistic tx active - +IgnoreChanges = false; optimistic tx active </emphasis> </entry> <entry colname="col2"> - no flush +no flush </entry> <entry colname="col3"> - flush +flush </entry> <entry colname="col4"> - - no flush unless - <methodname> - flush - </methodname> - has - already been invoked - +no flush unless <methodname>flush</methodname> has already been invoked </entry> <entry colname="col5"> - flush +flush </entry> </row> </tbody> @@ -3664,61 +3003,10 @@ results. <programlisting> import org.apache.openjpa.persistence.*; -... - -// obtaining an em with a certain transaction and connection retain mode -OpenJPAEntityManagerFactory kemf = OpenJPAPersistence.cast (emf); -EntityManager em = kemf.createEntityManager (PersistenceContextType.EXTENDED, - false, OpenJPAEntityManager.CONN_RETAIN_ALWAYS); - -... - -// changing the flush mode for an individual EntityManager -OpenJPAEntityManager em = OpenJPAPersistence.cast (em); -FetchPlan fetch = kem.getFetchPlan (); -fetch.setFlushBeforeQueries (FetchPlan.QUERY_FLUSH_TRUE); -</programlisting> - </example> - </section> - <section id="ref_guide_perfpack_batch"> - <title> - Statement Batching - - - - prepared statement - - - batching - - - -In addition to connection pooling and prepared statement caching, OpenJPA -employs statement batching to speed up JDBC updates. Statement batching is -enabled by default for any JDBC driver that supports it. When batching is on, -OpenJPA automatically orders its SQL statements to maximize the size of each -batch. This can result in large performance gains for transactions that modify a -lot of data. - - -You configure statement batching through the system - -DBDictionary, which is controlled by the -openjpa.jdbc.DBDictionary - configuration property. The example below shows how to enable -and disable statement batching via your configuration properties. - - - - Configuring SQL Batching - - -The batch limit is the maximum number of statements OpenJPA will ever batch -together. A value of -1 means "no limit" - this is the default for most -dictionaries. A value of 0 disables batching. - - -<property name="openjpa.jdbc.DBDictionary" value="BatchLimit=25"/> +// obtaining an em with a certain connection retain mode +Map props = new HashMap(); +props.put("openjpa.ConnectionRetainMode", "always"); +EntityManager em = emf.createEntityManager(props);
@@ -3924,14 +3212,14 @@ import org.apache.openjpa.persistence.jdbc.*; ... -Query q = em.createQuery ("select m from Magazine m where m.title = 'JDJ'"); -OpenJPAQuery kq = OpenJPAPersistence.cast (q); -JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan (); -fetch.setFetchSize (20); -fetch.setResultSetType (ResultSet.TYPE_SCROLL_INSENSITIVE); -fetch.setFetchDirection (ResultSet.FETCH_FORWARD); -fetch.setLRSSize (JDBCFetchPlan.SIZE_LAST); -List results = (List) q.getResultList (); +Query q = em.createQuery("select m from Magazine m where m.title = 'JDJ'"); +OpenJPAQuery kq = OpenJPAPersistence.cast(q); +JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan(); +fetch.setFetchSize(20); +fetch.setResultSetType(ResultSet.TYPE_SCROLL_INSENSITIVE); +fetch.setFetchDirection(ResultSet.FETCH_FORWARD); +fetch.setLRSSize(JDBCFetchPlan.SIZE_LAST); +List results = q.getResultList(); @@ -3951,7 +3239,7 @@ List results = (List) q.getResultList (); It is common to duplicate a database model in multiple schemas. You may have one schema for development and another for production, or different database users may access different schemas. OpenJPA facilitates these patterns with the - openjpa.jdbc.Schema +openjpa.jdbc.Schema configuration property. This property establishes a default schema for any unqualified table names, allowing you to leave schema names out of your mapping definitions. @@ -4048,8 +3336,9 @@ built-in options to choose from: dynamic: This is the default setting. It is an alias for the -org.apache.openjpa.jdbc.schema.DynamicSchemaFactory -. The DynamicSchemaFactory is the most performant + +org.apache.openjpa.jdbc.schema.DynamicSchemaFactory. The +DynamicSchemaFactory 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 @@ -4067,11 +3356,9 @@ that OpenJPA can order its SQL statements to meet them. metadata and object-relational mapping information. This factory uses the java.sql.DatabaseMetaData interface to reflect on the schema and ensure that it is consistent with the mapping data being read. -Because the factory doesn't reflect on a table definition until that table is -mentioned by the mapping information, we call it "lazy". 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: +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: @@ -4217,9 +3504,8 @@ dependencies. Thus the schema tool is useful as a general way to manipulate schemas. -You can invoke the schema tool through the schematool -shell/bat script included in the OpenJPA distribution, or through its Java -class, +You can invoke the schema tool through its Java class, + org.apache.openjpa.jdbc.schema.SchemaTool. In addition to the universal flags of the configuration framework, the schema tool accepts the following command @@ -4246,7 +3532,7 @@ CLASSPATH, data will be written to that resource. Use stdout --openjpaTables/-kt <true/t | false/f>: When reflecting +-openjpaTables/-ot <true/t | false/f>: When reflecting on the schema, whether to reflect on tables and sequences whose names start with OPENJPA_. Certain OpenJPA components may use such tables - for example, the table schema factory option covered in @@ -4286,23 +3572,21 @@ indexes on existing tables. Defaults to true. -primaryKeys/-pk <true/t | false/f>: Whether to -manipulate primary keys on existing tables. Defaults to true -. +manipulate primary keys on existing tables. Defaults to true. -foreignKeys/-fk <true/t | false/f>: Whether to -manipulate foreign keys on existing tables. Defaults to true -. +manipulate foreign keys on existing tables. Defaults to true. -record/-r <true/t | false/f>: Use false to prevent writing the schema changes made by the tool to the current -schema factory -. Defaults to true. +schema +factory. Defaults to true. diff --git a/openjpa-project/src/doc/manual/ref_guide_deploy.xml b/openjpa-project/src/doc/manual/ref_guide_deploy.xml index a7a4b2ea7..70c6ed321 100644 --- a/openjpa-project/src/doc/manual/ref_guide_deploy.xml +++ b/openjpa-project/src/doc/manual/ref_guide_deploy.xml @@ -13,8 +13,8 @@ turn. Factory Deployment -OpenJPA offers several EntityManagerFactory - deployment options. +OpenJPA offers several EntityManagerFactory +deployment options.
@@ -39,12 +39,12 @@ The JPA Overview describes the <classname>javax.persistence.Persistence <classname>Persistence</classname> to add additional <classname> EntityManagerFactory</classname> creation methods. The <classname> org.apache.openjpa.persistence.OpenJPAPersistence</classname> class -<ulink url="../../api/openjpa/persistence/OpenJPAPersistence.html"> Javadoc -</ulink> details these extensions. +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAPersistence.html"> +Javadoc</ulink> details these extensions. </para> <para> -After obtaining the factory, you can cache it for all <phrase><classname> -EntityManager</classname></phrase> creation duties. +After obtaining the factory, you can cache it for all <classname> +EntityManager</classname> creation duties. </para> </section> <section id="ref_guide_deploy_inject"> diff --git a/openjpa-project/src/doc/manual/ref_guide_integration.xml b/openjpa-project/src/doc/manual/ref_guide_integration.xml index f77cea888..08984599c 100644 --- a/openjpa-project/src/doc/manual/ref_guide_integration.xml +++ b/openjpa-project/src/doc/manual/ref_guide_integration.xml @@ -83,7 +83,7 @@ attributes for the <literal>config</literal> tag are defined by the <classname>JDBCConfiguration</classname></ulink> bean methods. Note that excluding the <literal>config</literal> element will cause the Ant task to use the default system configuration mechanism, such as the configuration defined in -the <phrase><filename>org.apache.openjpa.xml</filename></phrase> file. +the <filename>org.apache.openjpa.xml</filename> file. </para> <para> Following is an example of how to use the nested <literal>config</literal> tag diff --git a/openjpa-project/src/doc/manual/ref_guide_intro.xml b/openjpa-project/src/doc/manual/ref_guide_intro.xml index 8ed4ffb4e..9bc4b1639 100644 --- a/openjpa-project/src/doc/manual/ref_guide_intro.xml +++ b/openjpa-project/src/doc/manual/ref_guide_intro.xml @@ -3,22 +3,25 @@ Introduction -OpenJPA JPA is a JDBC-based implementation of the JPA standard. -This document is a reference for the configuration and use of OpenJPA -JPA. +OpenJPA is a JDBC-based implementation of the JPA standard. +This document is a reference for the configuration and use of OpenJPA.
Intended Audience -This document is intended for OpenJPA JPA developers. It +This document is intended for OpenJPA developers. It assumes strong knowledge of Java, familiarity with the eXtensible Markup Language (XML), and an understanding of JPA. If you are not familiar with JPA, please read the JPA Overview before -proceeding. We also strongly recommend taking OpenJPA's hands-on +proceeding. + Certain sections of this guide cover advanced topics such as custom diff --git a/openjpa-project/src/doc/manual/ref_guide_logging.xml b/openjpa-project/src/doc/manual/ref_guide_logging.xml index 7e927d388..979c89b62 100644 --- a/openjpa-project/src/doc/manual/ref_guide_logging.xml +++ b/openjpa-project/src/doc/manual/ref_guide_logging.xml @@ -61,7 +61,7 @@ files the tools are running on. Detailed output is only available via the logging category the tool belongs to, such as openjpa.Enhance for the enhancer (see ) or openjpa.MetaData for the mapping tool (see - ). This logging category +). This logging category is provided so that you can get a general idea of what a tool is doing without having to manipulate logging settings that might also affect runtime behavior. @@ -129,19 +129,6 @@ level at execution time. Information about possible performance concerns will be logged to the INFO level. - - - - - remote - - - log messages - - -openjpa.Remote: Remote connection and execution messages. - - @@ -209,7 +196,7 @@ Pretty-printing properties configuration might look like so: <property name="openjpa.Log" value="SQL=TRACE"/> <property name="openjpa.ConnectionFactoryProperties" - value="MaxActive=100, PrettyPrint=true, PrettyPrintLineLength=72"/> + value="PrettyPrint=true, PrettyPrintLineLength=72"/> @@ -245,8 +232,8 @@ By default, OpenJPA uses a basic logging framework with the following output format: -millislevel [ thread name - ] channel - message +millislevel [thread +name] channel - message For example, when loading an application that uses OpenJPA, a message like the @@ -511,32 +498,28 @@ package com.xyz; import org.apache.openjpa.lib.log.*; public class CustomLogFactory - implements LogFactory -{ + implements LogFactory { + private String _prefix = "CUSTOM LOG"; - public void setPrefix (String prefix) - { + public void setPrefix (String prefix) { _prefix = prefix; } - public Log getLog (String channel) - { + public Log getLog(String channel) { // Return a simple extension of AbstractLog that will log // everything to the System.err stream. Note that this is // roughly equivalent to OpenJPA's default logging behavior. - return new AbstractLog () - { - protected boolean isEnabled (short logLevel) - { + return new AbstractLog() { + + protected boolean isEnabled(short logLevel) { // log all levels return true; } - protected void log (short type, String message, Throwable t) - { + protected void log (short type, String message, Throwable t) { // just send everything to System.err - System.err.println (_prefix + ": " + type + ": " + System.err.println(_prefix + ": " + type + ": " + message + ": " + t); } }; diff --git a/openjpa-project/src/doc/manual/ref_guide_mapping.xml b/openjpa-project/src/doc/manual/ref_guide_mapping.xml index d2c0efc01..4a52b2634 100644 --- a/openjpa-project/src/doc/manual/ref_guide_mapping.xml +++ b/openjpa-project/src/doc/manual/ref_guide_mapping.xml @@ -955,7 +955,7 @@ schema that matches your object model. 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 -. +. @@ -980,7 +980,7 @@ properties (though with different default values). -default: This is an alias for the +default: This is an alias for the org.apache.openjpa.jdbc.meta.MappingDefaultsImpl class. This default implementation is highly configurable. It has the following @@ -2505,14 +2505,14 @@ OpenJPA recognizes the following class extensions. This extension specifies how to eagerly fetch subclass state. It overrides the global -openjpa.jdbc.SubclassFetchMode property. Set the JPA +openjpa.jdbc.SubclassFetchMode property. Set the JPA org.apache.openjpa.persistence.jdbc.SubclassFetchMode annotation to a value from the org.apache.openjpa.persistence.jdbc.EagerFetchType enum: JOIN, PARALLEL, or -NONE. See +NONE. See for a discussion of eager fetching.
@@ -2625,14 +2625,14 @@ OpenJPA recognizes the following field extensions. This extension specifies how to eagerly fetch related objects. It overrides the global -openjpa.jdbc.EagerFetchMode property. Set the JPA +openjpa.jdbc.EagerFetchMode property. Set the JPA org.apache.openjpa.persistence.jdbc.EagerFetchMode annotation to a value from the org.apache.openjpa.persistence.jdbc.EagerFetchType enum: JOIN, PARALLEL, or -NONE. See +NONE. See for a discussion of eager fetching.
@@ -2877,12 +2877,11 @@ concrete strategies in the org.apache.openjpa.jdbc.meta.strats package. -The - +The org.apache.openjpa.persistence.jdbc.Strategy 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 +strategy. You can configure your strategy class' bean properties using OpenJPA's plugin syntax, detailed in . @@ -3028,10 +3027,10 @@ defaults in detail. Your other option is to explicitly install a custom value handler or strategy on a particular field. To do so, specify the full name of your implementation class -in the proper mapping metadata extension. OpenJPA includes the +in the proper mapping metadata extension. OpenJPA includes the org.apache.openjpa.persistence.jdbc.Strategy -annotation. You can configure the named strategy or handler's bean +annotation. You can configure the named strategy or handler's bean properties in these extensions using OpenJPA's plugin format (see ). diff --git a/openjpa-project/src/doc/manual/ref_guide_meta.xml b/openjpa-project/src/doc/manual/ref_guide_meta.xml index 69da20d94..83902b943 100644 --- a/openjpa-project/src/doc/manual/ref_guide_meta.xml +++ b/openjpa-project/src/doc/manual/ref_guide_meta.xml @@ -3,8 +3,8 @@ Metadata -The JPA Overview covers JPA metadata in -. This chapter discusses OpenJPA's extensions to standard JPA metadata. +The JPA Overview covers JPA metadata in . +This chapter discusses OpenJPA's extensions to standard JPA metadata.
@@ -24,14 +24,14 @@ The JPA Overview covers JPA metadata in <xref linkend="jpa_overview_meta"/> <para> The <link linkend="openjpa.MetaDataFactory"><literal>openjpa.MetaDataFactory </literal></link> configuration property controls metadata loading and storing. -This property takes a plugin string (see <xref linkend="ref_guide_conf_plugins"/> -) describing a concrete +This property takes a plugin string (see +<xref linkend="ref_guide_conf_plugins"/>) describing a concrete <ulink url="../apidocs/org/apache/openjpa/meta/MetaDataFactory.html"> <classname>org.apache.openjpa.meta.MetaDataFactory</classname></ulink> implementation. A metadata factory can load mapping information as well as persistence metadata, or it can leave mapping information to a separate <emphasis>mapping factory</emphasis> (see -<xref linkend="ref_guide_mapping_factory"/> ). OpenJPA recognizes the +<xref linkend="ref_guide_mapping_factory"/>). OpenJPA recognizes the following built-in metadata factories: </para> <itemizedlist> @@ -39,17 +39,20 @@ following built-in metadata factories: <para> <literal>jpa</literal>: Standard JPA metadata. This is an alias for the <ulink url="../apidocs/org/apache/openjpa/persistence/PersistenceMetaDataFactory.html"> -<classname> org.apache.openjpa.persistence.PersistenceMetaDataFactory -</classname></ulink>. +<classname> +org.apache.openjpa.persistence.PersistenceMetaDataFactory</classname></ulink>. </para> </listitem> </itemizedlist> <para> -The standard metadata factories all accept the following properties for locating -persistent classes. Each property represents a different mechanism for locating -persistent types; you can choose the mechanism or combination of mechanisms that -are most convenient. See <xref linkend="ref_guide_pc_pcclasses"/> for a -discussion of when it is necessary to list your persistent classes. +JPA has built-in settings for listing your persistent classes, which +the <link linkend="jpa_overview_persistence_xml">JPA Overview</link> describes. +OpenJPA supports these JPA standard settings by translating them into its own +internal metadata factory properties. Each internal property represents a +different mechanism for locating persistent types; you can choose the mechanism +or combination of mechanisms that are most convenient. See +<xref linkend="ref_guide_pc_pcclasses"/> for a discussion of when it is +necessary to list your persistent classes. </para> <itemizedlist> <listitem> @@ -61,22 +64,22 @@ persistent class names. <listitem> <para> <literal>Resources</literal>: A semicolon-separated list of resource paths to -metadata files or jar archives. Each jar archive will be scanned for <phrase> -annotated JPA entities</phrase>. +metadata files or jar archives. Each jar archive will be scanned for +annotated JPA entities. </para> </listitem> <listitem> <para> <literal>URLs</literal>: A semicolon-separated list of URLs of metadata files -or jar archives. Each jar archive will be scanned for <phrase>annotated JPA -entities</phrase>. +or jar archives. Each jar archive will be scanned for annotated JPA +entities. </para> </listitem> <listitem> <para> <literal>ClasspathScan</literal>: A semicolon-separated list of directories or jar archives listed in your classpath. Each directory and jar archive will be -scanned for <phrase>annotated JPA entities</phrase>. +scanned for annotated JPA entities. </para> </listitem> </itemizedlist> @@ -85,7 +88,7 @@ scanned for <phrase>annotated JPA entities</phrase>. Setting a Standard Metadata Factory -<property name="openjpa.MetaDataFactory" value="jpa"/> +<property name="openjpa.MetaDataFactory" value="jpa(ClasspathScan=build;lib.jar)"/> @@ -227,160 +230,6 @@ annotation exists. For example, to denote a persistent java.awt.Point field.
-
- - Persistent Collection Fields - - - - persistent fields - - - collection metadata - - - -JPA standardizes support for collections of entities with the -OneToMany and ManyToMany persistence strategies. -OpenJPA expands collection support to handle collections of simple types -(primitive wrappers, String s, etc), custom types, and -embedded objects. - - -The - -org.apache.openjpa.persistence.PersistentCollection - metadata annotation represents a persistent collection field. It has -the following properties: - - - - -Class elementType: 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. - - - - -FetchType fetch: Whether to load the collection eagerly or -lazily. Corresponds exactly to the same-named property of standard JPA -annotations such as Basic -. Defaults to FetchType.LAZY. - - - - -String mappedBy: Names the field in the related entity that -maps this bidirectional relation. Corresponds to the same-named property of -standard JPA annotations such as - ManyToMany. - - - - -CascadeType[] elementCascade: Array of enum values defining -cascade behavior for the collection elements. Corresponds exactly to the -cascade property of standard JPA annotations such as -ManyToMany -. Defaults to empty array. - - - - -boolean elementEmbedded: Set this property to true - if the elements are stored as embedded objects. - - - - - contains several examples of -using PersistentCollection to mark non-standard -collection fields persistent. - -
-
- - Persistent Map Fields - - - - persistent fields - - - map metadata - - - -JPA has limited support for maps. OpenJPA introduces the - -org.apache.openjpa.persistence.PersistentMap -metadata annotation to represent a persistent map field. It has the following -properties: - - - - -Class keyType: 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. - - - - -Class elementType: 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. - - - - -FetchType fetch: Whether to load the collection eagerly or -lazily. Corresponds exactly to the same-named property of standard JPA -annotations such as Basic -. Defaults to FetchType.LAZY. - - - - -CascadeType[] keyCascade: Array of enum values defining -cascade behavior for the map keys. Corresponds exactly to the cascade - property of standard JPA annotations such as -ManyToOne -. Defaults to empty array. - - - - -CascadeType[] elementCascade: Array of enum values defining -cascade behavior for the map values. Corresponds exactly to the -cascade property of standard JPA annotations such as -ManyToOne -. Defaults to empty array. - - - - -boolean keyEmbedded: Set this property to true - if the map keys are stored as embedded objects. - - - - -boolean elementEmbedded: Set this property to true - if the map values are stored as embedded objects. - - - - -Map keys and values in OpenJPA can be entities, simple types (primitive -wrappers, String s, etc), custom types, or embedded -objects. contains several -examples of using PersistentMap to annotate persistent -map fields. - -
@@ -477,15 +326,6 @@ other properties are ignored. </listitem> <listitem> <para> -<literal>String name</literal>: Place data for instances of the class in a -named cache. By default, instance data is placed in the same cache as superclass -data, or the default cache configured through the -<link linkend="openjpa.DataCache"><literal> openjpa.DataCache</literal></link> -configuration property for base classes. - </para> - </listitem> - <listitem> - <para> <literal>int timeout</literal>: The number of milliseconds data for the class remains valid. Use -1 for no timeout. Defaults to the <link linkend="openjpa.DataCacheTimeout"><literal> openjpa.DataCacheTimeout @@ -669,74 +509,14 @@ annotation in particular. </seealso> </indexterm> <para> -This boolean extension, denoted by <phrase> the JPA +This boolean extension, denoted by the OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname> -org.apache.openjpa.persistence.LRS</classname></ulink> annotation,</phrase> +org.apache.openjpa.persistence.LRS</classname></ulink> annotation, indicates that a field should use OpenJPA's special large result set collection or map proxies. A complete description of large result set proxies is available in <xref linkend="ref_guide_pc_scos_proxy_lrs"/>. </para> </section> - <section id="order-by"> - <title> - Order-By - - - - metadata - - - extensions - - - order-by - - - - The JPA Overview's -describes JPA's OrderBy annotation for loading the elements -of collection fields in a prescribed order. Ordering syntax is as -follows: - - -#element|<field name>[ asc|ascending|desc|descending][, ...] - - -The token #element represents the element value. Simple -element types such as strings and primitive wrappers are sorted based on their -natural ordering. If the collection holds persistent objects, its elements are -sorted based on the natural ordering of the objects' primary key values. By -substituting a field name for the #element token, you can -order a collection of persistent objects by an arbitrary field in the related -type, rather than by primary key. - - -The field name or #element token may be followed by the -keywords asc/ascending or desc/descending -in either all-upper or all-lower case to mandate ascending and descending order. -If the direction is omitted, OpenJPA defaults to ascending order. - - -Note that the defined ordering is only applied when the collection is loaded -from the datastore. It is not maintained by OpenJPA as you modify the collection -in memory. - - -The following ordering string orders a collection by its element values in -descending order: - - -"#element desc" - - -The following ordering string orders a collection of Author - objects by each author's last name in ascending order. If two last -names are equal, the authors are ordered by first name in ascending order. - - -"firstName, lastName" - -
Inverse-Logical @@ -757,10 +537,10 @@ names are equal, the authors are ordered by first name in ascending order. </indexterm> <para> This extension names the inverse field in a logical bidirectional relation. -<phrase> To create a logical bidrectional relation in OpenJPA, use the +To create a logical bidrectional relation in OpenJPA, use the <ulink url="../apidocs/org/apache/openjpa/persistence/InverseLogical.html"> <classname>org.apache.openjpa.persistence.InverseLogical</classname></ulink> -annotation.</phrase> We discuss logical bidirectional relations and this +annotation. We discuss logical bidirectional relations and this extension in detail in <xref linkend="ref_guide_inverses"/>. </para> </section> @@ -798,7 +578,7 @@ existing persistent objects; new object fields are always writeable. To mark a field read-only in JPA metadata, set the <ulink url="../apidocs/org/apache/openjpa/persistence/ReadOnly.html"> <classname>org.apache.openjpa.persistence.ReadOnly</classname></ulink> -annotation to a +annotation to an <ulink url="../apidocs/org/apache/openjpa/persistence/UpdateAction.html"> <classname>org.apache.openjpa.persistence.UpdateAction</classname></ulink> enum value. The <classname>UpdateAction</classname> enum includes: @@ -876,7 +656,7 @@ non-interface, unrecognized field types, which are all assigned level 3 support. <para> With OpenJPA's type family of metadata extensions, you can control the level of support given to your unknown/interface-typed fields. Setting the value of this -extension to <phrase><classname>Entity</classname></phrase> indicates that the +extension to <classname>Entity</classname> indicates that the field value will always be some persistent object, and gives level 2 support. Setting the value of this extension to the class of a concrete persistent type is even better; it gives you level 1 support (just as if you had declared your @@ -934,10 +714,10 @@ org.apache.openjpa.persistence.KeyType</classname></ulink> </seealso> </indexterm> <para> -The <phrase> JPA +The OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html"> <classname>org.apache.openjpa.persistence.Externalizer</classname></ulink> -annotation</phrase> names a method to transform a field value into a value of +annotation names a method to transform a field value into a value of another type. See <xref linkend="ref_guide_pc_extern"/> for details. </para> </section> @@ -960,9 +740,9 @@ another type. See <xref linkend="ref_guide_pc_extern"/> for details. </seealso> </indexterm> <para> -The <phrase> JPA +The OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname> -org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase> +org.apache.openjpa.persistence.Factory</classname></ulink> annotation names a method to re-create a field value from its externalized form. See <xref linkend="ref_guide_pc_extern"/> for details. </para> @@ -986,10 +766,10 @@ names a method to re-create a field value from its externalized form. See </seealso> </indexterm> <para> -The <phrase> JPA +The OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/ExternalValues.html"> <classname>org.apache.openjpa.persistence.ExternalValues</classname></ulink> -annotation</phrase> declares values for transformation of simple fields to +annotation declares values for transformation of simple fields to different constant values in the datastore. See <xref linkend="ref_guide_pc_extern_values"/> for details. </para> @@ -1021,10 +801,6 @@ public class Magazine @Type(int.class) private boolean weekly; - @PersistentCollection - @OrderBy("#element DESC") - private List<String> subtitles; - ... } </programlisting> diff --git a/openjpa-project/src/doc/manual/ref_guide_optimization.xml b/openjpa-project/src/doc/manual/ref_guide_optimization.xml index e528c5a11..94024aea5 100644 --- a/openjpa-project/src/doc/manual/ref_guide_optimization.xml +++ b/openjpa-project/src/doc/manual/ref_guide_optimization.xml @@ -186,12 +186,10 @@ or deletes. flushes during your transaction to reduce its memory requirements. See the Javadoc: - <phrase> - <ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html"> + <ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> OpenJPAEntityManager.setLargeTransaction - </ulink> - </phrase> + </ulink> @@ -203,9 +201,9 @@ If your transaction will visit objects that you know are very unlikely to be accessed by other transactions, for example an exhaustive report run only once a month, you can turn off population of the data cache so that the transaction doesn't fill the entire data cache with objects that won't be accessed again. -Again, see the Javadoc: <phrase> -<ulink url="javadoc/openjpa/persistence/OpenJPAEntityManager.html"> -OpenJPAEntityManager.setPopulateDataCache</ulink></phrase> +Again, see the Javadoc: +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> +OpenJPAEntityManager.setPopulateDataCache</ulink> </para> </entry> </row> diff --git a/openjpa-project/src/doc/manual/ref_guide_pc.xml b/openjpa-project/src/doc/manual/ref_guide_pc.xml index 408f8c508..e7f21f0cc 100644 --- a/openjpa-project/src/doc/manual/ref_guide_pc.xml +++ b/openjpa-project/src/doc/manual/ref_guide_pc.xml @@ -57,14 +57,14 @@ may return incorrect results. <listitem> <para> If you configure OpenJPA to create the needed database schema on startup (see -<xref linkend="ref_guide_mapping_synch"/> ), OpenJPA must know all of your +<xref linkend="ref_guide_mapping_synch"/>), OpenJPA must know all of your persistent classes up-front. </para> </listitem> </itemizedlist> <para> When any of these conditions are a factor in your JPA application, use the -<literal>class</literal>, <literal> mapping-file</literal>, and <literal> +<literal>class</literal>, <literal>mapping-file</literal>, and <literal> jar-file</literal> elements of JPA's standard XML format to list your persistent classes. See <xref linkend="jpa_overview_persistence_xml"/> for details. </para> @@ -101,20 +101,19 @@ persistent classes after you have written them. The enhancer post-processes the bytecode generated by your Java compiler, adding the necessary fields and methods to implement the required persistence features. This bytecode modification perfectly preserves the line numbers in stack traces and is -compatible with Java debuggers. <phrase> In fact, the only change to debugging +compatible with Java debuggers. In fact, the only change to debugging is that the persistent setter and getter methods of entity classes using property access will be prefixed with <literal>pc</literal> in stack traces and step-throughs. For example, if your entity has a <methodname>getId</methodname> method for persistent property <literal>id</literal>, and that method throws an exception, the stack trace will report the exception from method <methodname> pcgetId</methodname>. The line numbers, however, will correctly correspond to -the <methodname>getId</methodname> method in your source file.</phrase> +the <methodname>getId</methodname> method in your source file. </para> <mediaobject> <imageobject> <!-- PNG image data, 509 x 133 (see README) --> <imagedata fileref="img/enhancement.png" width="339px"/> - </imageobject> </mediaobject> <para> @@ -139,13 +138,13 @@ are loaded into the JVM. The following sections describe each option. </indexterm> <para> The enhancer can be invoked at build time -via the Java tool, -<classname>org.apache.openjpa.enhance.PCEnhancer</classname>. +via its Java class, <classname> +org.apache.openjpa.enhance.PCEnhancer</classname>. </para> <note> <para> -You can also enhance via Ant; see <xref linkend="ref_guide_integration_enhance"/> -. +You can also enhance via Ant; see +<xref linkend="ref_guide_integration_enhance"/>. </para> </note> <example id="ref_guide_pc_enhance_enhancer"> @@ -182,8 +181,8 @@ not obeying the restrictions placed on property access. Defaults to false. <literal>-addDefaultConstructor/-adc <true/t | false/f></literal>: The spec requires that all persistent classes define a no-arg constructor. This flag tells the enhancer whether to add a protected no-arg constructor to any -persistent classes that don't already have one. Defaults to <literal>true -</literal>. +persistent classes that don't already have one. Defaults to <literal> +true</literal>. </para> </listitem> <listitem> @@ -218,8 +217,7 @@ The <filename>.class</filename> file of a class. </itemizedlist> <para> If you do not supply any arguments to the enhancer, it will run on the classes -in your persistent class list (see <xref linkend="ref_guide_pc_pcclasses"/> - ). +in your persistent class list (see <xref linkend="ref_guide_pc_pcclasses"/>). </para> <para> You can run the enhancer over classes that have already been enhanced, in which @@ -286,38 +284,30 @@ are invoked prior to your application's <methodname>main</methodname> method. OpenJPA's agent uses JVM hooks to intercept all class loading to enhance classes that have persistence metadata before the JVM loads them. </para> - <note> - <para> -Java agents are new to Java 5; if you are using a previous Java version, you -must use OpenJPA's <link linkend="ref_guide_pc_enhance_build">build-time -enhancement</link> option. - </para> - </note> <para> Searching for metadata for every class loaded by the JVM can slow application initialization. One way to speed things up is to take advantage of the optional -persistent class list described in <xref linkend="ref_guide_pc_pcclasses"/> -. If you declare a persistent class list, OpenJPA will only search for +persistent class list described in <xref linkend="ref_guide_pc_pcclasses"/>. If +you declare a persistent class list, OpenJPA will only search for metadata for classes in that list. </para> <para> To employ the OpenJPA agent, invoke <literal>java</literal> with the <literal> --javaagent</literal> set to the path to your <filename>org.apache.openjpa.jar -</filename> or <filename>openjpa-runtime.jar</filename> file. +-javaagent</literal> set to the path to your OpenJPA jar file. </para> <example id="ref_guide_pc_enhance_runtime_ex"> <title> Using the OpenJPA Agent for Runtime Enhancement -java -javaagent:/home/dev/openjpa/lib/org.apache.openjpa.jar com.xyz.Main +java -javaagent:/home/dev/openjpa/lib/openjpa.jar com.xyz.Main You can pass settings to the agent using OpenJPA's plugin syntax (see - ). The agent accepts the long -form of any of the standard configuration options ( - ). It also accepts the following +). The agent accepts the long +form of any of the standard configuration options +( ). It also accepts the following options, the first three of which correspond exactly to to the same-named options of the enhancer tool described in : @@ -330,11 +320,6 @@ options of the enhancer tool described in -jdoEnhance - - - - enforcePropertyRestrictions @@ -353,7 +338,7 @@ accordingly. This may slow down class load times significantly. Passing Options to the OpenJPA Agent -java -javaagent:/home/dev/openjpa/lib/org.apache.openjpa.jar=jdoEnhance=true,addDefaultConstructor=false com.xyz.Main +java -javaagent:/home/dev/openjpa/lib/openjpa.jar=addDefaultConstructor=false com.xyz.Main
@@ -420,7 +405,7 @@ described in of the JPA Overview. To retrieve the identity value of a datastore identity entity, use the -OpenJPAEntityManager.getObjectId (Object entity) +OpenJPAEntityManager.getObjectId(Object entity) method. See for more information on the OpenJPAEntityManager. @@ -433,8 +418,8 @@ import org.apache.openjpa.persistence.*; @Entity @DataStoreId -public class LineItem -{ +public class LineItem { + ... no @Id fields declared ... } @@ -491,7 +476,7 @@ record. If you choose to use application identity, you may want to take advantage of -OpenJPA JPA's application identity tool. The application +OpenJPA's application identity tool. The application identity tool generates Java code implementing the identity class for any persistent type using application identity. The code satisfies all the requirements the specification places on identity classes. You can use it as-is, @@ -513,7 +498,7 @@ generated identity class. Once the application identity tool has generated the class code, you can set the @IdClass annotation. -The application identity tool can be invoked via the Java class, +The application identity tool can be invoked via its Java class, org.apache.openjpa.enhance.ApplicationIdTool. @@ -534,7 +519,7 @@ java org.apache.openjpa.enhance.ApplicationIdTool -s Id Magazine.java The application identity tool accepts the standard set of command-line arguments defined by the configuration framework (see - ), including code formatting +), including code formatting flags described in . It also accepts the following arguments: @@ -605,8 +590,7 @@ The .class file of a persistent class. If you do not supply any arguments to the tool, it will act on the classes in -your persistent classes list (see -). +your persistent classes list (see ).
@@ -666,14 +650,6 @@ non-primary key auto-increment columns, and may allow more than one per table. See your database documentation for details. - - -Statements inserting into tables with auto-increment / identity columns cannot -be batched. After each insert, OpenJPA must go back to the database to retrieve -the last inserted auto-increment value to set back in the persistent object. -This can have a negative impact on performance. - -
@@ -696,11 +672,10 @@ use the mappedBy annotation attribute to form bidirectional relations that also share datastore storage in JPA. -OpenJPA also allows you to define purely logical bidirectional relations. - The +OpenJPA also allows you to define purely logical bidirectional relations. The org.apache.openjpa.persistence.InverseLogical -annotation names a logical inverse in JPA metadata. +annotation names a logical inverse in JPA metadata. @@ -717,8 +692,8 @@ inverse of both fields. import org.apache.openjpa.persistence.*; @Entity -public class Magazine -{ +public class Magazine { + @OneToOne private Photograph coverPhoto; @@ -726,26 +701,14 @@ public class Magazine } @Entity -public class Photograph -{ +public class Photograph { + @OneToOne @InverseLogical("coverPhoto") private Magazine mag; ... } -</programlisting> -<programlisting> -<class name="Magazine"> - <field name="coverPhoto"/> - ... -</class> -<class name="Photograph"> - <field name="mag"> - <extension vendor-name="openjpa" key="inverse-logical" value="coverPhoto"/> - </field> - ... -</class> </programlisting> </example> <para> @@ -878,19 +841,18 @@ employeesBySal</literal> and <literal>departments</literal> are persistent fields in the class below. </para> <programlisting> -public class Company -{ +public class Company { + // OpenJPA will detect the custom comparator in the initial field value // and use it whenever loading data from the database into this field - private Collection employeesBySal = new TreeSet (new SalaryComparator ()); + private Collection employeesBySal = new TreeSet(new SalaryComparator()); private Map departments; - public Company - { + public Company { // or we can initialize fields in our no-args constructor; even though - // this field is declared type Map, OpenJPA will detect that it's actually - // a TreeMap and use natural ordering for loaded data - departments = new TreeMap (); + // this field is declared type Map, OpenJPA will detect that it's + // actually a TreeMap and use natural ordering for loaded data + departments = new TreeMap(); } // rest of class definition... @@ -978,7 +940,7 @@ OpenJPA smart proxies by using fields of type <classname>java.util.Set </classname>, <classname>java.util.TreeSet</classname>, and <classname> java.util.HashSet</classname> for your collections whenever possible. Smart proxies for these types are more efficient than proxies for <classname>List -</classname> s. You can also design your own smart proxies to further optimize +</classname>s. You can also design your own smart proxies to further optimize OpenJPA for your usage patterns. See the section on <link linkend="ref_guide_pc_scos_proxy_custom">custom proxies</link> for details. @@ -1019,7 +981,7 @@ large result set collection will perform a <literal> SELECT COUNT(*)</literal> query with the proper <literal>WHERE</literal> conditions to find out if the given element exists in the database's record of the collection. Similarly, each time you obtain an iterator OpenJPA performs the proper query using the current -<link linkend="ref_guide_dbsetup_lrs"> large result set settings</link>, as +<link linkend="ref_guide_dbsetup_lrs">large result set settings</link>, as discussed in the <link linkend="ref_guide_dbsetup">JDBC</link> chapter. As you invoke <methodname>Iterator.next</methodname>, OpenJPA instantiates the result objects on-demand. @@ -1038,11 +1000,11 @@ import org.apache.openjpa.persistence.*; ... -Collection employees = company.getEmployees (); // employees is a lrs collection -Iterator itr = employees.iterator (); -while (itr.hasNext ()) - process ((Employee) itr.next ()); -OpenJPAPersistence.close (itr); +Collection employees = company.getEmployees(); // employees is a lrs collection +Iterator itr = employees.iterator(); +while (itr.hasNext()) + process((Employee) itr.next()); +OpenJPAPersistence.close(itr); </programlisting> </example> <para> @@ -1052,10 +1014,10 @@ which it uses to make sure the proper results are always returned from collection and map methods, and to update the field's database record on commit. </para> <para> -<phrase> In order to use large result set proxies in JPA, add the +In order to use large result set proxies in JPA, add the <ulink url="../apidocs/org/apache/openjpa/persistence/LRS.html"><classname> org.apache.openjpa.persistence.LRS</classname></ulink> annotation to the -persistent field.</phrase> +persistent field. </para> <para> The following restrictions apply to large result set fields: @@ -1071,8 +1033,8 @@ concrete collection or map class. </listitem> <listitem> <para> -The field cannot have an externalizer (see <xref linkend="ref_guide_pc_extern"/> - ). +The field cannot have an externalizer (see +<xref linkend="ref_guide_pc_extern"/>). </para> </listitem> <listitem> @@ -1082,9 +1044,9 @@ cannot be transferred from one persistent field to another. The following code would result in an error on commit: </para> <programlisting> -Collection employees = company.getEmployees () // employees is a lrs collection -company.setEmployees (null); -anotherCompany.setEmployees (employees); +Collection employees = company.getEmployees() // employees is a lrs collection +company.setEmployees(null); +anotherCompany.setEmployees(employees); </programlisting> </listitem> </itemizedlist> @@ -1096,8 +1058,8 @@ anotherCompany.setEmployees (employees); import org.apache.openjpa.persistence.*; @Entity -public class Company -{ +public class Company { + @ManyToMany @LRS private Collection<Employee> employees; @@ -1132,7 +1094,7 @@ OpenJPA manages proxies through the org.apache.openjpa.util.ProxyManager</classname></ulink> interface. OpenJPA includes a default proxy manager, the <classname> org.apache.openjpa.util.ProxyManagerImpl</classname> (with a plugin alias name -of <literal>default</literal> ), that will meet the needs of most users. The +of <literal>default</literal>), that will meet the needs of most users. The default proxy manager understands the following configuration properties: </para> <itemizedlist> @@ -1203,10 +1165,10 @@ JPA cannot have externalizers. </para> </note> <para> -The <phrase> JPA +The OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/Externalizer.html"> <classname>org.apache.openjpa.persistence.Externalizer</classname></ulink> -annotation</phrase> sets the name of a method that will be invoked to convert +annotation sets the name of a method that will be invoked to convert the field into its external form for database storage. You can specify either the name of a non-static method, which will be invoked on the field value, or a static method, which will be invoked with the field value as a parameter. Each @@ -1235,10 +1197,10 @@ their corresponding metadata extensions. <thead> <row> <entry colname="method"> - Method +Method </entry> <entry colname="extension"> - Extension +Extension </entry> </row> </thead> @@ -1246,64 +1208,48 @@ their corresponding metadata extensions. <row> <entry colname="method"> <literal> - - public String CustomType.toString() - +public String CustomType.toString() </literal> </entry> <entry colname="extension"> <literal> - - @Externalizer("toString") - +@Externalizer("toString") </literal> </entry> </row> <row> <entry colname="method"> <literal> - - public String CustomType.toString(StoreContext ctx) - +public String CustomType.toString(StoreContext ctx) </literal> </entry> <entry colname="extension"> <literal> - - @Externalizer("toString") - +@Externalizer("toString") </literal> </entry> </row> <row> <entry colname="method"> <literal> - - public static String AnyClass.toString(CustomType ct) - +public static String AnyClass.toString(CustomType ct) </literal> </entry> <entry colname="extension"> <literal> - - @Externalizer("AnyClass.toString") - +@Externalizer("AnyClass.toString") </literal> </entry> </row> <row> <entry colname="method"> <literal> - - public static String AnyClass.toString(CustomType ct, StoreContext ctx) - +public static String AnyClass.toString(CustomType ct, StoreContext ctx) </literal> </entry> <entry colname="extension"> <literal> - - @Externalizer("AnyClass.toString") - +@Externalizer("AnyClass.toString") </literal> </entry> </row> @@ -1311,9 +1257,9 @@ their corresponding metadata extensions. </tgroup> </table> <para> -The <phrase> JPA +The OpenJPA <ulink url="../apidocs/org/apache/openjpa/persistence/Factory.html"><classname> -org.apache.openjpa.persistence.Factory</classname></ulink> annotation</phrase> +org.apache.openjpa.persistence.Factory</classname></ulink> annotation contains the name of a method that will be invoked to instantiate the field from the external form stored in the database. Specify a static method name. The method will will be invoked with the externalized value and must return an @@ -1335,16 +1281,14 @@ corresponding metadata extensions. - - - Method +Method - Extension +Extension @@ -1352,78 +1296,58 @@ corresponding metadata extensions. - - public CustomType(String str) - +public CustomType(String str) - - none - +none - - public static CustomType CustomType.fromString(String str) - +public static CustomType CustomType.fromString(String str) - - @Factory("fromString") - +@Factory("fromString") - - public static CustomType CustomType.fromString(String str, StoreContext ctx) - +public static CustomType CustomType.fromString(String str, StoreContext ctx) - - @Factory("fromString") - +@Factory("fromString") - - public static CustomType AnyClass.fromString(String str) - +public static CustomType AnyClass.fromString(String str) - - @Factory("AnyClass.fromString") - +@Factory("AnyClass.fromString") - - public static CustomType AnyClass.fromString(String str, StoreContext ctx) - +public static CustomType AnyClass.fromString(String str, StoreContext ctx) - - @Factory("AnyClass.fromString") - +@Factory("AnyClass.fromString") @@ -1432,24 +1356,19 @@ corresponding metadata extensions. If your externalized field is not a standard persistent type, you must -explicitly mark it persistent. In JPA, you can force a persistent field +explicitly mark it persistent. In OpenJPA, you can force a persistent field by annotating it with org.apache.openjpa.persistence.Persistent annotation. - If your custom field type is mutable and is not a standard collection, map, or date class, OpenJPA will not be able to detect changes to the field. You must -mark the field dirty manully, or create a custom field proxy. - - - See - +mark the field dirty manually, or create a custom field proxy. +See + OpenJPAEntityManager.dirty for how to mark a -field dirty manually in JPA. - - +field dirty manually in JPA. See for a discussion of proxies. @@ -1458,13 +1377,13 @@ You can externalize a field to virtually any value that is supported by OpenJPA's field mappings (embedded relations are the exception; you must declare your field to be a persistence-capable type in order to embed it). This means that a field can externalize to something as simple as a primitive, something as -complex as a collection or map of persistence-capable objects, or anything in +complex as a collection or map of entities, or anything in between. If you do choose to externalize to a collection or map, OpenJPA recognizes a family of metadata extensions for specying type information for the externalized form of your fields - see . If the -external form of your field is a persistence-capable object, or contains -persistence-capable objects, OpenJPA will correctly include the objects in its -persistence-by-reachability algorithms and its delete-dependent algorithms. +external form of your field is an entity object or contains entities, OpenJPA +will correctly include the objects in its persistence-by-reachability +algorithms and its delete-dependent algorithms. The example below demonstrates a few forms of externalization. @@ -1477,8 +1396,8 @@ The example below demonstrates a few forms of externalization. import org.apache.openjpa.persistence.*; @Entity -public class Magazine -{ +public class Magazine { + // use Class.getName and Class.forName to go to/from strings @Persistent @Externalizer("getName") @@ -1491,22 +1410,19 @@ public class Magazine @Externalizer("toExternalForm") private URL url; - // use our custom methods; notice how we use the KeyType and ElementType - // annotations to specify the metadata for our externalized map + // use our custom methods @Persistent - @Externalizer("Magazine.mapFromCustomType") - @Factory("Magazine.mapToCustomType") - @KeyType(String.class) @ElementType(String.class) + @Externalizer("Magazine.authorsFromCustomType") + @Factory("Magazine.authorsToCustomType") + @ElementType(Author.class) private CustomType customType; - public static Map mapFromCustomType (CustomType customType) - { - ... logic to pack custom type into a map ... + public static Collection authorsFromCustomType(CustomType customType) { + ... logic to pack custom type into a list of authors ... } - public static CustomType mapToCustomType (Map map) - { - ... logic to create custom type from a map ... + public static CustomType authorsToCustomType (Collection authors) { + ... logic to create custom type from a collection of authors ... } ... @@ -1545,13 +1461,13 @@ previous example. // you can query using parameters -Query q = em.createQuery ("select m from Magazine m where m.url = :u"); -q.setParameter ("u", new URL ("http://www.solarmetric.com")); -List results = q.getResultList (); +Query q = em.createQuery("select m from Magazine m where m.url = :u"); +q.setParameter("u", new URL("http://www.solarmetric.com")); +List results = q.getResultList(); // or as a shortcut, you can use the externalized form directly -q = em.createQuery ("select m from Magazine m where m.url = 'http://www.solarmetric.com'"); -results = q.getResultList (); +q = em.createQuery("select m from Magazine m where m.url = 'http://www.solarmetric.com'"); +results = q.getResultList();
@@ -1581,10 +1497,10 @@ External values supports translation of pre-defined simple types (primitives, primitive wrappers, and Strings), to other pre-defined simple values. -Use the JPA +Use the OpenJPA org.apache.openjpa.persistence.ExternalValues -annotation to define external value translations. The values are +annotation to define external value translations. The values are defined in a format similar to that of configuration plugins, except that the value pairs represent Java and datastore values. To convert the Java boolean values of true @@ -1594,9 +1510,9 @@ true=T,false=F. If the type of the datastore value is different from the field's type, use the - JPA + org.apache.openjpa.persistence.Type annotation - to define the datastore type. +to define the datastore type. @@ -1607,8 +1523,8 @@ This example uses external value translation to transform a string field to an integer in the database. </para> <programlisting> -public class Magazine -{ +public class Magazine { + @ExternalValues({"SMALL=5", "MEDIUM=8", "LARGE=10"}) @Type(int.class) private String sizeWidth; @@ -1746,8 +1662,7 @@ import org.apache.openjpa.persistence.*; }), ... }) -public class Magazine -{ +public class Magazine { ... } </programlisting> @@ -1787,8 +1702,8 @@ import org.apache.openjpa.persistence.*; }), ... }) -public class Magazine -{ +public class Magazine { + @ManyToOne(fetch=FetchType.LAZY) @LoadFetchGroup("detail") private Publisher publisher; @@ -1844,25 +1759,25 @@ the fetch depth to something less than the configured maximum. OpenJPA's <classname>OpenJPAEntityManager</classname> and <classname> OpenJPAQuery</classname> extensions to the standard <classname>EntityManager </classname> and <classname>Query</classname> interfaces provide access to a -<ulink url="../../api/openjpa/persistence/FetchPlan.html"><classname> -org.apache.openjpa.persistence.FetchPlan</classname></ulink> object. The -<classname>FetchPlan</classname> maintains the set of active fetch groups and -the maximum fetch depth. It begins with the groups and depth defined in the +<ulink url="../apidocs/org/apache/openjpa/persistence/FetchPlan.html"> +<classname>org.apache.openjpa.persistence.FetchPlan</classname></ulink> object. +The <classname>FetchPlan</classname> maintains the set of active fetch groups +and the maximum fetch depth. It begins with the groups and depth defined in the <literal>openjpa.FetchGroups</literal> and <literal>openjpa.MaxFetchDepth </literal> properties, but allows you to add or remove groups and change the maximum fetch depth for an individual <classname>EntityManager</classname> or <classname>Query</classname> through the methods below. </para> <programlisting> -public FetchPlan addFetchGroup (String group); -public FetchPlan addFetchGroups (String... groups); -public FetchPlan addFetchGroups (Collection groups); -public FetchPlan removeFetchGroup (String group); -public FetchPlan removeFetchGroups (String... groups); -public FetchPlan removeFetchGroups (Collection groups); -public FetchPlan resetFetchGroups (); -public Collection<String> getFetchGroups (); -public void clearFetchGroups (); +public FetchPlan addFetchGroup(String group); +public FetchPlan addFetchGroups(String... groups); +public FetchPlan addFetchGroups(Collection groups); +public FetchPlan removeFetchGrop(String group); +public FetchPlan removeFetchGroups(String... groups); +public FetchPlan removeFetchGroups(Collection groups); +public FetchPlan resetFetchGroups(); +public Collection<String> getFetchGroups(); +public void clearFetchGroups(); public FetchPlan setMaxFetchDepth(int depth); public int getMaxFetchDepth(); </programlisting> @@ -1880,9 +1795,9 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAQuery kq = OpenJPAPersistence.cast (em.createQuery (...)); -kq.getFetchPlan ().setMaxFetchDepth(3).addFetchGroup ("detail"); -List results = kq.getResultList (); +OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...)); +kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail"); +List results = kq.getResultList(); </programlisting> </example> </section> @@ -1909,18 +1824,18 @@ fields that will be eagerly loaded from the database. JPA <classname>FetchPlan</classname> methods: </para> <programlisting> -public FetchPlan addField (String field); -public FetchPlan addFields (String... fields); -public FetchPlan addFields (Class cls, String... fields); -public FetchPlan addFields (Collection fields); -public FetchPlan addFields (Class cls, Collection fields); -public FetchPlan removeField (String field); -public FetchPlan removeFields (String... fields); -public FetchPlan removeFields (Class cls, String... fields); -public FetchPlan removeFields (Collection fields); -public FetchPlan removeFields (Class cls, Collection fields); -public Collection<String> getFields (); -public void clearFields (); +public FetchPlan addField(String field); +public FetchPlan addFields(String... fields); +public FetchPlan addFields(Class cls, String... fields); +public FetchPlan addFields(Collection fields); +public FetchPlan addFields(Class cls, Collection fields); +public FetchPlan removeField(String field); +public FetchPlan removeFields(String... fields); +public FetchPlan removeFields(Class cls, String... fields); +public FetchPlan removeFields(Collection fields); +public FetchPlan removeFields(Class cls, Collection fields); +public Collection<String> getFields(); +public void clearFields(); </programlisting> <para> The methods that take only string arguments use the fully-qualified field name, @@ -1952,9 +1867,9 @@ import org.apache.openjpa.persistence.*; ... -OpenJPAEntityManager kem = OpenJPAPersistence.cast (em); -kem.getFetchPlan ().addField (Magazine.class, "publisher"); -Magazine mag = em.find (Magazine.class, magId); +OpenJPAEntityManager kem = OpenJPAPersistence.cast(em); +kem.getFetchPlan().addField(Magazine.class, "publisher"); +Magazine mag = em.find(Magazine.class, magId); </programlisting> </example> </section> @@ -2100,13 +2015,12 @@ but they can spawn recursive to-one joins. <para> Under the <literal>join</literal> subclass fetch mode, subclass data in joined tables is selected by outer joining to all possible subclass tables of the type -being queried. Unjoined subclass data is selected with a SQL UNION where -possible. As you'll see below, subclass data fetching is configured separately -from relation fetching, and can be disabled for specific classes. +being queried. As you'll see below, subclass data fetching is configured +separately from relation fetching, and can be disabled for specific classes. </para> <note> <para> -Some databases may not support UNIONs or outer joins. Also, OpenJPA can not use +Some databases may not support outer joins. Also, OpenJPA can not use outer joins if you have set the <link linkend="openjpa.jdbc.DBDictionary"> <literal> DBDictionary</literal></link>'s <literal>JoinSyntax</literal> to <literal>traditional</literal>. See <xref linkend="ref_guide_dbsetup_sql92"/>. @@ -2155,16 +2069,8 @@ relations to use parallel rather than join mode eager fetching using the metadata extension described in <xref linkend="eager-fetch-mode"/>. </para> <para> -Setting your subclass fetch mode to <literal>parallel</literal> affects -table-per-class and vertical inheritance hierarchies. Under parallel mode, -OpenJPA issues separate selects for each subclass in a table-per-class -inheritance hierarchy, rather than UNIONing all subclass tables together as in -join mode. This applies to any operation on a table-per-class base class: query, -by-id lookup, or relation traversal. - </para> - <para> -When dealing with a vertically-mapped hierarchy, on the other hand, parallel -subclass fetch mode only applies to queries. Rather than outer-joining to +Parallel subclass fetch mode only applies to queries on joined inheritance +hierarchies. Rather than outer-joining to subclass tables, OpenJPA will issue the query separately for each subclass. In all other situations, parallel subclass fetch mode acts just like join mode in regards to vertically-mapped subclasses. @@ -2253,12 +2159,12 @@ import org.apache.openjpa.persistence.jdbc.*; ... -Query q = em.createQuery ("select p from Person p where p.address.state = 'TX'"); -OpenJPAQuery kq = OpenJPAPersistence.cast (q); -JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan (); -fetch.setEagerFetchMode (JDBCFetchPlan.EAGER_PARALLEL); -fetch.setSubclassFetchMode (JDBCFetchPlan.EAGER_JOIN); -List results = q.getResultList (); +Query q = em.createQuery("select p from Person p where p.address.state = 'TX'"); +OpenJPAQuery kq = OpenJPAPersistence.cast(q); +JDBCFetchPlan fetch = (JDBCFetchPlan) kq.getFetchPlan(); +fetch.setEagerFetchMode(JDBCFetchPlan.EAGER_PARALLEL); +fetch.setSubclassFetchMode(JDBCFetchPlan.EAGER_JOIN); +List results = q.getResultList(); </programlisting> </example> <para> @@ -2270,7 +2176,7 @@ subclass data fetching will take place, regardless of your metadata setting. </para> <para> This applies to the eager fetch mode metadata extension as well (see -<xref linkend="eager-fetch-mode"/> ). You can use this extension to +<xref linkend="eager-fetch-mode"/>). You can use this extension to disable eager fetching on a field or to declare that a collection would rather use joins than parallel selects or vice versa. But an extension value of <literal>join</literal> won't cause any eager joining if the fetch diff --git a/openjpa-project/src/doc/manual/ref_guide_remote.xml b/openjpa-project/src/doc/manual/ref_guide_remote.xml index bb215cb3f..001a47dde 100644 --- a/openjpa-project/src/doc/manual/ref_guide_remote.xml +++ b/openjpa-project/src/doc/manual/ref_guide_remote.xml @@ -73,7 +73,7 @@ In JPA, objects detach automatically when they are serialized or when a <link linkend="jpa_overview_emfactory_perscontext">persistence context</link> ends. The specification does not define any way to explicitly detach objects. The extended -<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> <classname>OpenJPAEntityManager</classname></ulink>, however, allows you to explicitly detach objects at any time. </para> @@ -111,8 +111,8 @@ your objects. Setting the <literal>RollbackOnly</literal> flag prevents OpenJPA from flushing when detaching dirty objects; instead OpenJPA just runs its pre-flush actions (see the <methodname>OpenJPAEntityManager.preFlush </methodname> -<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> Javadoc -</ulink> for details). +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> +Javadoc</ulink> for details). </para> <para> This allows you to use the same instances in multiple @@ -152,7 +152,7 @@ attached instance's corresponding fields to null. </listitem> <listitem> <para> -If the instance has <phrase> a <literal>Version</literal> field,</phrase> +If the instance has a <literal>Version</literal> field, OpenJPA will consider the object detached if the version field has a non-default value, and new otherwise. </para> @@ -322,7 +322,7 @@ use detached state managers, as determined by the settings above. <para> You can also alter the set of fields that will be included in the detached graph at runtime. -<ulink url="../../api/openjpa/persistence/OpenJPAEntityManager.html"> +<ulink url="../apidocs/org/apache/openjpa/persistence/OpenJPAEntityManager.html"> <classname>OpenJPAEntityManager</classname></ulink>s expose the following APIs for controlling detached state: </para> diff --git a/openjpa-project/src/doc/manual/ref_guide_runtime.xml b/openjpa-project/src/doc/manual/ref_guide_runtime.xml index dc42272ae..bb47340c0 100644 --- a/openjpa-project/src/doc/manual/ref_guide_runtime.xml +++ b/openjpa-project/src/doc/manual/ref_guide_runtime.xml @@ -3,7 +3,7 @@ Runtime Extensions -This chapter describes OpenJPA extensions to the standard JPA +This chapter describes OpenJPA extensions to the standard JPA interfaces, and outlines some additional features of the OpenJPA runtime.
@@ -17,7 +17,7 @@ and JDO are simply different "personalities" that can OpenJPA's native kernel can adopt. -As a OpenJPA JPA user, you will not normally see beneath +As a OpenJPA user, you will not normally see beneath OpenJPA's JPA personality. OpenJPA allows you to access its feature set without leaving the comfort of JPA. Where OpenJPA goes beyond standard JPA functionality, we have crafted JPA-specific APIs to each OpenJPA extension for @@ -190,7 +190,7 @@ features. The OpenJPAEntityManagerFactory offers APIs to obtain managed and unmanaged EntityManagers from the same factory, to access the OpenJPA data and query caches, and to perform other OpenJPA-specific operations. See the - + interface Javadoc for details.
@@ -216,7 +216,7 @@ interface Javadoc for details. All OpenJPA EntityManagers implement the - + org.apache.openjpa.persistence.OpenJPAEntityManager interface. This interface extends the standard javax.persistence.EntityManager. Just as the standard @@ -249,7 +249,7 @@ extensions this interface contains. OpenJPA extends JPA's standard query functionality with the org.apache.openjpa.persistence.OpenJPAQuery interface. See its -Javadoc for +Javadoc for details on the convenience methods it provides.
@@ -276,7 +276,7 @@ details on the convenience methods it provides. An Extent is a logical view of all persistent instances of a given entity class, possibly including subclasses. OpenJPA adds the - + org.apache.openjpa.persistence.Extent class to the set of Java Persistence APIs. The following code illustrates iterating over all instances of the Magazine entity, without subclasses: @@ -310,8 +310,8 @@ for (Magazine m : mags) In addition to the EntityManager object cache mandated by the JPA specification, OpenJPA includes a flexible datastore-level cache. You can access this cache from your JPA code using the - -org.apache.openjpa.persistence.StoreCache facade. + +org.apache.openjpa.persistence.StoreCache facade. has detailed information on OpenJPA's data caching system, including the StoreCache facade. @@ -327,9 +327,9 @@ data caching system, including the StoreCache facade. OpenJPA can cache query results as well as persistent object data. The - -org.apache.openjpa.persistence.QueryResultCache is an -JPA-flavored facade to OpenJPA's internal query cache. See + +org.apache.openjpa.persistence.QueryResultCache +is an JPA-flavored facade to OpenJPA's internal query cache. See for details on query caching in OpenJPA. @@ -361,10 +361,10 @@ groups, and lock levels. OpenJPA goes one step further, extending FetchPlan with - -org.apache.openjpa.persistence.jdbc.JDBCFetchPlan to add -additional JDBC-specific tuning methods. Unless you have customized OpenJPA to -use a non-relational back-end (see + +org.apache.openjpa.persistence.jdbc.JDBCFetchPlan +to add additional JDBC-specific tuning methods. Unless you have customized +OpenJPA to use a non-relational back-end (see ), all FetchPlans in OpenJPA implement JDBCFetchPlan , so feel free to cast to this interface. @@ -397,10 +397,10 @@ FetchPlan s. - -org.apache.openjpa.persistence.OpenJPAPersistence is a -static helper class that adds OpenJPA-specific utility methods to -javax.persistence.Persistence. + +org.apache.openjpa.persistence.OpenJPAPersistence +is a static helper class that adds OpenJPA-specific utility methods to +javax.persistence.Persistence. @@ -586,7 +586,7 @@ In addition to the standard EntityManager.lock (Object, LockModeType) method, the - + OpenJPAEntityManager exposes the following methods to lock objects explicitly: @@ -879,9 +879,9 @@ changes. This chapter describes how to use and configure OpenJPA savepoints. Using Savepoints -OpenJPA's - -OpenJPAEntityManager have the following +OpenJPA's + +OpenJPAEntityManager have the following methods to control savepoint behavior. Note that the savepoints work in tandem with the current transaction. This means that savepoints require an open transaction, and that a rollback of the transaction will rollback all of the @@ -958,7 +958,8 @@ kem.getTransaction ().commit (); Configuring Savepoints -OpenJPA uses the +OpenJPA uses the + org.apache.openjpa.kernel.SavepointManager plugin to handle perserving the savepoint state. OpenJPA includes the following SavepointManager @@ -1199,8 +1200,8 @@ registration for very specific extensions that do not apply globally. See the OpenJPAQuery -Javadoc for -details. + +Javadoc for details. @@ -1267,8 +1268,8 @@ registration for very specific aggregates that do not apply globally. See the OpenJPAQuery -Javadoc for -details. + +Javadoc for details. @@ -1687,7 +1688,8 @@ OpenJPA allows you to access named generators at runtime through the public Generator getNamedGenerator (String name); -The returned +The returned + org.apache.openjpa.persistence.Generator is a facade over an internal OpenJPA Seq. @@ -1697,8 +1699,8 @@ retrieve the identity generator of any class, or the generator of any field. With these APIs, you do not have to know the generator name. Additionally, they allow you to access the implicit generator used by default for datastore identity classes. See the - Javadoc - for the OpenJPAEntityManager.getIdentityGenerator + +Javadoc for the OpenJPAEntityManager.getIdentityGenerator and OpenJPAEntityManager.getFieldGenerator methods for API details. diff --git a/openjpa-project/src/doc/manual/supported_databases.xml b/openjpa-project/src/doc/manual/supported_databases.xml index 400ec97f3..1d88529c5 100644 --- a/openjpa-project/src/doc/manual/supported_databases.xml +++ b/openjpa-project/src/doc/manual/supported_databases.xml @@ -4,7 +4,7 @@ Following is a table of the database and JDBC driver versions that are supported -by OpenJPA JPA. +by OpenJPA. @@ -326,10 +326,7 @@ datastore transactions cannot use the pessimistic lock manager. <listitem> <para> Interbase does not support the <literal>LOWER</literal>, <literal>SUBSTRING -</literal>, or <literal>INSTR</literal> SQL functions, which means that -<methodname>toLowerCase()</methodname>, <methodname>indexOf()</methodname>, and -<methodname>substring()</methodname> methods in <phrase>JPA</phrase> QL cannot -be used. +</literal>, or <literal>INSTR</literal> SQL functions> </para> </listitem> </itemizedlist> @@ -482,10 +479,7 @@ Firebird does not support auto-increment columns. <listitem> <para> Firebird does not support the <literal>LOWER</literal>, <literal>SUBSTRING -</literal>, or <literal>INSTR</literal> SQL functions, which means that -<methodname>toLowerCase()</methodname>, <methodname>indexOf()</methodname>, and -<methodname>substring()</methodname> methods in <phrase>JPA</phrase> QL cannot -be used. +</literal>, or <literal>INSTR</literal> SQL functions. </para> </listitem> </itemizedlist>