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 > Obtaining DataContext
Date Sun, 20 Feb 2011 16:04: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/Obtaining+DataContext">Obtaining
DataContext</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~andrus">Andrus
Adamchik</a>
    </h4>
        <br/>
                         <h4>Changes (24)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{warning}TODO...
The API below looks different in 3.1{warning} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Depending
on deployment environment and application needs, Cayenne can be configured in a few different
ways to make DataContext instances available. This is discussed in detail in deployment chapter.
But basically it comes down to getting a hold of an instance of {{ServerRuntime}} and calling
{{getContext()}} on it as described below. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Depending
on deployment environment and application needs, Cayenne can be configured in a few different
ways to make DataContext instances available. This is discussed in detail in deployment chapter.
In this chapter we assume a properly deployed application and will concentrate on how to obtain
a DataContext for the database access. The following are the most common ways to achieve that:
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Obtaining a DataContext from the DI Runtime <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Creating DataContext on the Spot <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{code}ServerRuntime
runtime = ... <br>ObjectContext context = runtime.getContext(){code} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">A
new DataContext instance normally can be created using the following code: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Note
that every call to {{getContext()}} returns a new instance. Also note that it returns {{ObjectContext}}
(an interface implemented by {{DataContext}}). If you need to use DataContext API not declared
in ObjectContext, you may use a cast: <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{code}import
org.apache.cayenne.access.DataContext; <br>... <br>DataContext context = DataContext.createDataContext();{code}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{code}ServerRuntime
runtime = ... <br>DataContext context = (DataContext) runtime.getContext(){code} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">This
approach may be used in standalone applications, where the notion of a &quot;session&quot;
is user-defined. In web applications the correct instance of DataContext is usually bound
to a session or a request thread externally, and all that is needed is to retrieve it, as
discussed below. Creating a new DataContext for each request is not a recommended practice.
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">But
if you don&#39;t, we recommend to stick with ObjectContext in your code, as it makes the
code more flexible and portable to the future versions of Cayenne. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h3.
Retrieving Session-Bound DataContext in Web Applications <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
Retrieving Thread-Bound DataContext <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">A
web application can be configured to automatically create a new instance of DataContext for
each new HttpSession, and set it as a session attribute. Retrieving it from a session is done
with the following code: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">An
application can bind a context to a current execution thread (e.g. via {{CayenneFilter}} or
manually). Later on the code that needs DB access can retrieve this DataContext without making
any assumptions about the environment. This approach is universal and works in all types of
applications (web, standalone, etc.). Previously bound context can be retrieved by calling
{{BaseContext.getThreadObjectContext()}} static method. If no context was bound to the current
thread, this method throws IllegalStateException (same rules for casting ObjectContext to
DataContext as above apply) : <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{code}import
org.apache.cayenne.conf.ServletUtil; <br>import org.apache.cayenne.access.DataContext;
<br>... <br> <br>// assume this exists <br>HttpSession session; <br>DataContext
context = ServletUtil.getSessionContext(session);{code} <br> <br> <br>h3.
Retrieving Thread-Bound DataContext. <br> <br>An application can bind a DataContext
to a current execution thread. Later on the code that needs DB access can retrieve this DataContext
without making any assumptions about the environment. This approach is universal and works
in all types of applications (web, standalone, etc.). Previously bound DataContext can be
retrieved by calling {{DataContext.getThreadDataContext()}} static method. If no DataContext
was bound to the current thread, this method throws IllegalStateException: <br> <br>{code}import
org.apache.cayenne.access.DataContext; <br>... <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">{code}</span>//</span>
we are positive there is DataContext in the current thread, and do not want <br></td></tr>
            <tr><td class="diff-unchanged" >// to handle possible exception...
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">DataContext
context = DataContext.getThreadDataContext(); <br>{code} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">DataContext
context = (DataContext) BaseContext.getThreadObjectContext();{code} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-unchanged" >{code}import org.apache.cayenne.access.DataContext;
<br>... <br></td></tr>
            <tr><td class="diff-changed-lines" >// we want to handle the condition
of no thread <span class="diff-changed-words">context<span class="diff-added-chars"style="background-color:
#dfd;"> exist</span>...</span> <br></td></tr>
            <tr><td class="diff-unchanged" >try { <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
   DataContext context = DataContext.getThreadDataContext(); <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
   DataContext context = (DataContext) BaseContext.getThreadObjectContext(); <br></td></tr>
            <tr><td class="diff-unchanged" >} <br>catch(IllegalStateException
ex) { <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >    .... <br>}{code} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">
<br> <br>h3. Multiple DataDomains (Advanced) <br> <br>Cayenne can
be configured to support mass database hosting. This is a so-called Application Service Provider
(ASP) scenario. Basic architecture of such setup is a single application supporting multiple
databases (or more generally - data sources), each one with same or similar schema. Each data
source corresponds to an individual ASP &quot;customer&quot; using the system. Each
customer has a number of users that will log in to the system and are only allowed to view
data from their data source. <br> <br>This approach, though not required for most
normal applications, could be quiet common and powerful in some enterprise systems. To implement
it, each DataContext must be limited to access only a relevant subset of datasources. <br>
<br>Considering that behind the scenes a source of DataContext instances is an object
called DataDomain, Cayenne allows creation of multiple DataDomains per project. Each DataDomain
would support a single &quot;customer&quot;. Creation of DataContext in this case
is done using DataDomain name as a parameter: <br> <br>{code}import org.apache.cayenne.access.DataContext;
<br>... <br> <br>// domain name string is initialized depending on <br>//
the application logic. For instance it can be based <br>// on the logged in user&#39;s
company, etc. <br>String domainName = ...; <br>DataContext context = DataContext.createDataContext(domainName);{code}
<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>Depending on deployment environment and application needs, Cayenne can be
configured in a few different ways to make DataContext instances available. This is discussed
in detail in deployment chapter. But basically it comes down to getting a hold of an instance
of <tt>ServerRuntime</tt> and calling <tt>getContext()</tt> on it
as described below.</p>

<h3><a name="ObtainingDataContext-ObtainingaDataContextfromtheDIRuntime"></a>Obtaining
a DataContext from the DI Runtime</h3>

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

<p>Note that every call to <tt>getContext()</tt> returns a new instance.
Also note that it returns <tt>ObjectContext</tt> (an interface implemented by
<tt>DataContext</tt>). If you need to use DataContext API not declared in ObjectContext,
you may use a cast:</p>

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

<p>But if you don't, we recommend to stick with ObjectContext in your code, as it makes
the code more flexible and portable to the future versions of Cayenne.</p>

<h3><a name="ObtainingDataContext-RetrievingThreadBoundDataContext"></a>Retrieving
Thread-Bound DataContext</h3>

<p>An application can bind a context to a current execution thread (e.g. via <tt>CayenneFilter</tt>
or manually). Later on the code that needs DB access can retrieve this DataContext without
making any assumptions about the environment. This approach is universal and works in all
types of applications (web, standalone, etc.). Previously bound context can be retrieved by
calling <tt>BaseContext.getThreadObjectContext()</tt> static method. If no context
was bound to the current thread, this method throws IllegalStateException (same rules for
casting ObjectContext to DataContext as above apply) :</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-comment">// we are positive there is
DataContext in the current thread, and <span class="code-keyword">do</span> not
want
</span><span class="code-comment">// to handle possible exception...
</span>DataContext context = (DataContext) BaseContext.getThreadObjectContext();</pre>
</div></div>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">import</span> org.apache.cayenne.access.DataContext;
...
<span class="code-comment">// we want to handle the condition of no thread context exist...
</span><span class="code-keyword">try</span> {
    DataContext context = (DataContext) BaseContext.getThreadObjectContext();
}
<span class="code-keyword">catch</span>(IllegalStateException ex) {
    <span class="code-comment">// handle failure
</span>    ....
}</pre>
</div></div>
    </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/Obtaining+DataContext">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=10539&revisedVersion=7&originalVersion=6">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CAYDOC/Obtaining+DataContext?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message