191 lines
7.1 KiB
HTML
191 lines
7.1 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="google-site-verification" content="CPhbjooaiTdROm7Vs4E7kuHZvBfkeLUtonGgcVUbTL8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="description" content="">
|
|
<meta name="author" content="">
|
|
<link rel="shortcut icon" href="ico/favicon.ico">
|
|
|
|
<title>Strolch: Transactions</title>
|
|
|
|
<!-- Bootstrap core CSS -->
|
|
<link href="css/bootstrap.min.css" rel="stylesheet">
|
|
|
|
<!-- Custom styles for this template -->
|
|
<link href="css/custom.css" rel="stylesheet">
|
|
|
|
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --><!--[if lt IE 9]>
|
|
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
|
|
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script><![endif]-->
|
|
</head>
|
|
<body>
|
|
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
|
|
<div class="container">
|
|
<div class="navbar-header">
|
|
<a class="navbar-brand" href="index.html">Strolch</a>
|
|
</div>
|
|
<div class="collapse navbar-collapse">
|
|
<ul class="nav navbar-nav">
|
|
<li><a href="index.html">Overview</a></li>
|
|
<li><a href="api.html">API</a></li>
|
|
<li class="active"><a href="documentation.html">Documentation</a></li>
|
|
<li><a href="tutorial.html">Tutorial</a></li>
|
|
<li><a href="downloads.html">Downloads</a></li>
|
|
<li><a href="development.html">Development</a></li>
|
|
<li><a href="blog.html">Blog</a></li>
|
|
</ul>
|
|
</div>
|
|
<!--/.nav-collapse -->
|
|
</div>
|
|
</div>
|
|
|
|
<div class="container">
|
|
|
|
<div class="page-header">
|
|
<h1 class="page-title">Documentation: Transactions</h1>
|
|
|
|
<p class="lead page-description">This page discusses Strolch Transactions.</p>
|
|
</div>
|
|
|
|
<div class="content">
|
|
|
|
<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. <b>Note:</b>
|
|
don't open a new TX inside a TX for the same realm!
|
|
</li>
|
|
<li>REST API: <code>RestfulStrolchComponent.openTx()</code></li>
|
|
</ul>
|
|
|
|
<p>Important is to always open the transaction as a try-with-resource block and to define if the TX should
|
|
commit, or not:</p>
|
|
<pre>
|
|
try (StrolchTransaction tx = openTx(...)) {
|
|
|
|
// read lock our object
|
|
Locator ferrariLoc = Resource.locatorFor("Car", "ferrari");
|
|
tx.lock(ferrariLoc);
|
|
|
|
// find a car by locator
|
|
Resource ferrari = tx.findElement(ferrariLoc);
|
|
|
|
// get a car by ID
|
|
Resource opel = tx.getResourceBy("Car", "opel", true);
|
|
|
|
// modify ball
|
|
opel.setName("Opel Corsa");
|
|
tx.update(opel);
|
|
|
|
// get by string reference
|
|
StringParameter ownerP = ferrari.getParameter("relations", "owner", true);
|
|
Resource owner = tx.getResourceBy(ownerP, true);
|
|
|
|
// get by string list reference
|
|
StringListParameter previousOwnersP = opel.getParameter("relations", "previousOwners", true);
|
|
List<Resource> previousOwners = tx.getResourcesBy(previousOwnersP, true);
|
|
|
|
// check resource exists
|
|
if (tx.hasResource("Car", "audi")) {
|
|
Resource audi = tx.getResourceBy("Car", "audi", true);
|
|
|
|
// assert has privilege to remove a car
|
|
tx.assertHasPrivilege(Operation.REMOVE, audi);
|
|
|
|
// remove the car
|
|
tx.remove(audi);
|
|
}
|
|
|
|
// iterate all cars
|
|
tx.streamResources("Car").forEach(car -> {
|
|
logger.info("Car: " + car.getId());
|
|
});
|
|
|
|
// commit if TX was changed
|
|
if (tx.needsCommit())
|
|
tx.commitOnClose();
|
|
}</pre>
|
|
|
|
|
|
<!-- content here -->
|
|
|
|
</div>
|
|
<!-- /.content -->
|
|
|
|
<div id="footer">
|
|
<div class="container">
|
|
<p class="text-muted">© Strolch / <a href="mailto:eitch@eitchnet.ch">Robert von Burg</a> / Hosting by
|
|
<a href="http://www.eitchnet.ch">eitchnet.ch</a></p>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
<!-- /.container -->
|
|
|
|
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
|
|
<!-- Include all compiled plugins (below), or include individual xsd as needed -->
|
|
<script src="js/bootstrap.min.js"></script>
|
|
|
|
<!-- Piwik -->
|
|
<script type="text/javascript">
|
|
var _paq = _paq || [];
|
|
_paq.push(['trackPageView']);
|
|
_paq.push(['enableLinkTracking']);
|
|
(function () {
|
|
var u = (("https:" == document.location.protocol) ? "https" : "http") + "://piwik.eitchnet.ch/";
|
|
_paq.push(['setTrackerUrl', u + 'piwik.php']);
|
|
_paq.push(['setSiteId', 2]);
|
|
var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
|
|
g.type = 'text/javascript';
|
|
g.defer = true;
|
|
g.async = true;
|
|
g.src = u + 'piwik.js';
|
|
s.parentNode.insertBefore(g, s);
|
|
})();
|
|
</script>
|
|
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt="" /></p></noscript>
|
|
<!-- End Piwik Code -->
|
|
|
|
</body>
|
|
</html>
|