You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by bu...@apache.org on 2016/05/09 17:01:23 UTC
svn commit: r987823 - in /websites/staging/aries/trunk/content: ./
modules/tx-control/advancedResourceProviders.html
modules/tx-control/advancedScopes.html
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>