Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_optimization.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_optimization.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_optimization.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,509 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 15. Optimization Guidelines</title><base
href="display"><link rel="stylesheet" type="text/css"
href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets
V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's
Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference
Guide"><link rel="prev" href="ref_guide_integration_dbcp.html" title="2.
Apache Commons DBCP"><link rel="next" href="ref_guide_instrumentation.html"
title="Chapter 16. Instrumentation"></head><body bgcolor="white"
text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div
class="navheader"><table width="100%" summary="Navigation header"><tr><th
colspan="3" align="center">Chapter 15.
+ Optimization Guidelines
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="ref_guide_integration_dbcp.html">Prev</a> </td><th width="60%"
align="center">Part 3. Reference Guide</th><td width="20%"
align="right"> <a accesskey="n"
href="ref_guide_instrumentation.html">Next</a></td></tr></table><hr></div><div
class="chapter" id="ref_guide_optimization"><div
class="titlepage"><div><div><h2 class="title">Chapter 15.
+ Optimization Guidelines
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e17293"></a>
+ <p>
+There are numerous techniques you can use in order to ensure that OpenJPA
+operates in the fastest and most efficient manner. Following are some
+guidelines. Each describes what impact it will have on performance and
+scalability. Note that general guidelines regarding performance or scalability
+issues are just that - guidelines. Depending on the particular characteristics
+of your application, the optimal settings may be considerably different than
+what is outlined below.
+ </p>
+ <p>
+In the following table, each row is labeled with a list of italicized keywords.
+These keywords identify what characteristics the row in question may improve
+upon. Many of the rows are marked with one or both of the <span
class="emphasis"><em>performance
+</em></span> and <span class="emphasis"><em>scalability</em></span> labels. It
is important to bear
+in mind the differences between performance and scalability (for the most part,
+we are referring to system-wide scalability, and not necessarily only
+scalability within a single JVM). The performance-related hints will probably
+improve the performance of your application for a given user load, whereas the
+scalability-related hints will probably increase the total number of users that
+your application can service. Sometimes, increasing performance will decrease
+scalability, and vice versa. Typically, options that reduce the amount of work
+done on the database server will improve scalability, whereas those that push
+more work onto the server will have a negative impact on scalability.
+ </p>
+ <div class="table" id="d5e17299"><p class="title"><b>Table 15.1.
+ Optimization Guidelines
+ </b></p><div class="table-contents">
+
+ <table class="table" summary="
 Optimization
Guidelines
 " border="1"><colgroup><col align="left"
class="name"><col align="left" class="desc"></colgroup><tbody
valign="top"><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use a connection pool
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+OpenJPA's built-in datasource does not perform connection pooling or
+prepared statement caching, but it can use Apache Commons DBCP for connection
+pooling if it is provided on the classpath. Check out the
+<a class="link" href="ref_guide_dbsetup.html#ref_guide_dbsetup_builtin"
title="1. Using the OpenJPA DataSource">DriverDataSource</a>
+section, which describes how to use and configure Commons DBCP.
+Also, you can manually plug in a third-party pooling datasource like
+<a class="link" href="ref_guide_integration_dbcp.html" title="2. Apache
Commons DBCP">Apache Commons DBCP</a>,
+included in the binary distribution and openjpa-all artifact, which may
+drastically improve application performance.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Optimize database indexes
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+The default set of indexes created by OpenJPA's mapping tool may not always be
+the most appropriate for your application. Manually setting indexes in your
+mapping metadata or manually manipulating database indexes to include
+frequently-queried fields (as well as dropping indexes on rarely-queried
+fields) can yield significant performance benefits.
+ <p>
+A database must do extra work on insert, update, and delete to maintain an
+index. This extra work will benefit selects with WHERE clauses, which will
+execute much faster when the terms in the WHERE clause are appropriately
+indexed. So, for a read-mostly application, appropriate indexing will slow down
+updates (which are rare) but greatly accelerate reads. This means that the
+system as a whole will be faster, and also that the database will experience
+less load, meaning that the system will be more scalable.
+ </p>
+ <p>
+Bear in mind that over-indexing is a bad thing, both for scalability and
+performance, especially for applications that perform lots of inserts, updates,
+or deletes.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ JVM optimizations
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, reliability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Manipulating various parameters of the Java Virtual Machine (such as hotspot
+compilation modes and the maximum memory) can result in performance
+improvements. For more details about optimizing the JVM execution environment,
+please see <a class="ulink"
href="http://www.oracle.com/technetwork/java/hotspotfaq-138619.html";
target="_top">http://www.oracle.com/technetwork/java/hotspotfaq-138619.html</a>.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use the data cache
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Using OpenJPA's <a class="link" href="ref_guide_caching.html#ref_guide_cache"
title="1. Data Cache">data and query caching</a>
+features can often result in a dramatic improvement in performance.
+Additionally, these caches can significantly reduce the amount of load on
+the database, increasing the scalability characteristics of your application.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Set <code class="literal">LargeTransaction</code>
to true,
+ or set <code class="literal">
PopulateDataCache</code> to
+ false
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance vs. scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+When using OpenJPA's <a class="link"
href="ref_guide_caching.html#ref_guide_cache" title="1. Data Cache">data
caching</a>
+features in a transaction that will delete, modify, or create a very large
+number of objects you can set <code class="literal">LargeTransaction</code> to
true and
+perform periodic flushes during your transaction to reduce its memory
+requirements. See the Javadoc:
+<a class="ulink"
href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html"
target="_top">
+OpenJPAEntityManager.setTrackChangesByType</a>. Note that transactions in
+large mode have to more aggressively flush items from the data cache.
+ <p>
+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:
+<a class="ulink"
href="../javadoc/org/apache/openjpa/persistence/OpenJPAEntityManager.html"
target="_top">
+OpenJPAEntityManager.setPopulateDataCache</a>
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Run the OpenJPA enhancer on your persistent
classes,
+ either at build-time or deploy-time.
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability, memory
footprint</em></span>
+ </p>
+ </td><td align="left" valign="top">
+OpenJPA performs best when your persistent classes have been run through the
+OpenJPA post-compilation bytecode enhancer. When dealing with enhanced classes,
+OpenJPA can make a number of assumptions that reduce memory footprint and
+accelerate persistent data access. When evaluating OpenJPA's performance,
+build-time or deploy-time enhancement should be enabled. See
+<a class="xref" href="ref_guide_pc_enhance.html" title="2.
Enhancement">Section 2, “
+ Enhancement
+ ”</a> for details.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Disable logging, performance tracking
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Developer options such as verbose logging and the JDBC performance tracker can
+result in serious performance hits for your application. Before evaluating
+OpenJPA's performance, these options should all be disabled.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Set <code class="literal">IgnoreChanges</code> to
true, or
+ set <code
class="literal">FlushBeforeQueries</code> to true
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance vs. scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+When both the <a class="link"
href="ref_guide_conf_openjpa.html#openjpa.IgnoreChanges" title="5.37.
openjpa.IgnoreChanges"><code class="literal">
+openjpa.IgnoreChanges</code></a> and
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.FlushBeforeQueries"
title="5.36. openjpa.FlushBeforeQueries"><code
class="literal">openjpa.FlushBeforeQueries
+</code></a> properties are set to false, OpenJPA needs to consider
+in-memory dirty instances during queries. This can sometimes result in OpenJPA
+needing to evaluate the entire extent objects in order to return the correct
+query results, which can have drastic performance consequences. If it is
+appropriate for your application, configuring <code
class="literal">FlushBeforeQueries
+</code> to automatically flush before queries involving dirty objects will
+ensure that this never happens. Setting <code
class="literal">IgnoreChanges</code> to
+false will result in a small performance hit even if <code
class="literal">FlushBeforeQueries
+</code> is true, as incremental flushing is not as efficient overall as
+delaying all flushing to a single operation during commit.
+ <p>
+Setting <code class="literal">IgnoreChanges</code> to <code
class="literal">true</code> will help
+performance, since dirty objects can be ignored for queries, meaning that
+incremental flushing or client-side processing is not necessary. It will also
+improve scalability, since overall database server usage is diminished. On the
+other hand, setting <code class="literal">IgnoreChanges</code> to <code
class="literal">false</code>
+will have a negative impact on scalability, even when using automatic flushing
+before queries, since more operations will be performed on the database server.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Configure <code
class="literal">openjpa.ConnectionRetainMode
+ </code> appropriately
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance vs. scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+The <a class="link"
href="ref_guide_conf_openjpa.html#openjpa.ConnectionRetainMode"
title="5.25. openjpa.ConnectionRetainMode"><code
class="literal">ConnectionRetainMode
+</code></a> configuration option controls when OpenJPA will obtain a
+connection, and how long it will hold that connection. The optimal settings for
+this option will vary considerably depending on the particular behavior of
+your application. You may even benefit from using different retain modes for
+different parts of your application.
+ <p>
+The default setting of <code class="literal">on-demand</code> minimizes the
amount of time
+that OpenJPA holds onto a datastore connection. This is generally the best
+option from a scalability standpoint, as database resources are held for a
+minimal amount of time. However, if you are not using connection pooling, or
+if your <code class="classname">DataSource</code> is not efficient at managing
its
+pool, then this default value could cause undesirable pool contention.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use flat inheritance
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability vs. disk space</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Mapping inheritance hierarchies to a single database table is faster for most
+operations than other strategies employing multiple tables. If it is
+appropriate for your application, you should use this strategy whenever
+possible.
+ <p>
+However, this strategy will require more disk space on the database side. Disk
+space is relatively inexpensive, but if your object model is particularly
large,
+it can become a factor.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ High sequence increment
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+For applications that perform large bulk inserts, the retrieval of sequence
+numbers can be a bottleneck. Increasing sequence allocation sizes can reduce
or eliminate
+this bottleneck. In some cases, implementing your own sequence factory can
+further optimize sequence number retrieval.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use optimistic transactions
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Using datastore transactions translates into pessimistic database row locking,
+which can be a performance hit (depending on the database). If appropriate for
+your application, optimistic transactions are typically faster than datastore
+transactions.
+ <p>
+Optimistic transactions provide the same transactional guarantees as datastore
+transactions, except that you must handle a potential optimistic verification
+exception at the end of a transaction instead of assuming that a transaction
+will successfully complete. In many applications, it is unlikely that different
+concurrent transactions will operate on the same set of data at the same time,
+so optimistic verification increases the concurrency, and therefore both the
+performance and scalability characteristics, of the application. A common
+approach to handling optimistic verification exceptions is to simply present
the
+end user with the fact that concurrent modifications happened, and require that
+the user redo any work.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use query aggregates and projections
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Using aggregates to compute reporting data on the database server can
+drastically speed up queries. Similarly, using projections when you are
+interested in specific object fields or relations rather than the entire object
+state can reduce the amount of data OpenJPA must transfer from the database to
+your application.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Always close resources
+ </strong></span>
+ <p>
+<span class="emphasis"><em>scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+ <p>
+Under certain settings, <code class="classname"> EntityManager</code> s,
OpenJPA
+<code class="classname">Extent</code> iterators, and <code
class="classname">Query</code>
+results may be backed by resources in the database.
+ </p>
+ <p>
+For example, if you have configured OpenJPA to use scrollable cursors and lazy
+object instantiation by default, each query result will hold open a <code
class="classname">
+ResultSet</code> object, which, in turn, will hold open a <code
class="classname">
+Statement</code> object (preventing it from being re-used). Garbage
+collection will clean up these resources, so it is never necessary to
explicitly
+close them, but it is always faster if it is done at the application level.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use detached state managers
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance</em></span>
+ </p>
+ </td><td align="left" valign="top">
+ <p>
+Attaching and even persisting instances can be more efficient when your
detached
+objects use detached state managers. By default, OpenJPA does not use detached
+state managers when serializing an instance across tiers. See
+<a class="xref" href="ref_guide_remote.html#ref_guide_detach_graph"
title="1.3. Defining the Detached Object Graph">Section 1.3, “
+ Defining the Detached Object Graph
+ ”</a> for how to force OpenJPA to use
+detached state managers across tiers, and for other options for more efficient
+attachment.
+ </p>
+ <p>
+The downside of using a detached state manager across tiers is that your
+enhanced persistent classes and the OpenJPA libraries must be available on the
+client tier.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Utilize the <code
class="classname">EntityManager</code>
+ cache
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+When possible and appropriate, re-using <code
class="classname">EntityManager</code>s
+and setting the <a class="link"
href="ref_guide_conf_openjpa.html#openjpa.RetainState" title="5.63.
openjpa.RetainState"><code class="literal">RetainState
+</code></a> configuration option to <code class="literal">true</code> may
result in
+significant performance gains, since the <code
class="classname">EntityManager</code>'s
+built-in object cache will be used.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Enable multithreaded operation only when necessary
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance</em></span>
+ </p>
+ </td><td align="left" valign="top">
+OpenJPA respects the <a class="link"
href="ref_guide_conf_openjpa.html#openjpa.Multithreaded" title="5.50.
openjpa.Multithreaded"><code class="literal">
+openjpa.Multithreaded</code></a> option in that it does not impose as
+much synchronization overhead for applications that do not set this value to
+<code class="literal">true</code>. If your application is guaranteed to only
use
+single-threaded access to OpenJPA resources and persistent objects, leaving
+this option as <code class="literal">false</code> will reduce synchronization
overhead,
+and may result in a modest performance increase.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Enable large data set handling
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+If you execute queries that return large numbers of objects or have relations
+(collections or maps) that are large, and if you often only access parts of
+these data sets, enabling <a class="link" href="ref_guide_dbsetup_lrs.html"
title="10. Large Result Sets">large result
+set handling</a> where appropriate can dramatically speed up your
+application, since OpenJPA will bring the data sets into memory from the
+database only as necessary.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Disable large data set handling
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+If you have enabled scrollable result sets and on-demand loading but you do not
+require it, consider disabling it again. Some JDBC drivers and databases
+(SQL Server for example) are much slower when used with scrolling result sets.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use the <code
class="classname">DynamicSchemaFactory</code>
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, validation</em></span>
+ </p>
+ </td><td align="left" valign="top">
+If you are using an <a class="link"
href="ref_guide_conf_jdbc.html#openjpa.jdbc.SchemaFactory" title="6.13.
openjpa.jdbc.SchemaFactory"><code class="literal">
+openjpa.jdbc.SchemaFactory</code></a> setting of something other than
+the default of <code class="literal">dynamic</code>, consider switching back.
While other
+factories can ensure that object-relational mapping information is valid when
+a persistent class is first used, this can be a slow process. Though the
+validation is only performed once for each class, switching back to the
+<code class="classname">DynamicSchemaFactory</code> can reduce the warm-up
time for
+your application.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Do not use XA transactions
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+<a class="link" href="ref_guide_enterprise_xa.html" title="3. XA
Transactions">XA transactions</a> can be orders of
+magnitude slower than standard transactions. Unless distributed transaction
+functionality is required by your application, use standard transactions.
+ <p>
+Recall that XA transactions are distinct from managed transactions - managed
+transaction services such as that provided by EJB declarative transactions can
+be used both with XA and non-XA transactions. XA transactions should only be
+used when a given business transaction involves multiple different
transactional
+resources (an Oracle database and an IBM transactional message queue, for
+example).
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use <code class="classname">Set</code>s instead of
+ <code class="classname">List/Collection</code>s
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+There is a small amount of extra overhead for OpenJPA to maintain collections
+where each element is not guaranteed to be unique. If your application does
+not require duplicates for a collection, you should always declare your
+fields to be of type <code class="classname">Set, SortedSet, HashSet,</code>
or
+<code class="classname">TreeSet</code>.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use query parameters instead of encoding search
+ data in filter strings
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance</em></span>
+ </p>
+ </td><td align="left" valign="top">
+If your queries depend on parameter data only known at runtime, you should use
+query parameters rather than dynamically building different query strings.
+OpenJPA performs aggressive caching of query compilation data, and the
+effectiveness of this cache is diminished if multiple query filters are used
+where a single one could have sufficed.
+ </td></tr><tr><td align="left"
valign="top">
+ <span class="bold"><strong>
+ Tune your fetch groups appropriately
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+The <a class="link" href="ref_guide_fetch.html" title="7. Fetch
Groups">fetch groups</a> used when loading an
+object control how much data is eagerly loaded, and by extension, which fields
+must be lazily loaded at a future time. The ideal fetch group configuration
+loads all the data that is needed in one fetch, and no extra fields - this
+minimizes both the amount of data transferred from the database, and the
+number of trips to the database.
+ <p>
+If extra fields are specified in the fetch groups (in particular, large fields
+such as binary data, or relations to other persistence-capable objects), then
+network overhead (for the extra data) and database processing (for any
necessary
+additional joins) will hurt your application's performance. If too few fields
+are specified in the fetch groups, then OpenJPA will have to make additional
+trips to the database to load additional fields as necessary.
+ </p>
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Use eager fetching
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Using <a class="link" href="ref_guide_perfpack_eager.html" title="8.
Eager Fetching">eager fetching</a> when
+loading subclass data or traversing relations for each instance in a large
+collection of results can speed up data loading by orders of magnitude.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Disable BrokerImpl finalization
+ </strong></span>
+ <p>
+<span class="emphasis"><em>performance, scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+Outside of a Java EE application server or other JPA persistence container,
+OpenJPA's EntityManagers use finalizers to ensure that resources
+get cleaned up. If you are properly managing your resources, this finalization
+is not necessary, and will introduce unneeded synchronization, leading to
+scalability problems. You can disable this protective behavior by setting the
+<code class="literal">openjpa.BrokerImpl</code> property to
+<code class="literal">non-finalizing</code>. See <a class="xref"
href="ref_guide_runtime.html#ref_guide_runtime_broker_finalization"
title="1.1. Broker Finalization">Section 1.1, “
+ Broker Finalization
+ ”</a> for details.
+ </td></tr><tr><td align="left" valign="top">
+ <span class="bold"><strong>
+ Preload MetaDataRepository
+ </strong></span>
+ <p>
+<span class="emphasis"><em>scalability</em></span>
+ </p>
+ </td><td align="left" valign="top">
+By default, the MetaDataRepository is lazily loaded which means that fair
amounts of locking
+is used to ensure that metadata is processed properly. Enabling preloading
allows OpenJPA to
+load metadata upfront and remove locking. See <a class="xref"
href="ref_guide_meta_repository.html" title="2. Metadata
Repository">Section 2, “Metadata Repository”</a> for details.
+ </td></tr></tbody></table>
+ </div></div><br class="table-break">
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation
footer"><tr><td width="40%" align="left"><a accesskey="p"
href="ref_guide_integration_dbcp.html">Prev</a> </td><td width="20%"
align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td
width="40%" align="right"> <a accesskey="n"
href="ref_guide_instrumentation.html">Next</a></td></tr><tr><td width="40%"
align="left" valign="top">2.
+ Apache Commons DBCP
+ </td><td width="20%" align="center"><a accesskey="h"
href="manual.html">Home</a></td><td width="40%" align="right"
valign="top"> Chapter 16.
+ Instrumentation
+ </td></tr></table></div></body></html>
\ No newline at end of file
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_orphan.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_orphan.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_orphan.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,86 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>11. Orphaned Keys</title><base href="display"><link
rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator"
content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 User's Guide"><link rel="up"
href="ref_guide_mapping.html" title="Chapter 7. Mapping"><link
rel="prev" href="ref_guide_mapping_custom.html" title="10. Custom
Mappings"><link rel="next" href="ref_guide_deploy.html"
title="Chapter 8. Deployment"></head><body bgcolor="white"
text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div
class="navheader"><table width="100%" summary="Navigation header"><tr><th
colspan="3" align="center">11.
+ Orphaned Keys
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="ref_guide_mapping_custom.html">Prev</a> </td><th width="60%"
align="center">Chapter 7.
+ Mapping
+ </th><td width="20%" align="right"> <a accesskey="n"
href="ref_guide_deploy.html">Next</a></td></tr></table><hr></div><div
class="section" id="ref_guide_orphan"><div class="titlepage"><div><div><h2
class="title" style="clear: both">11.
+ Orphaned Keys
+ </h2></div></div></div>
+
+ <p>
+Unless you apply database foreign key constraints extensively, it is possible
to
+end up with orphaned keys in your database. For example, suppose <code
class="classname">
+Magazine</code> <code class="literal">m</code> has a reference to <code
class="classname">Article
+</code><code class="literal">a</code>. If you delete <code
class="literal">a</code> without
+nulling <code class="literal">m</code>'s reference, <code
class="literal">m</code>'s database
+record will wind up with an orphaned key to the non-existent <code
class="literal">a
+</code> record.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3
class="title">Note</h3>
+ <p>
+One way of avoiding orphaned keys is to use <span
class="emphasis"><em>dependent</em></span>
+fields.
+ </p>
+ </div>
+ <p>
+OpenJPA's <a class="link"
href="ref_guide_conf_openjpa.html#openjpa.OrphanedKeyAction" title="5.53.
openjpa.OrphanedKeyAction"><code class="literal">
+openjpa.OrphanedKeyAction</code></a> configuration property controls what
+action to take when OpenJPA encounters an orphaned key. You can set this plugin
+string (see <a class="xref" href="ref_guide_conf_plugins.html" title="4.
Plugin Configuration">Section 4, “
+ Plugin Configuration
+ ”</a>) to a custom
+implementation of the
+<a class="ulink"
href="../javadoc/org/apache/openjpa/event/OrphanedKeyAction.html" target="_top">
+<code class="classname"> org.apache.openjpa.event.OrphanedKeyAction</code></a>
+interface, or use one of the built-in options:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+<code class="literal">log</code>: This is the default setting. This option
logs a message
+for each orphaned key. It is an alias for the
+<a class="ulink"
href="../javadoc/org/apache/openjpa/event/LogOrphanedKeyAction.html"
target="_top">
+<code
class="classname">org.apache.openjpa.event.LogOrphanedKeyAction</code></a>
+class, which has the following additional properties:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: circle; "><li class="listitem">
+ <p>
+<code class="literal">Channel</code>: The channel to log to. Defaults to <code
class="literal">
+openjpa.Runtime</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">Level</code>: The level to log at. Defaults to <code
class="literal">WARN
+</code>.
+ </p>
+ </li></ul></div>
+ </li><li class="listitem">
+ <p>
+<code class="literal">exception</code>: Throw an <code class="classname">
+EntityNotFoundException</code> when OpenJPA discovers an
+orphaned key. This is an alias for the
+<a class="ulink"
href="../javadoc/org/apache/openjpa/event/ExceptionOrphanedKeyAction.html"
target="_top">
+<code
class="classname">org.apache.openjpa.event.ExceptionOrphanedKeyAction</code>
+</a> class.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">none</code>: Ignore orphaned keys. This is an alias for
the
+<a class="ulink"
href="../javadoc/org/apache/openjpa/event/NoneOrphanedKeyAction.html"
target="_top">
+<code
class="classname">org.apache.openjpa.event.NoneOrphanedKeyAction</code></a>
+class.
+ </p>
+ </li></ul></div>
+ <div class="example" id="ref_guide_orphan_logex"><p
class="title"><b>Example 7.26.
+ Custom Logging Orphaned Keys
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+<property name="openjpa.OrphanedKeyAction" value="log(Channel=Orphans,
Level=DEBUG)"/>
+</pre>
+ </div></div><br class="example-break">
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation
footer"><tr><td width="40%" align="left"><a accesskey="p"
href="ref_guide_mapping_custom.html">Prev</a> </td><td width="20%"
align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td
width="40%" align="right"> <a accesskey="n"
href="ref_guide_deploy.html">Next</a></td></tr><tr><td width="40%" align="left"
valign="top">10.
+ Custom Mappings
+ </td><td width="20%" align="center"><a accesskey="h"
href="manual.html">Home</a></td><td width="40%" align="right"
valign="top"> Chapter 8.
+ Deployment
+ </td></tr></table></div></body></html>
\ No newline at end of file
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,152 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>Chapter 5. Persistent Classes</title><base
href="display"><link rel="stylesheet" type="text/css"
href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets
V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 User's
Guide"><link rel="up" href="ref_guide.html" title="Part 3. Reference
Guide"><link rel="prev" href="ref_guide_schema_xml.html" title="14. XML
Schema Format"><link rel="next" href="ref_guide_pc_enhance.html"
title="2. Enhancement"></head><body bgcolor="white" text="black"
link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table
width="100%" summary="Navigation header"><tr><th colspan="3"
align="center">Chapter 5.
+ Persistent Classes
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="ref_guide_schema_xml.html">Prev</a> </td><th width="60%"
align="center">Part 3. Reference Guide</th><td width="20%"
align="right"> <a accesskey="n"
href="ref_guide_pc_enhance.html">Next</a></td></tr></table><hr></div><div
class="chapter" id="ref_guide_pc"><div class="titlepage"><div><div><h2
class="title">Chapter 5.
+ Persistent Classes
+ </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl
class="toc"><dt><span class="section"><a
href="ref_guide_pc.html#ref_guide_pc_pcclasses">1.
+ Persistent Class List
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html">2.
+ Enhancement
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_build">2.1.
+ Enhancing at Build Time
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_runtime_container">2.2.
+ Enhancing JPA Entities on Deployment
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_runtime">2.3.
+ Enhancing at Runtime
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_dynamic">2.4.
+ Enhancing Dynamically at Runtime
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_unenhanced_types">2.5.
+ Omitting the OpenJPA enhancer
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="ref_guide_pc_interfaces.html">3. Managed
Interfaces</a></span></dt><dt><span class="section"><a
href="ref_guide_pc_oid.html">4.
+ Object Identity
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_pc_oid.html#ref_guide_pc_oid_datastore">4.1.
+ Datastore Identity
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_oid.html#ref_guide_pc_oid_entitypk">4.2.
+ Entities as Identity Fields
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_oid.html#ref_guide_pc_oid_application">4.3.
+ Application Identity Tool
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_oid.html#ref_guide_pc_oid_pkgen_autoinc">4.4.
+ Autoassign / Identity Strategy Caveats
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="ref_guide_inverses.html">5.
+ Managed Inverses
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html">6.
+ Persistent Fields
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_restore">6.1.
+ Restoring State
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_order">6.2.
+ Typing and Ordering
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_calendar_timezone">6.3.
+ Calendar Fields and TimeZones
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy">6.4.
+ Proxies
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_smart">6.4.1.
+ Smart Proxies
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_lrs">6.4.2.
+ Large Result Set Proxies
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_custom">6.4.3.
+ Custom Proxies
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_scos_proxy_serial">6.4.4.
+ Serialization
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_extern">6.5.
+ Externalization
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_pc_scos.html#ref_guide_pc_extern_values">6.5.1.
+ External Values
+ </a></span></dt></dl></dd></dl></dd><dt><span
class="section"><a href="ref_guide_fetch.html">7.
+ Fetch Groups
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_fetch.html#ref_guide_fetch_custom">7.1.
+ Custom Fetch Groups
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_fetch.html#ref_guide_fetch_conf">7.2.
+ Custom Fetch Group Configuration
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_fetch.html#ref_guide_fetch_single_field">7.3.
+ Per-field Fetch Configuration
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_fetch.html#ref_guide_fetch_impl">7.4.
+ Implementation Notes
+ </a></span></dt></dl></dd><dt><span class="section"><a
href="ref_guide_perfpack_eager.html">8.
+ Eager Fetching
+ </a></span></dt><dd><dl><dt><span class="section"><a
href="ref_guide_perfpack_eager.html#ref_guide_perfpack_eager_conf">8.1.
+ Configuring Eager Fetching
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_perfpack_eager.html#ref_guide_perfpack_eager_consider">8.2.
+ Eager Fetching Considerations and Limitations
+ </a></span></dt></dl></dd></dl></div>
+
+ <a class="indexterm" name="d5e12108"></a>
+ <p>
+Persistent class basics are covered in <a class="xref"
href="jpa_overview_pc.html" title="Chapter 4.
Entity">Chapter 4, <i>
+ Entity
+ </i></a>
+of the JPA Overview. This chapter details the persistent class features OpenJPA
+offers beyond the core JPA specification.
+ </p>
+ <div class="section" id="ref_guide_pc_pcclasses"><div
class="titlepage"><div><div><h2 class="title" style="clear: both">1.
+ Persistent Class List
+ </h2></div></div></div>
+
+ <a class="indexterm" name="d5e12114"></a>
+ <a class="indexterm" name="d5e12117"></a>
+ <p>
+Unlike many ORM products, OpenJPA does not need to know about all of your
+persistent classes at startup. OpenJPA discovers new persistent classes
+automatically as they are loaded into the JVM; in fact you can introduce new
+persistent classes into running applications under OpenJPA. However, there are
+certain situations in which providing OpenJPA with a persistent class list is
+helpful:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+OpenJPA must be able to match entity names in JPQL queries to persistent
+classes. OpenJPA automatically knows the entity names of any persistent classes
+already loaded into the JVM. To match entity names to classes that have not
been
+loaded, however, you must supply a persistent class list.
+ </p>
+ </li><li class="listitem">
+ <p>
+When OpenJPA manipulates classes in a persistent inheritance hierarchy, OpenJPA
+must be aware of all the classes in the hierarchy. If some of the classes have
+not been loaded into the JVM yet, OpenJPA may not know about them, and queries
+may return incorrect results.
+ </p>
+ </li><li class="listitem">
+ <p>
+If you configure OpenJPA to create the needed database schema on startup (see
+<a class="xref" href="ref_guide_mapping.html#ref_guide_mapping_synch"
title="1.3. Runtime Forward Mapping">Section 1.3, “
+ Runtime Forward Mapping
+ ”</a>), OpenJPA must know all of your
+persistent classes up-front.
+ </p>
+ </li></ul></div>
+ <p>
+When any of these conditions are a factor in your JPA application, use the
+<code class="literal">class</code>, <code class="literal">mapping-file</code>,
and <code class="literal">
+jar-file</code> elements of JPA's standard XML format to list your persistent
+classes. See <a class="xref"
href="jpa_overview_persistence.html#jpa_overview_persistence_xml"
title="1. persistence.xml">Section 1, “
+ persistence.xml
+ ”</a> for details.
+ </p>
+ <p>
+Alternately, you can tell OpenJPA to search through your classpath for
+persistent types. This is described in more detail in
+<a class="xref" href="ref_guide_meta.html#ref_guide_meta_factory"
title="1. Metadata Factory">Section 1, “
+ Metadata Factory
+ ”</a>.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3
class="title">Note</h3>
+ <p>
+Listing persistent classes (or their metadata or jar files) is an
all-or-nothing
+endeavor. If your persistent class list is non-empty, OpenJPA will assume that
+any unlisted class is not persistent.
+ </p>
+ </div>
+ </div>
+
+
+
+
+
+
+
+</div><div class="navfooter"><hr><table width="100%" summary="Navigation
footer"><tr><td width="40%" align="left"><a accesskey="p"
href="ref_guide_schema_xml.html">Prev</a> </td><td width="20%"
align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td
width="40%" align="right"> <a accesskey="n"
href="ref_guide_pc_enhance.html">Next</a></td></tr><tr><td width="40%"
align="left" valign="top">14.
+ XML Schema Format
+ </td><td width="20%" align="center"><a accesskey="h"
href="manual.html">Home</a></td><td width="40%" align="right"
valign="top"> 2.
+ Enhancement
+ </td></tr></table></div></body></html>
\ No newline at end of file
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_enhance.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_enhance.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_enhance.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,411 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>2. Enhancement</title><base href="display"><link
rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator"
content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_pc.html"
title="Chapter 5. Persistent Classes"><link rel="prev"
href="ref_guide_pc.html" title="Chapter 5. Persistent Classes"><link
rel="next" href="ref_guide_pc_interfaces.html" title="3. Managed
Interfaces"></head><body bgcolor="white" text="black" link="#0000FF"
vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%"
summary="Navigation header"><tr><th colspan="3" align="center">2.
+ Enhancement
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="ref_guide_pc.html">Prev</a> </td><th width="60%"
align="center">Chapter 5.
+ Persistent Classes
+ </th><td width="20%" align="right"> <a accesskey="n"
href="ref_guide_pc_interfaces.html">Next</a></td></tr></table><hr></div><div
class="section" id="ref_guide_pc_enhance"><div class="titlepage"><div><div><h2
class="title" style="clear: both">2.
+ Enhancement
+ </h2></div></div></div><div class="toc"><dl class="toc"><dt><span
class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_build">2.1.
+ Enhancing at Build Time
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_runtime_container">2.2.
+ Enhancing JPA Entities on Deployment
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_runtime">2.3.
+ Enhancing at Runtime
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_dynamic">2.4.
+ Enhancing Dynamically at Runtime
+ </a></span></dt><dt><span class="section"><a
href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_unenhanced_types">2.5.
+ Omitting the OpenJPA enhancer
+ </a></span></dt></dl></div>
+
+ <a class="indexterm" name="d5e12139"></a>
+ <a class="indexterm" name="d5e12141"></a>
+ <p>
+In order to provide optimal runtime performance, flexible lazy loading, and
+efficient, immediate dirty tracking, OpenJPA can use an <span
class="emphasis"><em>enhancer
+</em></span>. An enhancer is a tool that automatically adds code to your
+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. 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 <code class="literal">pc</code> in stack
traces and
+step-throughs. For example, if your entity has a <code
class="methodname">getId</code>
+method for persistent property <code class="literal">id</code>, and that
method throws an
+exception, the stack trace will report the exception from method <code
class="methodname">
+pcgetId</code>. The line numbers, however, will correctly correspond to
+the <code class="methodname">getId</code> method in your source file.
+ </p>
+ <div class="mediaobject"><table border="0" summary="manufactured
viewport for HTML img" style="cellpadding: 0; cellspacing: 0;"
width="339"><tr><td><img src="img/enhancement.png"></td></tr></table></div>
+ <p>
+The diagram above illustrates the compilation of a persistent class.
+ </p>
+ <p>
+You can add the OpenJPA enhancer to your build process, or use Java 1.5's
+instrumentation features to transparently enhance persistent classes when they
+are loaded into the JVM. The following sections describe each option.
+ </p>
+ <div class="section" id="ref_guide_pc_enhance_build"><div
class="titlepage"><div><div><h3 class="title">2.1.
+ Enhancing at Build Time
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12158"></a>
+ <p>
+The enhancer can be invoked at build time
+via its Java class, <code class="classname">
+org.apache.openjpa.enhance.PCEnhancer</code>.
+ </p>
+ <div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+ <p>
+You can also enhance via Ant; see
+<a class="xref"
href="ref_guide_integration.html#ref_guide_integration_enhance"
title="1.2. Enhancer Ant Task">Section 1.2, “
+ Enhancer Ant Task
+ ”</a>.
+ </p>
+ </div>
+ <div class="example" id="ref_guide_pc_enhance_enhancer"><p
class="title"><b>Example 5.1.
+ Using the OpenJPA Enhancer
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+java org.apache.openjpa.enhance.PCEnhancer Magazine.java
+</pre>
+ </div></div><br class="example-break">
+ <p>
+The enhancer accepts the standard set of command-line arguments defined by the
+configuration framework (see <a class="xref"
href="ref_guide_conf_devtools.html" title="3. Command Line
Configuration">Section 3, “
+ Command Line Configuration
+ ”</a> ),
+along with the following flags:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+<code class="literal">-directory/-d <output directory></code>: Path to
the output
+directory. If the directory does not match the enhanced class' package, the
+package structure will be created beneath the directory. By default, the
+enhancer overwrites the original <code class="filename">.class</code> file.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-enforcePropertyRestrictions/-epr <true/t |
false/f></code>:
+Whether to throw an exception when it appears that a property access entity is
+not obeying the restrictions placed on property access. Defaults to false.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-addDefaultConstructor/-adc <true/t |
false/f></code>: 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 <code
class="literal">
+true</code>.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">-tmpClassLoader/-tcl <true/t | false/f></code>:
Whether to
+load persistent classes with a temporary class loader. This allows other code
to
+then load the enhanced version of the class within the same JVM. Defaults to
+<code class="literal">true</code>. Try setting this flag to <code
class="literal">false</code> as a
+debugging step if you run into class loading problems when running the
enhancer.
+ </p>
+ </li></ul></div>
+ <p>
+Each additional argument to the enhancer must be one of the following:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+The full name of a class.
+ </p>
+ </li><li class="listitem">
+ <p>
+The .java file for a class.
+ </p>
+ </li><li class="listitem">
+ <p>
+The <code class="filename">.class</code> file of a class.
+ </p>
+ </li></ul></div>
+ <p>
+If you do not supply any arguments to the enhancer, it will run on the classes
+in your persistent class list (see <a class="xref"
href="ref_guide_pc.html#ref_guide_pc_pcclasses" title="1. Persistent
Class List">Section 1, “
+ Persistent Class List
+ ”</a>).
+You must, however, supply the classpath you wish the enhancer to run with. This
+classpath must include, at minimum, the openjpa jar(s), persistence.xml and
+the target classes.
+ </p>
+ <p>
+You can run the enhancer over classes that have already been enhanced, in which
+case it will not further modify the class. You can also run it over classes
that
+are not persistence-capable, in which case it will treat the class as
+persistence-aware. Persistence-aware classes can directly manipulate the
+persistent fields of persistence-capable classes.
+ </p>
+ <p>
+Note that the enhancement process for subclasses introduces dependencies on the
+persistent parent class being enhanced. This is normally not problematic;
+however, when running the enhancer multiple times over a subclass whose parent
+class is not yet enhanced, class loading errors can occur. In the event of a
+class load error, simply re-compile and re-enhance the offending classes.
+ </p>
+ </div>
+ <div class="section" id="ref_guide_pc_enhance_runtime_container"><div
class="titlepage"><div><div><h3 class="title">2.2.
+ Enhancing JPA Entities on Deployment
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12203"></a>
+ <p>
+The Java EE specification includes hooks to automatically enhance JPA entities
+when they are deployed into a container. Thus, if you are using a Java
EE-compliant application server,
+OpenJPA will enhance your entities automatically
+at runtime. Note that if you prefer build-time enhancement, OpenJPA's runtime
+enhancer will correctly recognize and skip pre-enhanced classes.
+ </p>
+ <p>
+If your application server does not support the Java EE enhancement hooks,
+consider using the build-time enhancement described above, or the more general
+runtime enhancement described in the next section.
+ </p>
+ </div>
+ <div class="section" id="ref_guide_pc_enhance_runtime"><div
class="titlepage"><div><div><h3 class="title">2.3.
+ Enhancing at Runtime
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12211"></a>
+ <p>
+OpenJPA includes a <span class="emphasis"><em>Java agent</em></span> for
automatically enhancing
+persistent classes as they are loaded into the JVM. Java agents are classes
that
+are invoked prior to your application's <code class="methodname">main</code>
method.
+OpenJPA's agent uses JVM hooks to intercept all class loading to enhance
classes
+that have persistence metadata before the JVM loads them.
+ </p>
+ <p>
+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 <a class="xref"
href="ref_guide_pc.html#ref_guide_pc_pcclasses" title="1. Persistent
Class List">Section 1, “
+ Persistent Class List
+ ”</a>. If
+you declare a persistent class list, OpenJPA will only search for
+metadata for classes in that list.
+ </p>
+ <p>
+To employ the OpenJPA agent, invoke <code class="literal">java</code> with the
<code class="literal">
+-javaagent</code> set to the path to your OpenJPA jar file.
+ </p>
+ <div class="example" id="ref_guide_pc_enhance_runtime_ex"><p
class="title"><b>Example 5.2.
+ Using the OpenJPA Agent for Runtime Enhancement
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+java -javaagent:/home/dev/openjpa/lib/openjpa.jar com.xyz.Main
+</pre>
+ </div></div><br class="example-break">
+ <p>
+You can pass settings to the agent using OpenJPA's plugin syntax (see
+<a class="xref" href="ref_guide_conf_plugins.html" title="4. Plugin
Configuration">Section 4, “
+ Plugin Configuration
+ ”</a>). The agent accepts the long
+form of any of the standard configuration options
+(<a class="xref" href="ref_guide_conf_devtools.html" title="3. Command
Line Configuration">Section 3, “
+ Command Line Configuration
+ ”</a> ). It also accepts the following
+options, the first three of which correspond exactly to the same-named
+options of the enhancer tool described in
+<a class="xref" href="ref_guide_pc_enhance.html#ref_guide_pc_enhance_build"
title="2.1. Enhancing at Build Time">Section 2.1, “
+ Enhancing at Build Time
+ ”</a>:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+<code class="literal">addDefaultConstructor</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">enforcePropertyRestrictions</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">scanDevPath</code>: Boolean indicating whether to scan
the
+classpath for persistent types if none have been configured. If you do not
+specify a persistent types list and do not set this option to true, OpenJPA
will
+check whether each class loaded into the JVM is persistent, and enhance it
+accordingly. This may slow down class load times significantly.
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">classLoadEnhancement</code>: Boolean controlling whether
OpenJPA
+load-time class enhancement should be available in this JVM execution. Default:
+<code class="literal">true</code>
+ </p>
+ </li><li class="listitem">
+ <p>
+<code class="literal">runtimeRedefinition</code>: Boolean controlling whether
OpenJPA
+class redefinition should be available in this JVM execution. Default:
+<code class="literal">true</code>
+ </p>
+ </li></ul></div>
+ <div class="example" id="ref_guide_pc_enhance_runtime_opt_ex"><p
class="title"><b>Example 5.3.
+ Passing Options to the OpenJPA Agent
+ </b></p><div class="example-contents">
+
+<pre class="programlisting">
+java -javaagent:/home/dev/openjpa/lib/openjpa.jar=addDefaultConstructor=false
com.xyz.Main
+</pre>
+ </div></div><br class="example-break">
+ </div>
+<div class="section" id="ref_guide_pc_enhance_dynamic"><div
class="titlepage"><div><div><h3 class="title">2.4.
+ Enhancing Dynamically at Runtime
+ </h3></div></div></div>
+
+ <p>
+ If a javaagent is not provided via the command line and
+ OpenJPA is running on the Oracle 1.6 SDK or IBM 1.6 JDK (SR8+),
OpenJPA
+ will attempt to dynamically load the Enhancer that was
+ mentioned in the previous section. This support is
+ provided as an ease of use feature and it is not recommended
+ for use in a production system. Using this method of
+ enhancement has the following caveats:
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem">
+ <p>
+ The dynamic runtime enhancer is plugged into
+ the JVM during creation of the
+ EntityManagerFactory. Any Entity classes that
+ are loaded before the EntityManagerFactory is
+ created will not be enhanced.
+ </p>
+ </li><li class="listitem">
+ <p>
+ The command line javaagent settings are not
+ configurable when using this method of
+ enhancement.
+ </p>
+ </li><li class="listitem">
+ <p>
+ Just as with the Javaagent approach, if you
+ declare a persistent class list, then OpenJPA
+ will only search for metadata and try to
+ enhance the listed classes.
+ </p>
+ </li></ul></div>
+ <p>
+ When then dynamic enhancer is loaded, the following
+ informational message is logged:
+</p><pre class="programlisting">
+[java] jpa.enhancement INFO [main] openjpa.Runtime - OpenJPA dynamically
loaded the class enhancer. Any classes that were not enhanced at build time
will be enhanced when they are loaded by the JVM.
+</pre><p>
+ </p>
+ <p>
+ Setting the property openjpa.DynamicEnhancementAgent to false
+ will disable this function.
+ </p>
+</div>
+ <div class="section" id="ref_guide_pc_enhance_unenhanced_types"><div
class="titlepage"><div><div><h3 class="title">2.5.
+ Omitting the OpenJPA enhancer
+ </h3></div></div></div>
+
+ <a class="indexterm" name="d5e12266"></a>
+ <p>
+OpenJPA does not require that the enhancer be run. If you do not run the
+enhancer, OpenJPA will fall back to one of several possible alternatives for
+state tracking, depending on the execution environment.
+ </p>
+ <div class="itemizedlist"><ul class="itemizedlist"
style="list-style-type: disc; "><li class="listitem"><p>
+<span class="emphasis"><em>Deploy-time enhancement</em></span>: if you are
running your
+application inside a Java EE container, or another environment that supports
+the JPA container contract, then OpenJPA will automatically perform class
+transformation at deploy time.
+ </p></li><li class="listitem"><p>
+<span class="emphasis"><em>Java 6 class retransformation</em></span>: if you
are running your
+application in a Java 6 environment, OpenJPA will attempt to dynamically
+register a <code class="literal">ClassTransformer</code> that will redefine
your
+persistent classes on the fly to track access to persistent data. Additionally,
+OpenJPA will create a subclass for each of your persistent classes. When
+you execute a query or traverse a relation, OpenJPA will return an instance
+of the subclass. This means that the <code class="literal">instanceof</code>
operator
+will work as expected, but <code class="literal">o.getClass()</code> will
return the
+subclass instead of the class that you wrote.
+ </p>
+ <p>
+You do not need to do anything at all to get this behavior. OpenJPA will
+automatically detect whether or not the execution environment is capable of
+Java 6 class retransformation.
+ </p></li><li class="listitem"><p>
+<span class="emphasis"><em>Java 5 class redefinition</em></span>: if you are
running your
+application in a Java 5 environment, and you specify the OpenJPA javaagent,
+OpenJPA will use Java 5 class redefinition to redefine any persistent classes
+that are not enhanced by the OpenJPA javaagent. Aside from the requirement
+that you specify a javaagent on the command line, this behavior is exactly the
+same as the Java 6 class retransformation behavior. Of course, since the
+OpenJPA javaagent performs enhancement by default, this will only be available
+if you set the <code class="literal">classLoadEnhancement</code> javaagent
flag to
+<code class="literal">false</code>, or on any classes that are skipped by the
OpenJPA
+runtime enhancement process for some reason.
+ </p></li><li class="listitem"><p>
+<span class="emphasis"><em>Runtime Unenhanced Classes</em></span>: AKA state
comparison and
+subclassing. If you are running
+in a Java 5 environment without a javaagent, or in a Java 6 environment that
+does not support class retransformation, OpenJPA will still create subclasses
+as outlined above. However, in some cases, OpenJPA may not be able to receive
+notifications when you read or write persistent data.
+ </p>
+ <p>
+ </p><div class="note" style="margin-left: 0.5in; margin-right:
0.5in;"><h3 class="title">Note</h3>
+Runtime Unenhanced Classes has some known limitations which are discussed below
+and documented in JIRA issue tracker on the OpenJPA website. As a result this
option is
+disabled by default. Support for this method of automatic enhancement may be
+enabled via the <a class="xref"
href="ref_guide_conf_openjpa.html#openjpa.RuntimeUnenhancedClasses"
title="5.65. openjpa.RuntimeUnenhancedClasses">Section 5.65,
“openjpa.RuntimeUnenhancedClasses”</a> option.
+ </div><p>
+ </p>
+ <p>
+To enable Runtime Unenhanced Classes for a specific persistence unit, add the
following property to persistence.xml:
+</p><pre class="programlisting">
+<properties>
+ . . .
+ <property name="openjpa.RuntimeUnenhancedClasses" value="supported"/>
+ . . .
+<properties>
+</pre><p>
+ </p>
+ <p>
+If you are using <span class="emphasis"><em>property access</em></span> for
your persistent data,
+then OpenJPA will be able to track all accesses for instances that you load
+from the database, but not for instances that you create. This is because
+OpenJPA will create new instances of its dynamically-generated subclass when
+it loads data from the database. The dynamically-generated subclass has
+code in the setters and getters that notify OpenJPA about persistent data
+access. This means that new instances that you create will be subject to
+state-comparison checks (see discussion below) to compute which fields to
+write to the database, and that OpenJPA will ignore requests to evict
+persistent data from such instances. In practice, this is not a particularly
+bad limitation, since OpenJPA already knows that it must insert all field
+values for new instances. So, this is only really an issue if you flush
+changes to the database while inserting new records; after such a flush,
+OpenJPA will need to hold potentially-unneeded hard references to the
+new-flushed instances.
+ </p>
+ <p>
+If you are using <span class="emphasis"><em>field access</em></span> for your
persistent data,
+then OpenJPA will not be able to track accesses for any instances, including
+ones that you load from the database. So, OpenJPA will perform state-comparison
+checks to determine which fields are dirty. These state comparison checks are
+costly in two ways. First, there is a performance penalty at flush / commit
+time, since OpenJPA must walk through every field of every instance to
determine
+which fields of which records are dirty. Second, there is a memory penalty,
+since OpenJPA must hold hard references to all instances that were loaded at
+any time in a given transaction, and since OpenJPA must keep a copy of all
+the initial values of the loaded data for later comparison. Additionally,
+OpenJPA will ignore requests to evict persistent state for these types of
+instances. Finally, the default lazy loading configuration will be ignored for
+single-valued fields (one-to-one, many-to-one, and any other non-collection
+or non-map field that has a lazy loading configuration). If you use fetch
+groups or programmatically configure your fetch plan, OpenJPA will obey these
+directives, but will be unable to lazily load any data that you exclude from
+loading. As a result of these limitations, it is not recommended that you use
+field access if you are not either running the enhancer or using OpenJPA with
+a javaagent or in a Java 6 environment.
+ </p></li></ul></div>
+ </div>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation
footer"><tr><td width="40%" align="left"><a accesskey="p"
href="ref_guide_pc.html">Prev</a> </td><td width="20%" align="center"><a
accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%"
align="right"> <a accesskey="n"
href="ref_guide_pc_interfaces.html">Next</a></td></tr><tr><td width="40%"
align="left" valign="top">Chapter 5.
+ Persistent Classes
+ </td><td width="20%" align="center"><a accesskey="h"
href="manual.html">Home</a></td><td width="40%" align="right"
valign="top"> 3. Managed
Interfaces</td></tr></table></div></body></html>
\ No newline at end of file
Added:
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_interfaces.html
==============================================================================
---
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_interfaces.html
(added)
+++
websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_pc_interfaces.html
Fri Jan 6 19:19:20 2017
@@ -0,0 +1,42 @@
+<html><head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>3. Managed Interfaces</title><base href="display"><link
rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator"
content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html"
title="Apache OpenJPA 2.4 User's Guide"><link rel="up" href="ref_guide_pc.html"
title="Chapter 5. Persistent Classes"><link rel="prev"
href="ref_guide_pc_enhance.html" title="2. Enhancement"><link rel="next"
href="ref_guide_pc_oid.html" title="4. Object Identity"></head><body
bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation
header"><tr><th colspan="3" align="center">3. Managed
Interfaces</th></tr><tr><td width="20%" align="left"><a accesskey="p"
href="ref_guide_pc_enhance.html">Prev</a> </td><th width="60%"
align="center">Chapter 5.
+ Persistent Classes
+ </th><td width="20%" align="right"> <a accesskey="n"
href="ref_guide_pc_oid.html">Next</a></td></tr></table><hr></div><div
class="section" id="ref_guide_pc_interfaces"><div
class="titlepage"><div><div><h2 class="title" style="clear:
both">3. Managed Interfaces</h2></div></div></div>
+
+ <a class="indexterm" name="d5e12301"></a>
+ <p>
+OpenJPA's managed interface feature allows you to define your object model
+entirely in terms of interfaces, instead of concrete classes. To use this
+feature, you must annotate your managed interfaces with the
+<code class="classname">ManagedInterface</code> annotation, and use the
+<code class="literal">OpenJPAEntityManager.createInstance(Class)</code> method
to
+create new records. Note that <code class="literal">createInstance()</code>
returns
+unmanaged instances; you must pass them to
+<code class="literal">EntityManager.persist()</code> to store them in the
database.
+ </p>
+ <pre class="programlisting">
+@ManagedInterface
+public interface PersonIface {
+ @Id @GeneratedValue
+ int getId();
+ void setId(int id);
+
+ // implicitly persistent per JPA property rules
+ String getName();
+ void setName(String name);
+}
+ </pre>
+ <pre class="programlisting">
+OpenJPAEntityManager em = ...;
+PersonIface person = em.createInstance(PersonIface.class);
+person.setName("Homer Simpson");
+em.getTransaction().begin();
+em.persist(person);
+em.getTransaction().commit();
+ </pre>
+ </div><div class="navfooter"><hr><table width="100%" summary="Navigation
footer"><tr><td width="40%" align="left"><a accesskey="p"
href="ref_guide_pc_enhance.html">Prev</a> </td><td width="20%"
align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td
width="40%" align="right"> <a accesskey="n"
href="ref_guide_pc_oid.html">Next</a></td></tr><tr><td width="40%" align="left"
valign="top">2.
+ Enhancement
+ </td><td width="20%" align="center"><a accesskey="h"
href="manual.html">Home</a></td><td width="40%" align="right"
valign="top"> 4.
+ Object Identity
+ </td></tr></table></div></body></html>
\ No newline at end of file
