59 lines
16 KiB
HTML
59 lines
16 KiB
HTML
<!doctype html><html lang=en class="js csstransforms3d"><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=generator content="Hugo 0.80.0"><meta name=description content="Strolch is a parameterized framework for use on servers and IoT"><meta name=author content="Strolch"><link rel=icon href=/favicon.ico type=image/ico><title>Transactions - Strolch</title><link href=/css/nucleus.css?1626091328 rel=stylesheet><link href=/css/fontawesome-all.min.css?1626091328 rel=stylesheet><link href=/css/hybrid.css?1626091328 rel=stylesheet><link href=/css/featherlight.min.css?1626091328 rel=stylesheet><link href=/css/perfect-scrollbar.min.css?1626091328 rel=stylesheet><link href=/css/auto-complete.css?1626091328 rel=stylesheet><link href=/css/atom-one-dark-reasonable.css?1626091328 rel=stylesheet><link href=/css/theme.css?1626091328 rel=stylesheet><link href=/css/hugo-theme.css?1626091328 rel=stylesheet><link href=/css/theme-green.css?1626091328 rel=stylesheet><script src=/js/jquery-3.3.1.min.js?1626091328></script><style>:root #header+#content>#left>#rlblock_left{display:none!important}</style></head><body data-url=/documentation/transactions/><nav id=sidebar><div id=header-wrapper><div id=header><a id=logo href=/><img src=/logo.png></a></div><div class=searchbox><label for=search-by><i class="fas fa-search"></i></label><input data-search-input id=search-by type=search placeholder=Search...>
|
|
<span data-search-clear><i class="fas fa-times"></i></span></div><script type=text/javascript src=/js/lunr.min.js?1626091328></script><script type=text/javascript src=/js/auto-complete.js?1626091328></script><script type=text/javascript>var baseurl="https:\/\/strolch.li\/";</script><script type=text/javascript src=/js/search.js?1626091328></script></div><section id=homelinks><ul><li><a class=padding href=/><i class="fas fa-home"></i>Home</a></li></ul></section><div class=highlightable><ul class=topics><li data-nav-id=/api/ title=API class=dd-item><a href=/api/>API</a></li><li data-nav-id=/history/ title=History class=dd-item><a href=/history/>History</a></li><li data-nav-id=/documentation/ title=Documentation class="dd-item
|
|
parent"><a href=/documentation/>Documentation</a><ul><li data-nav-id=/documentation/architecture/ title=Architecture class=dd-item><a href=/documentation/architecture/>Architecture</a></li><li data-nav-id=/documentation/model/ title=Model class=dd-item><a href=/documentation/model/>Model</a></li><li data-nav-id=/documentation/do-and-donts/ title="Do and Don't" class=dd-item><a href=/documentation/do-and-donts/>Do and Don't</a></li><li data-nav-id=/documentation/runtime-configuration/ title="Runtime Configuration" class=dd-item><a href=/documentation/runtime-configuration/>Runtime Configuration</a></li><li data-nav-id=/documentation/realms/ title=Realms class=dd-item><a href=/documentation/realms/>Realms</a></li><li data-nav-id=/documentation/components/ title=Components class=dd-item><a href=/documentation/components/>Components</a></li><li data-nav-id=/documentation/services-and-commands/ title="Services and Commands" class=dd-item><a href=/documentation/services-and-commands/>Services and Commands</a></li><li data-nav-id=/documentation/searches/ title=Searches class=dd-item><a href=/documentation/searches/>Searches</a></li><li data-nav-id=/documentation/queries/ title=Queries class=dd-item><a href=/documentation/queries/>Queries</a></li><li data-nav-id=/documentation/transactions/ title=Transactions class="dd-item active"><a href=/documentation/transactions/>Transactions</a></li><li data-nav-id=/documentation/policies/ title=Policies class=dd-item><a href=/documentation/policies/>Policies</a></li><li data-nav-id=/documentation/observers/ title=Observers class=dd-item><a href=/documentation/observers/>Observers</a></li><li data-nav-id=/documentation/versioning/ title=Versioning class=dd-item><a href=/documentation/versioning/>Versioning</a></li><li data-nav-id=/documentation/reports/ title=Reports class=dd-item><a href=/documentation/reports/>Reports</a></li><li data-nav-id=/documentation/priviles/ title=Privileges class=dd-item><a href=/documentation/priviles/>Privileges</a></li></ul></li><li data-nav-id=/plc/ title=PLC class=dd-item><a href=/plc/>PLC</a><ul><li data-nav-id=/plc/architecture/ title=Architecture class=dd-item><a href=/plc/architecture/>Architecture</a></li><li data-nav-id=/plc/example-set-up/ title="Example Set-Up" class=dd-item><a href=/plc/example-set-up/>Example Set-Up</a></li></ul></li><li data-nav-id=/tutorial/ title=Tutorial class=dd-item><a href=/tutorial/>Tutorial</a><ul><li data-nav-id=/tutorial/configuration/ title=Configuration class=dd-item><a href=/tutorial/configuration/>Configuration</a></li><li data-nav-id=/tutorial/model/ title=Model class=dd-item><a href=/tutorial/model/>Model</a></li><li data-nav-id=/tutorial/crud-book/ title="CRUD Book" class=dd-item><a href=/tutorial/crud-book/>CRUD Book</a></li></ul></li><li data-nav-id=/download/ title=Download class=dd-item><a href=/download/>Download</a></li><li data-nav-id=/development/ title=Development class=dd-item><a href=/development/>Development</a></li></ul><section id=shortcuts><h3>More</h3><ul><li><a class=padding href=https://strolch.li/tags><i class="fas fa-tags"></i>Tags</a></li><li><a class=padding href=https://github.com/strolch-li><i class="fab fa-github"></i>GitHub project</a></li></ul></section><section id=footer><p>Built with <a href=https://github.com/matcornic/hugo-theme-learn><i class="fas fa-heart"></i></a>from <a href=https://getgrav.org>Grav</a> and <a href=https://gohugo.io/>Hugo</a></p></section></div></nav><section id=body><div id=overlay></div><div class="padding highlightable"><div><div id=top-bar><div id=top-github-link><a class=github-link title="Edit this page" href=https://github.com/Pi4J/pi4j.github.io/tree/main/contentdocumentation/transactions.md target=blank><i class="fas fa-code-branch"></i><span id=top-github-link-text>Edit this page</span></a></div><div id=breadcrumbs itemscope itemtype=http://data-vocabulary.org/Breadcrumb><span id=sidebar-toggle-span><a href=# id=sidebar-toggle data-sidebar-toggle><i class="fas fa-bars"></i></a></span><span id=toc-menu><i class="fas fa-list-alt"></i></span><span class=links><a href=/>Strolch Overview</a> > <a href=/documentation/>Documentation</a> > Transactions</span></div><div class=progress><div class=wrapper><nav id=TableOfContents><ul><li><a href=#transactions>Transactions</a></li></ul></nav></div></div></div></div><div id=head-tags></div><div id=body-inner><h1>Transactions</h1><h2 id=transactions>Transactions</h2><p>Strolch Transactions play a central role in a Strolch agent. A transaction is
|
|
opened for a realm, and grants access to the model of the agent. Transactions
|
|
are implemented as a Java <code>try-with-resources</code> by implementing
|
|
the <code>AutoCloseable</code>
|
|
interface. This makes it trivial to understand the scope of a transaction.</p><p>Transactions handle the following:</p><ul><li>Opening and closing database connections</li><li>Releasing locks to strolch elements, if <code>tx.lock(StrolchRootElement)</code> or
|
|
<code>tx.lock(Locator)</code> was called</li><li>Performing Commands by executing them in the added order, and validating them
|
|
first.</li><li>Exception handling</li><li>Auditing</li><li>Updating observers</li></ul><p>When a transaction is opened, it is by default read-only, i.e. does not perform
|
|
any commands when it is closed. Should the TX perform commands, then it is
|
|
important to call <code>tx.commitOnClose()</code>, but only at the end of the work, so that
|
|
exception handling can properly work if something goes wrong.</p><p><code>StrolchTransaction</code> offers a myriad of methods:</p><ul><li>find element by its <code>Locator</code></li><li>get methods for elements by type and id, or using a <code>StringParameter</code> or
|
|
<code>StringListParameter</code> references</li><li>methods to add, update or remove elements</li><li>assert privilege access</li><li>get a new element by its template</li><li>check if an element exists by type and id</li><li>get streams for elements</li><li>add commands for execution</li></ul><p>Transactions are opened by accessing the realm, but there are convenience
|
|
methods depending on the use-case:</p><ul><li>In Services: by calling one of the <code>openTx()</code>-methods</li><li>In Commands: Transactions are already open, use method <code>tx()</code> to get instance.</li><li>REST API: <code>RestfulStrolchComponent.openTx()</code></li></ul><div class="notices warning"><p>Note: don’t open a new TX inside a TX for the same realm!</p></div><p>Important is to always open the transaction as a <code>try-with-resource</code> block and to
|
|
define if the TX should commit, or not:</p><div class=highlight><pre style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-java data-lang=java><span style=color:#66d9ef>try</span> <span style=color:#f92672>(</span>StrolchTransaction tx <span style=color:#f92672>=</span> openTx<span style=color:#f92672>(...))</span> <span style=color:#f92672>{</span>
|
|
|
|
<span style=color:#75715e>// read lock our object
|
|
</span><span style=color:#75715e></span> Locator ferrariLoc <span style=color:#f92672>=</span> Resource<span style=color:#f92672>.</span><span style=color:#a6e22e>locatorFor</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"ferrari"</span><span style=color:#f92672>);</span>
|
|
tx<span style=color:#f92672>.</span><span style=color:#a6e22e>lock</span><span style=color:#f92672>(</span>ferrariLoc<span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// find a car by locator
|
|
</span><span style=color:#75715e></span> Resource ferrari <span style=color:#f92672>=</span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>findElement</span><span style=color:#f92672>(</span>ferrariLoc<span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// get a car by ID
|
|
</span><span style=color:#75715e></span> Resource opel <span style=color:#f92672>=</span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>getResourceBy</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"opel"</span><span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// modify ball
|
|
</span><span style=color:#75715e></span> opel<span style=color:#f92672>.</span><span style=color:#a6e22e>setName</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Opel Corsa"</span><span style=color:#f92672>);</span>
|
|
tx<span style=color:#f92672>.</span><span style=color:#a6e22e>update</span><span style=color:#f92672>(</span>opel<span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// get by string reference
|
|
</span><span style=color:#75715e></span> StringParameter ownerP <span style=color:#f92672>=</span> ferrari<span style=color:#f92672>.</span><span style=color:#a6e22e>getParameter</span><span style=color:#f92672>(</span><span style=color:#e6db74>"relations"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"owner"</span><span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
Resource owner <span style=color:#f92672>=</span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>getResourceBy</span><span style=color:#f92672>(</span>ownerP<span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// get by string list reference
|
|
</span><span style=color:#75715e></span> StringListParameter previousOwnersP <span style=color:#f92672>=</span> opel<span style=color:#f92672>.</span><span style=color:#a6e22e>getParameter</span><span style=color:#f92672>(</span><span style=color:#e6db74>"relations"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"previousOwners"</span><span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
List<span style=color:#f92672><</span>Resource<span style=color:#f92672>></span> previousOwners <span style=color:#f92672>=</span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>getResourcesBy</span><span style=color:#f92672>(</span>previousOwnersP<span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// check resource exists
|
|
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> <span style=color:#f92672>(</span>tx<span style=color:#f92672>.</span><span style=color:#a6e22e>hasResource</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"audi"</span><span style=color:#f92672>))</span> <span style=color:#f92672>{</span>
|
|
Resource audi <span style=color:#f92672>=</span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>getResourceBy</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car"</span><span style=color:#f92672>,</span> <span style=color:#e6db74>"audi"</span><span style=color:#f92672>,</span> <span style=color:#66d9ef>true</span><span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// assert has privilege to remove a car
|
|
</span><span style=color:#75715e></span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>assertHasPrivilege</span><span style=color:#f92672>(</span>Operation<span style=color:#f92672>.</span><span style=color:#a6e22e>REMOVE</span><span style=color:#f92672>,</span> audi<span style=color:#f92672>);</span>
|
|
|
|
<span style=color:#75715e>// remove the car
|
|
</span><span style=color:#75715e></span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>remove</span><span style=color:#f92672>(</span>audi<span style=color:#f92672>);</span>
|
|
<span style=color:#f92672>}</span>
|
|
|
|
<span style=color:#75715e>// iterate all cars
|
|
</span><span style=color:#75715e></span> tx<span style=color:#f92672>.</span><span style=color:#a6e22e>streamResources</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car"</span><span style=color:#f92672>).</span><span style=color:#a6e22e>forEach</span><span style=color:#f92672>(</span>car <span style=color:#f92672>-></span> <span style=color:#f92672>{</span>
|
|
logger<span style=color:#f92672>.</span><span style=color:#a6e22e>info</span><span style=color:#f92672>(</span><span style=color:#e6db74>"Car: "</span> <span style=color:#f92672>+</span> car<span style=color:#f92672>.</span><span style=color:#a6e22e>getId</span><span style=color:#f92672>());</span>
|
|
<span style=color:#f92672>});</span>
|
|
|
|
<span style=color:#75715e>// commit if TX was changed
|
|
</span><span style=color:#75715e></span> <span style=color:#66d9ef>if</span> <span style=color:#f92672>(</span>tx<span style=color:#f92672>.</span><span style=color:#a6e22e>needsCommit</span><span style=color:#f92672>())</span>
|
|
tx<span style=color:#f92672>.</span><span style=color:#a6e22e>commitOnClose</span><span style=color:#f92672>();</span>
|
|
<span style=color:#f92672>}</span>
|
|
</code></pre></div><footer class=footline></footer></div></div><div id=navigation><a class="nav nav-prev" href=/documentation/queries/ title=Queries><i class="fa fa-chevron-left"></i></a><a class="nav nav-next" href=/documentation/policies/ title=Policies style=margin-right:0><i class="fa fa-chevron-right"></i></a></div></section><div style=left:-1000px;overflow:scroll;position:absolute;top:-1000px;border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px><div style=border:none;box-sizing:content-box;height:200px;margin:0;padding:0;width:200px></div></div><script src=/js/clipboard.min.js?1626091328></script><script src=/js/perfect-scrollbar.min.js?1626091328></script><script src=/js/perfect-scrollbar.jquery.min.js?1626091328></script><script src=/js/jquery.sticky.js?1626091328></script><script src=/js/featherlight.min.js?1626091328></script><script src=/js/highlight.pack.js?1626091328></script><script>hljs.initHighlightingOnLoad();</script><script src=/js/modernizr.custom-3.6.0.js?1626091328></script><script src=/js/learn.js?1626091328></script><script src=/js/hugo-learn.js?1626091328></script><script src=/mermaid/mermaid.js?1626091328></script><script>mermaid.initialize({startOnLoad:true});</script></body></html> |