[Project] Extended documentation with policies and transactions
This commit is contained in:
parent
11e66fec06
commit
2fe9f74be8
|
@ -93,8 +93,6 @@ public class ModelQuery {
|
||||||
resources.addAll(tx.doQuery(query));
|
resources.addAll(tx.doQuery(query));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
tx.doNothingOnClose();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// do ordering
|
// do ordering
|
||||||
|
@ -151,8 +149,6 @@ public class ModelQuery {
|
||||||
orders.addAll(tx.doQuery(query));
|
orders.addAll(tx.doQuery(query));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
tx.doNothingOnClose();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// do ordering
|
// do ordering
|
||||||
|
@ -210,8 +206,6 @@ public class ModelQuery {
|
||||||
activities.addAll(tx.doQuery(query));
|
activities.addAll(tx.doQuery(query));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
tx.doNothingOnClose();
|
|
||||||
}
|
}
|
||||||
|
|
||||||
// do ordering
|
// do ordering
|
||||||
|
|
|
@ -62,9 +62,9 @@
|
||||||
<li><a href="documentation_components.html">Strolch Components</a></li>
|
<li><a href="documentation_components.html">Strolch Components</a></li>
|
||||||
<li><a href="documentation_services_and_commands.html">Strolch Services and Commands</a></li>
|
<li><a href="documentation_services_and_commands.html">Strolch Services and Commands</a></li>
|
||||||
<li><a href="documentation_queries.html">Strolch Queries</a></li>
|
<li><a href="documentation_queries.html">Strolch Queries</a></li>
|
||||||
<!--
|
|
||||||
<li><a href="documentation_transactions.html">Strolch Transactions</a></li>
|
<li><a href="documentation_transactions.html">Strolch Transactions</a></li>
|
||||||
<li><a href="documentation_policies.html">Strolch Policies</a></li>
|
<li><a href="documentation_policies.html">Strolch Policies</a></li>
|
||||||
|
<!--
|
||||||
<li><a href="documentation_privileges.html">Strolch Privileges</a></li>
|
<li><a href="documentation_privileges.html">Strolch Privileges</a></li>
|
||||||
<li><a href="documentation_observers.html">Strolch Observers</a></li>
|
<li><a href="documentation_observers.html">Strolch Observers</a></li>
|
||||||
<li><a href="documentation_versioning.html">Strolch Versioning</a></li>
|
<li><a href="documentation_versioning.html">Strolch Versioning</a></li>
|
||||||
|
|
|
@ -94,19 +94,21 @@
|
||||||
<p>In addition to the main parts, Strolch contains inherit capabilities, which gives Strolch unique features
|
<p>In addition to the main parts, Strolch contains inherit capabilities, which gives Strolch unique features
|
||||||
when compared to other Java Frameworks:</p>
|
when compared to other Java Frameworks:</p>
|
||||||
<ul>
|
<ul>
|
||||||
<li>Privileges → Strolch is user agnostic and any action, i.e. Service, Query, etc. is authorized
|
|
||||||
against the authenticated user.
|
|
||||||
</li>
|
|
||||||
<li>Transactions → Transactions handle locking/unlocking of objects, updating the model and are the
|
|
||||||
central API for the developer.
|
|
||||||
</li>
|
|
||||||
<li>Observers → modifications to the model are propagated to listeners using the observer pattern.</li>
|
|
||||||
<li>Versioning → modifications to objects are versioned and thus can be rolled back at a later time.
|
|
||||||
</li>
|
|
||||||
<li>Policies → Policies allow injecting different algorithms. All root elements can store Policy
|
<li>Policies → Policies allow injecting different algorithms. All root elements can store Policy
|
||||||
definitions, so that a service can delegate to a Policy and thus behave differently, depending on the
|
definitions, so that a service can delegate to a Policy and thus behave differently, depending on the
|
||||||
element being accessed.
|
element being accessed.
|
||||||
</li>
|
</li>
|
||||||
|
<li>Transactions → Transactions handle locking/unlocking of objects, updating the model and are the
|
||||||
|
central API for the developer.
|
||||||
|
</li>
|
||||||
|
<li>Privileges → Strolch is user agnostic and any action, i.e. Service, Query, etc. is authorized
|
||||||
|
against the authenticated user.
|
||||||
|
</li>
|
||||||
|
<li>Observers → modifications to the model are propagated to listeners using the observer pattern.</li>
|
||||||
|
<li>Audits → Every access (read, modify) of the model are audited</li>
|
||||||
|
<li>Versioning → modifications to objects are versioned and thus can be rolled back at a later time.
|
||||||
|
</li>
|
||||||
|
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,177 @@
|
||||||
|
<!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: Policies</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="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: Policies</h1>
|
||||||
|
|
||||||
|
<p class="lead page-description">This page discusses the Strolch policies</p>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="content">
|
||||||
|
|
||||||
|
<p>Policies are an integral part when writing business logic in Strolch. In many cases it would suffice to write
|
||||||
|
all such logic in <code>Services</code> and <code>Commands</code>, but as soon as behaviour can change,
|
||||||
|
depending on the element being accessed, then this would quickly lead to many if/else blocks.</p>
|
||||||
|
|
||||||
|
<p>Since writing large if/else blocks is not maintanable in the long run, Strolch offers a different approach.
|
||||||
|
All Strolch elements can store Policy definitions. This is a simple key/value store where the key defines
|
||||||
|
the type of policy, and the value references the policy to use.</p>
|
||||||
|
|
||||||
|
<p>Currently there are two ways to reference a policy in Strolch, either via a key which defines a further
|
||||||
|
lookup in the <code>PolicyHandler</code>, or directly as the name of the class to instantiate.</p>
|
||||||
|
|
||||||
|
<p>Using policies in Strolch gives the additional possibility of easily changing the behaviour at runtime, as a
|
||||||
|
Service and/or Command would delegate the behaviour to the currently configured policy on the releveant
|
||||||
|
element.</p>
|
||||||
|
|
||||||
|
<p>Policies are implemented by defining an abstract class and extends <code>StrolchPolicy</code>. This abstract
|
||||||
|
class then defines the API of the actual policy. A concrete class then extends this abstract class and
|
||||||
|
implements the concrete methods.</p>
|
||||||
|
|
||||||
|
<p>Policies are registered on Resources, Orders, Activities and Actions. The following shows defining two
|
||||||
|
policies on a Resource, a PlanningPolicy, an ExecutionPolicy in XML:</p>
|
||||||
|
<pre>
|
||||||
|
<Resource ...>
|
||||||
|
...
|
||||||
|
<Policies>
|
||||||
|
<Policy Type="PlanningPolicy" Value="key:SimplePlanning" />
|
||||||
|
<Policy Type="ExecutionPolicy" Value="java:li.strolch.policytest.TestSimulatedExecutionPolicy" />
|
||||||
|
</Policies>
|
||||||
|
</Resource></pre>
|
||||||
|
|
||||||
|
<p><b>Note</b> how the PlanningPolicy has a value of <code>key:SimplePlanning</code> and the ExecutionPolicy
|
||||||
|
defines a reference to an actual class.</p>
|
||||||
|
|
||||||
|
<br />
|
||||||
|
<p>To use the PolicyHandler, it must be configured in the StrolchConfiguration.xml as follows:</p>
|
||||||
|
<pre>
|
||||||
|
<Component>
|
||||||
|
<name>PolicyHandler</name>
|
||||||
|
<api>li.strolch.policy.PolicyHandler</api>
|
||||||
|
<impl>li.strolch.policy.DefaultPolicyHandler</impl>
|
||||||
|
<Properties>
|
||||||
|
<readPolicyFile>true</readPolicyFile>
|
||||||
|
<policyConfigFile>StrolchPolicies.xml</policyConfigFile>
|
||||||
|
</Properties>
|
||||||
|
</Component></pre>
|
||||||
|
|
||||||
|
<br />
|
||||||
|
<p>And this policy handler implementation requires a file where the lookups for the policies is defined,
|
||||||
|
e.g.:</p>
|
||||||
|
<pre>
|
||||||
|
<StrolchPolicies>
|
||||||
|
|
||||||
|
<PolicyType Type="PlanningPolicy" Api="li.strolch.policytest.TestPlanningPolicy">
|
||||||
|
<Policy Key="SimplePlanning" Class="li.strolch.policytest.TestSimplePlanningPolicy" />
|
||||||
|
</PolicyType>
|
||||||
|
|
||||||
|
<PolicyType Type="ConfirmationPolicy" Api="li.strolch.policytest.TestConfirmationPolicy">
|
||||||
|
<Policy Key="NoConfirmation" Class="li.strolch.policytest.TestNoConfirmationPolicy" />
|
||||||
|
</PolicyType>
|
||||||
|
|
||||||
|
</StrolchPolicies></pre>
|
||||||
|
|
||||||
|
<br />
|
||||||
|
<p>Now at runtime we can access the policies:</p>
|
||||||
|
<pre>
|
||||||
|
PolicyHandler policyHandler = getComponent(PolicyHandler.class);
|
||||||
|
|
||||||
|
try (StrolchTransaction tx = openTx()) {
|
||||||
|
|
||||||
|
Resource res = tx.getResourceBy("TestType", "MyTestResource");
|
||||||
|
PolicyDefs policyDefs = res.getPolicyDefs();
|
||||||
|
|
||||||
|
PolicyDef planningPolicyDef = policyDefs.getPolicyDef("PlanningPolicy");
|
||||||
|
PlanningPolicy planningPolicy = policyHandler.getPolicy(planningPolicyDef, tx);
|
||||||
|
planningPolicy.plan(...);
|
||||||
|
|
||||||
|
PolicyDef executionPolicyDef = res.getPolicyDefs().getPolicyDef("ExecutionPolicy");
|
||||||
|
ExecutionPolicy executionPolicy = policyHandler.getPolicy(executionPolicyDef, tx);
|
||||||
|
executionPolicy.execute(...);
|
||||||
|
}</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 files 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>
|
|
@ -50,7 +50,58 @@
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="content">
|
<div class="content">
|
||||||
<p>Strolch Transactions</p>
|
|
||||||
|
<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></li>
|
||||||
|
<li>Performing Commands correctly</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>accessing the Resources, Orders and Activities</li>
|
||||||
|
<li>accessing the element maps</li>
|
||||||
|
<li>do queries</li>
|
||||||
|
<li>get copies of templates</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>
|
||||||
|
|
||||||
|
<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(...)) {
|
||||||
|
|
||||||
|
// do work
|
||||||
|
|
||||||
|
// either or:
|
||||||
|
tx.doNothingOnClose(); // can also be omitted, as default
|
||||||
|
tx.commitOnClose();
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
<!-- content here -->
|
<!-- content here -->
|
||||||
|
|
||||||
|
|
File diff suppressed because one or more lines are too long
Before Width: | Height: | Size: 17 KiB After Width: | Height: | Size: 18 KiB |
Loading…
Reference in New Issue