openjpa-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kwsut...@apache.org
Subject svn commit: r908837 [33/37] - /websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/
Date Wed, 14 May 2014 22:22:26 GMT
Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_optimization.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_optimization.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_optimization.html Wed May 14 22:22:23 2014
@@ -0,0 +1,509 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;15.&nbsp; Optimization Guidelines</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide.html" title="Part&nbsp;3.&nbsp;Reference Guide"><link rel="prev" href="ref_guide_integration_dbcp.html" title="2.&nbsp; Apache Commons DBCP"><link rel="next" href="ref_guide_instrumentation.html" title="Chapter&nbsp;16.&nbsp; 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&nbsp;15.&nbsp;
+        Optimization Guidelines
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_integration_dbcp.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;3.&nbsp;Reference Guide</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_instrumentation.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;15.&nbsp; Optimization Guidelines" id="ref_guide_optimization"><div class="titlepage"><div><div><h2 class="title">Chapter&nbsp;15.&nbsp;
+        Optimization Guidelines
+    </h2></div></div></div>
+    
+    <a class="indexterm" name="d5e17185"></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"><a name="d5e17191"></a><p class="title"><b>Table&nbsp;15.1.&nbsp;
+            Optimization Guidelines
+        </b></p><div class="table-contents">
+        
+        <table summary="&#xA;            Optimization Guidelines&#xA;        " 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; Enhancement">Section&nbsp;2, &#8220;
+            Enhancement
+        &#8221;</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.&nbsp; openjpa.IgnoreChanges"><code class="literal">
+openjpa.IgnoreChanges</code></a> and 
+<a class="link" href="ref_guide_conf_openjpa.html#openjpa.FlushBeforeQueries" title="5.36.&nbsp; 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.&nbsp; 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.&nbsp; Defining the Detached Object Graph">Section&nbsp;1.3, &#8220;
+                Defining the Detached Object Graph
+            &#8221;</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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; Broker Finalization">Section&nbsp;1.1, &#8220;
+                Broker Finalization
+            &#8221;</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.&nbsp;Metadata Repository">Section&nbsp;2, &#8220;Metadata Repository&#8221;</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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_instrumentation.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;
+            Apache Commons DBCP
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;16.&nbsp;
+        Instrumentation
+    </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_optimization.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_orphan.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_orphan.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_orphan.html Wed May 14 22:22:23 2014
@@ -0,0 +1,86 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>11.&nbsp; Orphaned Keys</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_mapping.html" title="Chapter&nbsp;7.&nbsp; Mapping"><link rel="prev" href="ref_guide_mapping_custom.html" title="10.&nbsp; Custom Mappings"><link rel="next" href="ref_guide_deploy.html" title="Chapter&nbsp;8.&nbsp; 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.&nbsp;
+            Orphaned Keys
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_mapping_custom.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;7.&nbsp;
+        Mapping
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_deploy.html">Next</a></td></tr></table><hr></div><div class="section" title="11.&nbsp; Orphaned Keys"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_orphan">11.&nbsp;
+            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" title="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.&nbsp; 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.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
+            Plugin Configuration
+        &#8221;</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" 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" 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"><a name="ref_guide_orphan_logex"></a><p class="title"><b>Example&nbsp;7.26.&nbsp;
+                Custom Logging Orphaned Keys
+            </b></p><div class="example-contents">
+            
+<pre class="programlisting">
+&lt;property name="openjpa.OrphanedKeyAction" value="log(Channel=Orphans, Level=DEBUG)"/&gt;
+</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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_mapping.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_deploy.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">10.&nbsp;
+            Custom Mappings
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;Chapter&nbsp;8.&nbsp;
+        Deployment
+    </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_orphan.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc.html Wed May 14 22:22:23 2014
@@ -0,0 +1,152 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>Chapter&nbsp;5.&nbsp; Persistent Classes</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide.html" title="Part&nbsp;3.&nbsp;Reference Guide"><link rel="prev" href="ref_guide_schema_xml.html" title="14.&nbsp; XML Schema Format"><link rel="next" href="ref_guide_pc_enhance.html" title="2.&nbsp; 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&nbsp;5.&nbsp;
+        Persistent Classes
+    </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_schema_xml.html">Prev</a>&nbsp;</td><th width="60%" align="center">Part&nbsp;3.&nbsp;Reference Guide</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_enhance.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter&nbsp;5.&nbsp; Persistent Classes" id="ref_guide_pc"><div class="titlepage"><div><div><h2 class="title">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><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="d5e12000"></a>
+    <p>
+Persistent class basics are covered in <a class="xref" href="jpa_overview_pc.html" title="Chapter&nbsp;4.&nbsp; Entity">Chapter&nbsp;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" title="1.&nbsp; Persistent Class List"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_pcclasses">1.&nbsp;
+            Persistent Class List
+        </h2></div></div></div>
+        
+        <a class="indexterm" name="d5e12006"></a>
+        <a class="indexterm" name="d5e12009"></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" 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.&nbsp; Runtime Forward Mapping">Section&nbsp;1.3, &#8220;
+                Runtime Forward Mapping
+            &#8221;</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.&nbsp; persistence.xml">Section&nbsp;1, &#8220;
+            persistence.xml
+        &#8221;</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.&nbsp; Metadata Factory">Section&nbsp;1, &#8220;
+            Metadata Factory
+        &#8221;</a>.
+        </p>
+        <div class="note" title="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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_enhance.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">14.&nbsp;
+            XML Schema Format
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;2.&nbsp;
+            Enhancement
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_enhance.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_enhance.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_enhance.html Wed May 14 22:22:23 2014
@@ -0,0 +1,411 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>2.&nbsp; Enhancement</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="next" href="ref_guide_pc_interfaces.html" title="3.&nbsp;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.&nbsp;
+            Enhancement
+        </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_interfaces.html">Next</a></td></tr></table><hr></div><div class="section" title="2.&nbsp; Enhancement"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_enhance">2.&nbsp;
+            Enhancement
+        </h2></div></div></div><div class="toc"><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></div>
+        
+        <a class="indexterm" name="d5e12031"></a>
+        <a class="indexterm" name="d5e12033"></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" cellspacing="0" cellpadding="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" title="2.1.&nbsp; Enhancing at Build Time"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_enhance_build">2.1.&nbsp;
+                Enhancing at Build Time
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12050"></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" title="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.&nbsp; Enhancer Ant Task">Section&nbsp;1.2, &#8220;
+                Enhancer Ant Task
+            &#8221;</a>.
+                </p>
+            </div>
+            <div class="example"><a name="ref_guide_pc_enhance_enhancer"></a><p class="title"><b>Example&nbsp;5.1.&nbsp;
+                    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.&nbsp; Command Line Configuration">Section&nbsp;3, &#8220;
+            Command Line Configuration
+        &#8221;</a> ),
+along with the following flags:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
+                    <p>
+<code class="literal">-directory/-d &lt;output directory&gt;</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 &lt;true/t | false/f&gt;</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 &lt;true/t | false/f&gt;</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 &lt;true/t | false/f&gt;</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" 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.&nbsp; Persistent Class List">Section&nbsp;1, &#8220;
+            Persistent Class List
+        &#8221;</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" title="2.2.&nbsp; Enhancing JPA Entities on Deployment"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_enhance_runtime_container">2.2.&nbsp;
+                Enhancing JPA Entities on Deployment
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12095"></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" title="2.3.&nbsp; Enhancing at Runtime"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_enhance_runtime">2.3.&nbsp;
+                Enhancing at Runtime
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12103"></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.&nbsp; Persistent Class List">Section&nbsp;1, &#8220;
+            Persistent Class List
+        &#8221;</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"><a name="ref_guide_pc_enhance_runtime_ex"></a><p class="title"><b>Example&nbsp;5.2.&nbsp;
+                    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.&nbsp; Plugin Configuration">Section&nbsp;4, &#8220;
+            Plugin Configuration
+        &#8221;</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.&nbsp; Command Line Configuration">Section&nbsp;3, &#8220;
+            Command Line Configuration
+        &#8221;</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.&nbsp; Enhancing at Build Time">Section&nbsp;2.1, &#8220;
+                Enhancing at Build Time
+            &#8221;</a>:
+            </p>
+            <div class="itemizedlist"><ul class="itemizedlist" 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"><a name="ref_guide_pc_enhance_runtime_opt_ex"></a><p class="title"><b>Example&nbsp;5.3.&nbsp;
+                    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" title="2.4.&nbsp; Enhancing Dynamically at Runtime"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_enhance_dynamic">2.4.&nbsp;
+		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" 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" title="2.5.&nbsp; Omitting the OpenJPA enhancer"><div class="titlepage"><div><div><h3 class="title" id="ref_guide_pc_enhance_unenhanced_types">2.5.&nbsp;
+                Omitting the OpenJPA enhancer
+            </h3></div></div></div>
+            
+            <a class="indexterm" name="d5e12158"></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" 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" title="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.&nbsp;openjpa.RuntimeUnenhancedClasses">Section&nbsp;5.65, &#8220;openjpa.RuntimeUnenhancedClasses&#8221;</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">
+&lt;properties&gt; 
+    . . .
+    &lt;property name="openjpa.RuntimeUnenhancedClasses" value="supported"/&gt;
+    . . .
+&lt;properties&gt;
+</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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_interfaces.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;3.&nbsp;Managed Interfaces</td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_enhance.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain

Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_interfaces.html
==============================================================================
--- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_interfaces.html (added)
+++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_interfaces.html Wed May 14 22:22:23 2014
@@ -0,0 +1,42 @@
+<html><head>
+      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+   <title>3.&nbsp;Managed Interfaces</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.3 User's Guide"><link rel="up" href="ref_guide_pc.html" title="Chapter&nbsp;5.&nbsp; Persistent Classes"><link rel="prev" href="ref_guide_pc_enhance.html" title="2.&nbsp; Enhancement"><link rel="next" href="ref_guide_pc_oid.html" title="4.&nbsp; 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.&nbsp;Managed Interfaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_pc_enhance.html">Prev</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;5.&nbsp;
+        Persistent Classes
+    </th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_oid.html">Next</a></td></tr></table><hr></div><div class="section" title="3.&nbsp;Managed Interfaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_pc_interfaces">3.&nbsp;Managed Interfaces</h2></div></div></div>
+        
+        <a class="indexterm" name="d5e12193"></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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ref_guide_pc.html">Up</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ref_guide_pc_oid.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.&nbsp;
+            Enhancement
+        &nbsp;</td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;4.&nbsp;
+            Object Identity
+        </td></tr></table></div></body></html>
\ No newline at end of file

Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_pc_interfaces.html
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message