cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [CONF] Apache Cayenne Documentation > Guide to 3.0 Features
Date Sun, 25 Oct 2009 10:37:00 GMT
    <base href="">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=CAYDOC&amp;forWysiwyg=true"
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="">Guide
to 3.0 Features</a></h2>
     <h4>Page <b>edited</b> by             <a href="">Andrus
     <div class="notificationGreySide">
         <p>This page highlights the new features and changes introduced in 3.0 release,
roughly corresponding to the latest released milestone. It is a high level overview and as
such is by no means complete. Consult RELEASE-NOTES.txt file included in each release for
the full list of changes.</p>

	<li><a href="#Guideto3.0Features-DistributionContentsStructure">Distribution
Contents Structure</a></li>
	<li><a href="#Guideto3.0Features-CayenneJPAProvider">Cayenne JPA Provider</a></li>
	<li><a href="#Guideto3.0Features-ObjectRelationalMapping">Object Relational Mapping</a></li>
	<li><a href="#Guideto3.0Features-CayennePersistenceAPI">Cayenne Persistence API</a></li>
	<li><a href="#Guideto3.0Features-RemoteObjectPersistence">Remote Object Persistence</a></li>
	<li><a href="#Guideto3.0Features-CayenneModeler">CayenneModeler</a></li>
	<li><a href="#Guideto3.0Features-DeploymentandRuntime">Deployment and Runtime</a></li>
	<li><a href="#Guideto3.0Features-Tools">Tools</a></li>

<h2><a name="Guideto3.0Features-DistributionContentsStructure"></a>Distribution
Contents Structure</h2>

	<li>There are a few changes in the contents of the distribution "lib" folder. For details
see <a href="/confluence/display/CAYDOC/JAR+Files+and+Dependencies" title="JAR Files and
Dependencies">this page</a>. Main Cayenne JAR is now called <tt>"cayenne-server-x.x.x.jar"</tt>.
We no longer ship the "fat" jar with dependencies. Instead dependencies are included in the
separate jars in <tt>"lib/third-party"</tt> distribution folder.</li>
	<li>CayenneModeler is located in the "bin" folder. Never mind the <tt>"lib/cayenne-modeler-x.x.x.jar"</tt>
- this is just an underlying Modeler <b>library</b>, used in "local JNDI" configuration
for instance, not the runnable application.</li>

<h2><a name="Guideto3.0Features-CayenneJPAProvider"></a>Cayenne JPA Provider</h2>

<p><em>Note that Cayenne JPA provider work has been frozen and it IS NOT included
in 3.0. If you have further questions or would like to give a hand with the JPA work, please
send a note to <a href="" rel="nofollow">developer
mailing list</a>.</em></p>

<h2><a name="Guideto3.0Features-ObjectRelationalMapping"></a>Object Relational

<h3><a name="Guideto3.0Features-KilledDerivedDbEntityConcept"></a>Killed
DerivedDbEntity Concept </h3>

<p>Stopped supporting <tt>DerivedDbEntity</tt> - its functionality (aggregate
queries) is achieved via EJBQL and other means.</p>

<h3><a name="Guideto3.0Features-DataMapDTDReplacedwithSchema"></a>DataMap
DTD Replaced with Schema</h3>

<p>A schema is now available <a href=""
rel="nofollow">here</a> for the DataMap XML format.</p>

<h3><a name="Guideto3.0Features-Embeddables"></a>Embeddables</h3>

<p>Added a new mapping artifact - Embeddable, that allows to map composite objects to
a single table. </p>

<h3><a name="Guideto3.0Features-FlattenedAttributes"></a>Flattened Attributes</h3>

<p>Just like with "flattened" relationships, now there is a way to map an ObjAttribute
that spans one or more DbRelationships and is mapped to a column of a joined table.</p>

<h3><a name="Guideto3.0Features-PersistingPrimitivesandaNumberofOtherSimpleProperties"></a>Persisting
Primitives and a Number of Other Simple Properties</h3>

<p>DataObjects are now allowed to have primitive properties, such as int, boolean, etc.
Also Cayenne can now persist the following extra simple property types: java.util.Calendar,
java.math.BigInteger,, char[], java.lang.Character, java.lang.Character[],

<h3><a name="Guideto3.0Features-SupportforToManyRelationshipMapsandCollections."></a>Support
for To-Many Relationship Maps and Collections.</h3>

<p>In addition to mapping a to-many relationship as a List, Cayenne now supports to-many
Maps (keyed by target object pk, or an arbitrary unique property), Sets and generic Collections.
Note that relationship maps is the only conceptually new type of relationships. Collection
and Set are not that different from the earlier List behavior (that was a Collection, and
just like Set ensured uniqueness of its objects).</p>

<h3><a name="Guideto3.0Features-Supportfor%22extended%22EnumsMapping"></a>Support
for "extended" Enums Mapping</h3>

<p>In addition to vanilla Java enums, Cayenne allows enums to provide a custom database
value for each enumerated instance by implementing <tt>org.apache.cayenne.ExtendedEnumeration</tt>.
This way a persistent value doesn't have to be tied to the enum Java name or position.</p>

<h3><a name="Guideto3.0Features-DbAttributeScaleandPrecision"></a>DbAttribute
Scale and Precision</h3>

<p>Changed DbAttribute "precision" property to "scale" (as it meant scale all along)
and added a separate "precision" attribute to track precision.</p>

<h2><a name="Guideto3.0Features-CayennePersistenceAPI"></a>Cayenne Persistence

<h3><a name="Guideto3.0Features-Java5Migration"></a>Java 5 Migration</h3>

<p>Cayenne now requires Java 5 or newer to run. This allowed us to start using generics,
enums and other Java 5 features.</p>

<h3><a name="Guideto3.0Features-ObjectContext"></a>ObjectContext</h3>

<p>While you can still use DataContext directly, we encourage you to avoid direct dependency
on DataContext throughout your code, and instead use <tt>org.apache.cayenne.ObjectContext</tt>
interface. E.g.:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">ObjectContext context = DataContext.createDataContext();</pre>

<p>This protects your code from the evolution of the underlying implementation, allows
you to customize context behavior by using interface wrappers. There are plans to update all
Cayenne API to return ObjectContext everywhere DataContext might be returned.</p>

<h3><a name="Guideto3.0Features-EJBQLQueries"></a>EJB QL Queries</h3>

<p>Never mind the "EJB" in the name. EJBQL queries are a powerful object query mechanism
similar to the one supported by the JPA specification. <a href="/confluence/display/CAYDOC/EJBQLQuery"
title="EJBQLQuery">EJBQLQuery</a> is a first-class citizen, just like SelectQuery.</p>

<h3><a name="Guideto3.0Features-SQLTemplateQueryImprovements"></a>SQLTemplate
Query Improvements</h3>

	<li><a href="/confluence/display/CAYDOC/Advanced+SQLTemplate" title="Advanced SQLTemplate">Significantly
simplified</a> the process for fetching DataObjects (vs. DataRows) via a SQLTemplate
query with <tt>'setColumnNamesCapitalization'</tt> method.</li>
	<li>Added support for <a href="/confluence/display/CAYDOC/SQLTemplate+Result+Mapping"
title="SQLTemplate Result Mapping">fetching scalar and mixed scalar/object results</a>
using <tt>SQLResultSetMapping</tt>.</li>

<h3><a name="Guideto3.0Features-EntityLifecycleCallbacks"></a>Entity Lifecycle

<p>Cayenne lifecycle callbacks are similar (but not identical) to callbacks defined
in the JPA specification. This is a feature that allows to perform custom operations at certain
points in the object lifecycle. For more details see <a href="/confluence/display/CAYDOC/Lifecycle+Callbacks"
title="Lifecycle Callbacks">this page</a>.</p>

<h3><a name="Guideto3.0Features-GeneralQueryImprovements"></a>General Query

	<li>Added support for fetch offset (complimentary to the existing "fetch limit").</li>

<h3><a name="Guideto3.0Features-DataContextChanges"></a>DataContext Changes</h3>

<p>Implemented <tt>DataContext.rollbackChangesLocally()</tt>. This was missing
in 2.0, limiting the operation of the nested DataContexts.</p>

<h3><a name="Guideto3.0Features-CacheManagement"></a>Cache Management</h3>

	<li><a href="/confluence/display/CAYDOC/Caching+and+Fresh+Data" title="Caching and
Fresh Data">pluggable query cache</a></li>
	<li>a notion of Query cache groups</li>
	<li>automated cache key management for standard queries</li>

<h3><a name="Guideto3.0Features-ExpressionImprovements"></a>Expression Improvements</h3>

	<li>Added missing DB expressions to ExpressionFactory.</li>
	<li><a href="/confluence/display/CAYDOC/Path+Expressions" title="Path Expressions">Added
support</a> for OUTER JOINS</li>
	<li>Added support for matching against TRUE and FALSE.</li>

<h3><a name="Guideto3.0Features-DatabaseIntegrationChanges%2FImprovements"></a>Database
Integration Changes/Improvements</h3>

	<li>Added support for "long" primary keys (vs. "int" PK used previously)</li>
	<li>Added adapter for <a href="" rel="nofollow">SQLite</a>
	<li>Added adapter for <a href="" rel="nofollow">H2</a>
	<li>Added stored procedure support on MySQL.</li>
	<li>Changed default table type on MySQL to InnoDB, added MySQL FK constraints support
in the Modeler.</li>
	<li>Turned on update query batching on SQL Server and Derby.</li>

<h3><a name="Guideto3.0Features-ClassGenerationImprovements"></a>Class Generation

	<li>Generating classes for DataMaps that contain type-safe methods for all mapped SelectQueries.</li>

<h3><a name="Guideto3.0Features-PrefetchingImprovements"></a>Prefetching

	<li>Joint prefetches are switched to OUTER joins, removing the major limitation to
their use.</li>
	<li>Disjoint to-many prefetches no longer have a limitation preventing their use if
a query qualifier spanned prefetched relationships.</li>

<h2><a name="Guideto3.0Features-RemoteObjectPersistence"></a>Remote Object

<h3><a name="Guideto3.0Features-ValidationcallbackssupportforROPObjectContext"></a>Validation
callbacks support for ROP ObjectContext</h3>
<p>Now object validation works the same way on the ROP client as it did on the server.</p>

<h3><a name="Guideto3.0Features-NestedcontextssupportforROPObjectContext"></a>Nested
contexts support for ROP ObjectContext</h3>
<p>Nested contexts can now be created for ROP contexts. Creation method is added to
ObjectContext interface.</p>

<h2><a name="Guideto3.0Features-CayenneModeler"></a>CayenneModeler</h2>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Upgrade Warning</b><br
/>Saving projects with CayenneModeler v.3.0 will render them uneditable with earlier versions
of the Modeler</td></tr></table></div>

<p>The Modeler underwent significant changes with the goal to improve usability and

	<li>Added copy/paste support</li>
	<li>Reworked ObjRelationship mapping dialog</li>
	<li>Added combo auto-completion</li>
	<li>Added a usable and good looking welcome screen</li>
	<li>Added contextual menus</li>
	<li>Added support for flattened attributes</li>
	<li>Added copy/paste support</li>
	<li>Added detection of project file changes on disk</li>
	<li>Added multi-item selection</li>
	<li>Added ability to specify password encryption mechanism</li>
	<li>Added ability to drag and drop cayenne.xml from the filesystem to the Modeler window
to open the project.</li>
	<li>Added support for to-many relationship collections mapping.</li>
	<li>Added "search" functionality</li>
	<li>Added lifecycle callback and listener mapping functionality.</li>
	<li>Added support for merging DataMap changes back to the database.</li>
	<li>Removed support for DerivedDbEntity</li>
	<li>Added confirmation dialog for delete actions</li>
	<li>Reopen Last Project on Startup</li>
	<li>Added progress/log view</li>
	<li>Added SQL syntax highlighting.</li>
	<li>Added EJBQL Query mapping capabilities, with synatx highlighting.</li>
	<li>Added support for quoting of SQL Identifiers</li>
	<li>The Modeler can be <a href="/confluence/display/CAYDOC/maven2-modeler" title="maven2-modeler">started
from Maven</a></li>
	<li>Added "Infer Relationships" operation to automatically create DbRelationships based
on PK/FK naming conventions.</li>
	<li>Added support for mapping Embeddable objects.</li>

<h2><a name="Guideto3.0Features-DeploymentandRuntime"></a>Deployment and

<h3><a name="Guideto3.0Features-ImprovedPerformance"></a>Improved Performance</h3>

	<li>Paginated query algorithm is changed, resulting in very significant performance
improvements on large data sets (this also improves ROP paginated query performance). This
includes faster query times and much smaller memory footprint of an unresolved list.</li>
	<li>Reduced the scope of lock on a shared cache during commit, that should result in
improved concurrency.</li>
	<li>Queries using disjoint to-many and joint to-one prefetching now work significantly
	<li>ROP new context creation speed is improved, as EntityResolver is cached on the
client after first retrieval.</li>
	<li>ROP uses a "diff compression" algorithm on commit, reducing the amount of data
passed around.</li>

<h3><a name="Guideto3.0Features-ImprovedMemoryManagement"></a>Improved Memory

	<li><a href="/confluence/display/CAYDOC/ObjectContext+Memory+Management" title="ObjectContext
Memory Management">Leak free ObjectContext</a></li>
	<li>Query lists are cached in an LRU map, so there's no indefinite memory growth when
using query caching.</li>

<h3><a name="Guideto3.0Features-LoggingSwitchedtocommonsloggingfromLog4J"></a>Logging
Switched to commons-logging from Log4J</h3>

<p>Cayenne no longer has a Log4J dependency. Instead it uses Jakarta commons-logging,
as described <a href="/confluence/display/CAYDOC/Configuring+Logging" title="Configuring
Logging">here</a>. Note that 2.0 Log4J configurations should continue to work, although
now it is a user responsibility to bootstrap Log4J - Cayenne will no longer do it for you.
E.g. you can do this on startup:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">org.apache.log4j.PropertyConfigurator.configure(<span class="code-quote">""</span>);</pre>

<h3><a name="Guideto3.0Features-OptionalQuotingofSQLIdentifiers"></a>Optional
Quoting of SQL Identifiers</h3>

<p>Cayenne now supports optional quoting of SQL identifiers in the generated SQL. This
has been a very popular request in the past. Identifier quoting can be turned on per DataMap
in the Modeler (look for "Quote SQL Identifiers" checkbox). This will allow to map column
names that contain spaces, non-ascii characters, reserved words, etc., i.e. the schemas that
could not be mapped with Cayenne before.</p>

<h3><a name="Guideto3.0Features-AbilitytoDetectMissing%2FPartialSchemaandAutoGenerateSchemainRuntime"></a>Ability
to Detect Missing/Partial Schema and Auto Generate Schema in Runtime</h3>

<p>DataNode has a new attribute in the Modeler - "Schema Update Strategy". This allows
to specify runtime behavior in regards to schema consistency checking. The default behavior
is "do nothing" (<tt>org.apache.cayenne.access.dbsync.SkipSchemaUpdateStrategy</tt>).
Alternatively Cayenne can create the schema if none is found or throw an exception if schema
inconsistencies are detected.</p>

<h2><a name="Guideto3.0Features-Tools"></a>Tools</h2>

	<li>Switched <tt>"cgen"</tt> to "version 1.2" of the template as a default
	<li>Support for classpath in <tt>"cdbgen"</tt>.</li>
	<li>The Modeler can be <a href="/confluence/display/CAYDOC/maven2-modeler" title="maven2-modeler">started
from Maven</a>, that can potentially help in aligning the Modeler version with the project
runtime Cayenne version.</li>

     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href=""
class="grey">Change Notification Preferences</a>

       <a href="">View
       <a href="">View
       <a href=";showCommentArea=true#addcomment">Add

View raw message