cayenne-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Cayenne Documentation > Guide to 3.1 Features
Date Sun, 20 Feb 2011 16:35:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/1/_/styles/combined.css?spaceKey=CAYDOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CAYDOC/Guide+to+3.1+Features">Guide
to 3.1 Features</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~andrus">Andrus
Adamchik</a>
    </h4>
        <br/>
                         <h4>Changes (5)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Framework API <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">_<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">TODO...
</span>See</span> UPGRADE.txt for the full list of changes_ <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. Lifecycle Listener
Annotations <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
DataDomain support for DataChannelFilter <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Cayenne
now features a {{DataChannelFilter}} interface that allows to intercept and alter all DataChannel
traffic (i.e. selects and commits between a DataContext and DataDomain). It provides a chain
of command API very similar to servlet filters. Filters are widely used by &quot;{{cayenne-lifecyle}}&quot;
extensions and allow to build powerful custom object lifecycle-aware code. To install a filter,
the following API is used: <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{code}class
MyFilter implement DataChannelFilter { .. } <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">MyFilter
filter = new MyFilter(); <br>ServerRuntime runtime = .. <br>runtime.getDataDomain().addFilter(filter);{code}
<br> <br>Very often filters mark some of their own methods with lifecycle annotations
so that certain operations can be triggered by Cayenne inside the scope of filter&#39;s
{{onQuery()}} or {{onSync()}} methods. To ensure annotated methods are invoked, filter registration
should be combined with listener registration: <br> <br>{code}MyFilter filter
= new MyFilter(); <br>ServerRuntime runtime = .. <br>runtime.getDataDomain().addFilter(filter);
<br>runtime.getDataDomain().getEntityResolver().getCallbackRegistry().addListener(filter);
<br>// noticed that by default runtime.getDataDomain() is equivalent to runtime.getChannel(){code}
<br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. CayenneModeler <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>This page highlights the new features and changes introduced in 3.1 release.
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, and UPGRADE.txt for the upgrade
instructions.</p>

<ul>
	<li><a href="#Guideto3.1Features-DistributionContentsStructure">Distribution
Contents Structure</a></li>
	<li><a href="#Guideto3.1Features-CayenneConfiguration">Cayenne Configuration</a></li>
	<li><a href="#Guideto3.1Features-FrameworkAPI">Framework API</a></li>
	<li><a href="#Guideto3.1Features-CayenneModeler">CayenneModeler</a></li>
</ul>


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

<p>Cayenne distribution is made leaner and more modular:</p>

<ul>
	<li><tt>"cayenne-modeler.jar"</tt> is no longer included in the "lib" folder,
as it is no longer used for loading local JNDI overrides. Of course "CayenneModeler-the-app"
is still included.</li>
	<li>Ashwood library used for commit operation sorting is no longer a third-party dependency.
Instead a small subset of the relevant Ashwood classes got included in Cayenne core.</li>
	<li>The following helper modules are split away from Cayenne core: <tt>"cayenne-project"</tt>
and <tt>"cayenne-wocompat"</tt>. They are bundled in CayenneModeler, and are available
from the source distribution. They are not included as standalone jars in the binary distribution.</li>
</ul>


<h2><a name="Guideto3.1Features-CayenneConfiguration"></a>Cayenne Configuration</h2>

<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>The new DI-based bootstrap and
configuration approach is not API-compatible with earlier versions of Cayenne. Make sure you
read the UPGRADE.txt file for instructions how to upgrade the existing projects.</td></tr></table></div>

<h3><a name="Guideto3.1Features-DependencyInjectionContainer"></a>Dependency
Injection Container</h3>

<p>Cayenne 3.1 runtime stack is built around the ideas of Dependency Injection (DI),
making it extremely flexible and easy to extend. It bundles a small, flexible annotations-based
<a href="/confluence/display/CAYDOC/Dependency+Injection+Container" title="Dependency Injection
Container">DI container</a> to configure its services. The container provides DI
services and exposes Cayenne extension points, but does not interfere with other DI containers
that may be present in the application. I.e. it is invisible to the users who do not care
about advanced Cayenne customization.</p>

<h3><a name="Guideto3.1Features-BootstrappingCayenneinVariousEnvironments"></a>Bootstrapping
Cayenne in Various Environments</h3>

<p><em>TODO... For now read the UPGRADE.txt file and check the tutorials source
code for bootstrap examples.</em> Here is a simple example of starting a server-side
Cayenne stack:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>ServerRuntime runtime = new ServerRuntime("cayenne-UntitledDomain.xml");</pre>
</div></div>

<h3><a name="Guideto3.1Features-ConfiguringLocalDataSources%2CRemovalofJNDIHack"></a>Configuring
Local DataSources, Removal of JNDI Hack</h3>

<p>Cayenne 3.1 provides a property-based mechanism to override Modeler DataSource definitions,
regardless of whether they are driver configurations, JNDI, DBCP, etc. A quick configuration
example is shown below:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>-Dcayenne.jdbc.driver=com.mysql.jdbc.Driver -Dcayenne.jdbc.url=jdbc:mysql://localhost/mydb
\
-Dcayenne.jdbc.username=user -Dcayenne.jdbc.password=password</pre>
</div></div>

<p>For more details and configuration options see javadocs of <tt>org.apache.cayenne.configuration.server.PropertyDataSourceFactory</tt>.
</p>

<p>This feature supersedes what was formerly known as "JNDI hack", i.e. JNDI DataSource
failover load strategy based on CayenneModeler preferences database. The problem with JNDI
hack was unstable and frequently corrupted preferences database, and the need to include hsqldb
and cayenne-modeler jars in the runtime. </p>

<h2><a name="Guideto3.1Features-FrameworkAPI"></a>Framework API</h2>

<p><em>See UPGRADE.txt for the full list of changes</em></p>

<h3><a name="Guideto3.1Features-LifecycleListenerAnnotations"></a>Lifecycle
Listener Annotations</h3>

<p>Cayenne 3.1 features support for annotations on lifecycle listeners (but not yet
on entity callback methods) that simplifies registering listeners via API. Our experience
with Cayenne 3.0 shows that mapping listeners in the Modeler doesn't scale well to complex
applications, and 3.0 API for mapping the listeners is hard to use. In 3.1 you can annotate
listener methods and register multiple callback methods with a single call. </p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// declare a listener with annotated
methods
</span>class MyListener {
    @PostLoad(Entity1.class)
    @PostPersist(Entity1.class)
    void postLoad(<span class="code-object">Object</span> object) {
        ....
    }
}

<span class="code-comment">// register a listener
</span>ServerRuntime runtime = ..
MyListener listener = <span class="code-keyword">new</span> MyListener();
runtime.getChannel().getEntityResolver().getCallbackRegistry().addListener(listener);</pre>
</div></div>

<p>Moreover, unlike JPA annotations, Cayenne allows to attach a listener to a set of
entities not known to the listener upfront, but that are all annotated with some custom annotation:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">class MyListener {
    @PostLoad(entityAnnotations = CustomAnnotation.class)
    void postLoad(<span class="code-object">Object</span> object) {
        ....
    }
}</pre>
</div></div>


<h3><a name="Guideto3.1Features-DataDomainsupportforDataChannelFilter"></a>DataDomain
support for DataChannelFilter</h3>

<p>Cayenne now features a <tt>DataChannelFilter</tt> interface that allows
to intercept and alter all DataChannel traffic (i.e. selects and commits between a DataContext
and DataDomain). It provides a chain of command API very similar to servlet filters. Filters
are widely used by "<tt>cayenne-lifecyle</tt>" extensions and allow to build powerful
custom object lifecycle-aware code. To install a filter, the following API is used:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">class MyFilter implement DataChannelFilter { .. }

MyFilter filter = <span class="code-keyword">new</span> MyFilter();
ServerRuntime runtime = ..
runtime.getDataDomain().addFilter(filter);</pre>
</div></div>

<p>Very often filters mark some of their own methods with lifecycle annotations so that
certain operations can be triggered by Cayenne inside the scope of filter's <tt>onQuery()</tt>
or <tt>onSync()</tt> methods. To ensure annotated methods are invoked, filter
registration should be combined with listener registration:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">MyFilter filter = <span class="code-keyword">new</span>
MyFilter();
ServerRuntime runtime = ..
runtime.getDataDomain().addFilter(filter);
runtime.getDataDomain().getEntityResolver().getCallbackRegistry().addListener(filter);
<span class="code-comment">// noticed that by <span class="code-keyword">default</span>
runtime.getDataDomain() is equivalent to runtime.getChannel()</span></pre>
</div></div>

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

<h3><a name="Guideto3.1Features-JavaPreferencesAPI"></a>Java Preferences
API</h3>

<p>We got rid of HSQLDB-based preferences storage, and are using standard Java Preferences
API for the Modeler preferences. This solved a long-standing stability issue with Modeler
preferences. So no more lost user preferences.</p>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CAYDOC/Guide+to+3.1+Features">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=8552555&revisedVersion=12&originalVersion=11">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAYDOC/Guide+to+3.1+Features?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message