Author: buildbot
Date: Mon May 9 17:01:23 2016
New Revision: 987823
Log:
Staging update by buildbot for aries
Modified:
websites/staging/aries/trunk/content/ (props changed)
websites/staging/aries/trunk/content/modules/tx-control/advancedResourceProviders.html
websites/staging/aries/trunk/content/modules/tx-control/advancedScopes.html
Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon May 9 17:01:23 2016
@@ -1 +1 @@
-1742224
+1743006
Modified:
websites/staging/aries/trunk/content/modules/tx-control/advancedResourceProviders.html
==============================================================================
---
websites/staging/aries/trunk/content/modules/tx-control/advancedResourceProviders.html
(original)
+++
websites/staging/aries/trunk/content/modules/tx-control/advancedResourceProviders.html
Mon May 9 17:01:23 2016
@@ -277,7 +277,128 @@ h2:hover > .headerlink, h3:hover > .head
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
-<h1 id="todo">TODO<a class="headerlink" href="#todo" title="Permanent
link">¶</a></h1></div>
+<h1 id="making-your-own-resource-provider">Making your own Resource Provider<a
class="headerlink" href="#making-your-own-resource-provider" title="Permanent
link">¶</a></h1>
+<p>The <code>TransactionControl</code> service is based around the use of
<code>ResourceProvider</code>
+instances. When combined the client receives a thread-safe resource instance
that they can use.</p>
+<p>Resource Provider implementations already exist for <a
href="localJDBC.html">JDBC</a>, <a href="xaJDBC.html">XA JDBC</a>, <a
href="localJPA.html">JPA</a> and <a href="xaJPA.html">XA JPA</a></p>
+<h2 id="create-an-interface">Create an interface<a class="headerlink"
href="#create-an-interface" title="Permanent link">¶</a></h2>
+<p>If you need to create your own Resource Provider then you should define a
sub-interface which declares the
+type of the resource. This allows clients type-safe access to the resources,
and makes it easier to identify
+the right Resource Provider at runtime.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span
class="n">interface</span> <span class="n">MyCustomResourceProvider</span>
<span class="n">extends</span>
+ <span class="n">ResourceProvider</span><span
class="o"><</span><span class="n">MyCustomResource</span><span
class="o">></span> <span class="p">{}</span>
+</pre></div>
+
+
+<h2 id="create-an-implementation">Create an implementation<a
class="headerlink" href="#create-an-implementation" title="Permanent
link">¶</a></h2>
+<p>The implementation of a ResourceProvider should return a thread-safe
delegating proxy. This may be a
+dynamic proxy or a static one. The proxy delegates to the real resource, and
is responsible for ensuring
+that the thread consistently accesses the same physical resource throughout
the scope. Note that even
+when multiple proxies are created they should share the same physical resource
throughout the life of the
+context.</p>
+<h3 id="lifecycle-first-access">Lifecycle - first access<a class="headerlink"
href="#lifecycle-first-access" title="Permanent link">¶</a></h3>
+<p>Whenever the resource is accessed then it must check to see whether it has
already been accessed
+within the current scope. If not then a resource should be selected and
associated with the scope. This
+physical resource must then be used for the rest of the scope.</p>
+<p>Note that if there is no active scope when the resource is accessed then
the resource access should
+fail with a TransactionException.</p>
+<div class="codehilite"><pre><span class="cm">/**</span>
+<span class="cm"> * A resource method</span>
+<span class="cm"> */</span>
+<span class="p">@</span><span class="n">Override</span>
+<span class="n">public</span> <span class="n">boolean</span> <span
class="n">doSomething</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span
class="o">!</span><span class="n">txControl</span><span class="p">.</span><span
class="n">activeScope</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">throw</span> <span class="k">new</span> <span
class="n">TransactionException</span><span class="p">(</span><span
class="s">"There is no scope currently active"</span><span
class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="c1">// Locate, or create and associate</span>
+ <span class="n">MyCustomResource</span> <span class="n">delegate</span>
<span class="o">=</span> <span class="n">locateDelegate</span><span
class="p">(</span><span class="n">txControl</span><span class="p">.</span><span
class="n">getCurrentContext</span><span class="p">());</span>
+
+ <span class="k">return</span> <span class="n">delegate</span><span
class="p">.</span><span class="n">doSomething</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="lifecycle-enlisting">Lifecycle - enlisting<a class="headerlink"
href="#lifecycle-enlisting" title="Permanent link">¶</a></h3>
+<p>If a transaction is active then the resource should enlist with it when it
is first used. If the resource is
+usable with XA transactions then it should register an XAResource.</p>
+<div class="codehilite"><pre><span class="n">private</span> <span
class="n">MyCustomResource</span> <span class="n">locateDelegate</span><span
class="p">(</span><span class="n">TransactionContext</span> <span
class="n">context</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MyCustomResource</span> <span class="n">resource</span>
<span class="p">=</span> <span class="n">findExisting</span><span
class="p">(</span><span class="n">context</span><span class="p">);</span>
+
+ <span class="k">if</span><span class="p">(</span><span
class="n">resource</span> !<span class="p">=</span> <span
class="n">null</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">resource</span> <span class="p">=</span> <span
class="n">getNewDelegate</span><span class="p">(</span><span
class="n">context</span><span class="p">);</span>
+
+ <span class="k">if</span><span class="p">(</span><span
class="n">context</span><span class="p">.</span><span
class="n">activeTransaction</span><span class="p">())</span> <span
class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span
class="n">context</span><span class="p">.</span><span
class="n">supportsXA</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">context</span><span class="p">.</span><span
class="n">registerXAResource</span><span class="p">(</span><span
class="n">resource</span><span class="p">.</span><span
class="n">getXAResource</span><span class="p">());</span>
+ <span class="p">}</span> <span class="k">else</span> <span
class="p">{</span>
+ <span class="n">throw</span> <span class="n">new</span> <span
class="n">TransactionException</span><span class="p">(</span>"<span
class="n">The</span> <span class="n">transaction</span> <span
class="n">does</span> <span class="n">not</span> <span class="n">support</span>
<span class="n">XA</span> <span class="n">resources</span>"<span
class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="o">//</span> <span class="n">Other</span> <span
class="n">resource</span> <span class="n">preparation</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="n">resource</span><span
class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Local resources are similar, but they register a LocalResource, not an
XAResource.</p>
+<div class="codehilite"><pre><span class="n">private</span> <span
class="n">MyCustomResource</span> <span class="n">locateDelegate</span><span
class="p">(</span><span class="n">TransactionContext</span> <span
class="n">context</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MyCustomResource</span> <span class="n">resource</span>
<span class="p">=</span> <span class="n">findExisting</span><span
class="p">(</span><span class="n">context</span><span class="p">);</span>
+
+ <span class="k">if</span><span class="p">(</span><span
class="n">resource</span> !<span class="p">=</span> <span
class="n">null</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">resource</span> <span class="p">=</span> <span
class="n">getNewDelegate</span><span class="p">(</span><span
class="n">context</span><span class="p">);</span>
+
+ <span class="k">if</span><span class="p">(</span><span
class="n">context</span><span class="p">.</span><span
class="n">activeTransaction</span><span class="p">())</span> <span
class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span
class="n">context</span><span class="p">.</span><span
class="n">supportsLocal</span><span class="p">())</span> <span
class="p">{</span>
+ <span class="n">context</span><span class="p">.</span><span
class="n">registerLocalResource</span><span class="p">(</span><span
class="n">resource</span><span class="p">.</span><span
class="n">getLocalesource</span><span class="p">());</span>
+ <span class="p">}</span> <span class="k">else</span> <span
class="p">{</span>
+ <span class="n">throw</span> <span class="n">new</span> <span
class="n">TransactionException</span><span class="p">(</span>"<span
class="n">The</span> <span class="n">transaction</span> <span
class="n">does</span> <span class="n">not</span> <span class="n">support</span>
<span class="n">Local</span> <span class="n">resources</span>"<span
class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="o">//</span> <span class="n">Other</span> <span
class="n">resource</span> <span class="n">preparation</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="n">resource</span><span
class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="lifecycle-tidying-up">Lifecycle - Tidying up<a class="headerlink"
href="#lifecycle-tidying-up" title="Permanent link">¶</a></h3>
+<p>In addition to registering with an active transaction the resource should
also register for cleanup at the end
+of the scope. This may involve closing the physical resource, or returning it
to a pool.</p>
+<div class="codehilite"><pre><span class="c1">// Other resource
preparation</span>
+
+<span class="k">context</span><span class="p">.</span><span
class="n">postCompletion</span><span class="p">(</span><span class="n">s</span>
<span class="o">-></span> <span class="n">resource</span><span
class="p">.</span><span class="k">release</span><span class="p">());</span>
+</pre></div>
+
+
+<h2 id="other-things-to-look-out-for">Other things to look out for...<a
class="headerlink" href="#other-things-to-look-out-for" title="Permanent
link">¶</a></h2>
+<ol>
+<li>
+<p>A client must have a friendly way to access the ResourceProvider. This may
be directly via the OSGi Service
+Registry or via a factory service of some kind.</p>
+</li>
+<li>
+<p>A resource must remain valid throughout a scope, therefore clients should
not be able to close or return the
+resource by making calls on the thread-safe proxy. Typically calls to close
should be a silent no-op (the
+actual close will occur when the scope ends).</p>
+</li>
+<li>
+<p>When a transaction is active clients must not be able to manually commit or
rollback the resource.
+Methods like <code>commit</code>, <code>rollback</code> and
<code>setRollbackOnly</code> must
+fail with a TransactionException indicating the incorrect usage. This is
different from <code>close</code>
+behaviour because unlike deferring a <code>close</code> ignoring a
<code>rollback</code> results in a
+different overall result from the client's perspective.</p>
+</li>
+<li>
+<p>Resources must not rely on the Transaction Control service recognising
duplicate enlistments. A resource
+should be enlisted at most once.</p>
+</li>
+</ol></div>
<!-- Content -->
</td>
</tr>
Modified:
websites/staging/aries/trunk/content/modules/tx-control/advancedScopes.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/advancedScopes.html
(original)
+++ websites/staging/aries/trunk/content/modules/tx-control/advancedScopes.html
Mon May 9 17:01:23 2016
@@ -277,7 +277,56 @@ h2:hover > .headerlink, h3:hover > .head
visibility: hidden;
}
h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
-<h1 id="todo">TODO<a class="headerlink" href="#todo" title="Permanent
link">¶</a></h1></div>
+<h1 id="advanced-scope-control">Advanced Scope control<a class="headerlink"
href="#advanced-scope-control" title="Permanent link">¶</a></h1>
+<p>There are a number of useful ways to interact with the scopes created by
the Transaction Control Service</p>
+<h2 id="determining-the-current-scope">Determining the current scope<a
class="headerlink" href="#determining-the-current-scope" title="Permanent
link">¶</a></h2>
+<p>The Transaction Control Service has methods which can be used to work out
whether a scope is in effect:</p>
+<ul>
+<li>
+<p><code>txControl.activeScope();</code> - When <code>true</code> there is a
scope in effect and resources can be
+accessed. The scope may, or may not, be transactional. When false there is no
current scope and
+<code>txControl.getCurrentContext();</code> will return <code>null</code>.</p>
+</li>
+<li>
+<p><code>txControl.activeTransaction()</code> - When <code>true</code> there
is a transactional scope in
+effect and resources can be accessed transactionally. When false there may, or
may not, be a "No Transaction"
+scope in effect.</p>
+</li>
+</ul>
+<p>Note that <code>assert txControl.activeTransaction();</code> can be used to
enforce the presence of a
+transaction. This is equivalent to a "Mandatory" transaction in Spring or Java
EE.</p>
+<h2 id="avoiding-rollback">Avoiding rollback<a class="headerlink"
href="#avoiding-rollback" title="Permanent link">¶</a></h2>
+<p>When setting up a transaction certain exception types can be marked as not
triggering rollback:</p>
+<div class="codehilite"><pre><span class="n">txControl</span><span
class="p">.</span><span class="n">build</span><span class="p">()</span>
+ <span class="p">.</span><span class="n">noRollbackFor</span><span
class="p">(</span><span class="n">MyCustomException</span><span
class="p">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="p">.</span><span class="n">required</span><span
class="p">(()</span> <span class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">A</span> <span
class="n">MyCustomException</span> <span class="n">thrown</span> <span
class="n">here</span> <span class="n">will</span> <span class="n">not</span>
<span class="n">trigger</span> <span class="n">rollback</span>
+ <span class="p">});</span>
+</pre></div>
+
+
+<h2 id="nesting-a-transaction">Nesting a transaction<a class="headerlink"
href="#nesting-a-transaction" title="Permanent link">¶</a></h2>
+<p>Nesting a Transaction can easily be managed using
<code>requiresNew()</code></p>
+<div class="codehilite"><pre><span class="n">txControl</span><span
class="p">.</span><span class="n">required</span><span class="p">(()</span>
<span class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Do</span> <span
class="n">some</span> <span class="n">work</span><span class="p">...</span>
+
+ <span class="k">return</span> <span class="n">txControl</span><span
class="p">.</span><span class="n">requiresNew</span><span class="p">(()</span>
<span class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Do</span> <span
class="n">some</span> <span class="n">more</span> <span class="n">work</span>
+ <span class="p">});</span>
+ <span class="p">});</span>
+</pre></div>
+
+
+<h2 id="suspending-a-transaction">Suspending a transaction<a
class="headerlink" href="#suspending-a-transaction" title="Permanent
link">¶</a></h2>
+<p>Suspending a Transaction can easily be managed using
<code>notSupported()</code></p>
+<div class="codehilite"><pre><span class="n">txControl</span><span
class="p">.</span><span class="n">required</span><span class="p">(()</span>
<span class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Do</span> <span
class="n">some</span> <span class="n">work</span><span class="p">...</span>
+
+ <span class="k">return</span> <span class="n">txControl</span><span
class="p">.</span><span class="n">notSupported</span><span class="p">(()</span>
<span class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Do</span> <span
class="n">some</span> <span class="n">more</span> <span class="n">work</span>
+ <span class="p">});</span>
+ <span class="p">});</span>
+</pre></div></div>
<!-- Content -->
</td>
</tr>
