<pclass="lead page-description">This page describes the Strolch API.</p>
</div>
<divclass="content">
<h2>Overview</h2>
<p>The Strolch API revolves around the <i>StrolchTransaction</i> object. The main concept is to implement your use cases in <i>Service</i> implementations. You open a transaction using the <i>openTx(String)</i>-method and then perform the use case by adding your <i>Command</i> instances to the transaction.</p>
<p>Transactions are opened on a <i>StrolchRealm</i>. The realms are used to separate mandates in a single runtime instance of Strolch. Each realm has its own <i>ResourceMap</i> and <i>OrderMap</i> instances from which you gain access to the Strolch elements.</ResourceMap></p>
<h2>Model</h2>
<p>The Strolch model is implemented in the project li.strolch.model.</p>
<p>The Strolch model consists of two root level elements: <i>Resource</i> and <i>Order</i>. Each element has at least the following attributes:</p>
<ul>
<li>Id → the element's id</li>
<li>Name → the element's name</li>
<li>Type → the element's type</li>
</ul>
<p>Each root element can have any number of <i>ParameterBag</i> instances on it, which in turn can have any number of <i>Parameters</i> on it. Accessing these objects is always done by their IDs. Strolch root elements are always stored in the respective <i>ElementMaps</i> in their Strolch realm. Thus accessing a certain parameter from a Resource would look like this:</p>
Strolch realms implement the multi-client capability which is thus baked right into the Strolch runtime. When configuring a Strolch runtime, realms are configured and for each realm the data store mode is set. Each realm has its own persistence configuration and can thus run in one of the 4 modes that the Strolch agent implements:
<ul>
<li>EMPTY
<p>This is a transient data store mode, where no model changes are persisted, but they are only kept in memory. When the Strolch agent is started, this realm stays empty as no data is loaded.</p></li>
<li>TRANSIENT
<p>This is the same as EMPTY, but with the difference that when the Strolch agent is started, an XML file is parsed and the in memory realm is populated with the elements parsed from that XML file.</p></li>
<li>CACHED
<p>In this mode, all data is stored in memory, and any changes made are written back to the persistence layer. This allows for fast in-memory quries, but makes sure no data is lost when the agent is restarted.</p></li>
<li>TRANSACTIONAL
<p>In this mode no data is kept in memory and every query, and root element retrieval is passed to the persistence layer to be retrieved from the underlying database. This is what comes closest to a typical Java+Hibernate implementation.</p></li>
</ul>
<p>Strolch Realms are also responsible for opening Transactions, as these are bound to the persistence layer configured for this realm. At runtime, a realm is then accessed from the ComponentContainer:</p>
In a Service implementation there is a convenience method, so that this is as simple as calling <i>openTx(String)</i>.
<h2>Services and Commands</h2>
<p>In the motivation section, it was discusses that writing business logic is what developing is about and a reason why Strolch is a different approach to the Java EE ecosystem. So this is where Services and Commands come into play, and tries to make writing business logic a first class citizen.</p>
<p>Services are to be used once for each use case. Services are not re-used or called by other services. Services open transactions are implement the calling of the re-usable commands. Thus when writing projects using Strolch, the first thing to do after configuring the runtime environmet for your situation, Services will be implemented.</p>
<p>Commands on the other hand are re-usable and should be implemented in such a way, that the encapsulate the use case's different actions. Commands are then passed to a transaction for execution and, when the transaction is comitted, will be executed. Commands also implement undoing its operation in the case of exceptions. Strolch transactions handle the life-cycle of a command. A further function of Commands is to lock the relevant Strolch elements before execution.</p>
<p>A typical Service and Command implementation would look as follows:</p>
<preclass="pre-scrollable">
public class SetParameterService extends AbstractService<SetParameterArg, ServiceResult> {
new UpdateElementVisitor(tx()).update(replacedElement);
}
}
}
}</pre>
<h2>Code</h2>
<p>The Strolch code can be retrieved from GitHub, where the code is hosted. Each commit triggers a continuous integration build, so that SNAPSHOT builds can be quickly integrated in projects if needed.</p>
<p>Strolch is divided up into different projects on GitHub so that these projects can be developed, or bugfixed independently and not all parts are required in every context.</p>
<p><ahref="https://github.com/eitchnet/strolch">Strolch on GitHub</a></p>
<p>This project implements the Strolch model. This is where you will find the different elements that can store data at runtime. Currently there are two root elements: Resource and Order</p></li>
<p>Implements a PostgreSQL persistence layer so that the Strolch model can be persisted to a PostgreSQL RDBMS when the realm is configured to have a data store mode of either CACHED or TRANSACTIONAL</p>
<p>Implements an XML persistence layer so that the Strolch model can be persisted to XML files when the realm is configured to have a data store mode of either CACHED or TRANSACTIONAL. This implementation uses the <ahref="xmlpers">xmlpers project</a>.</p>
<p>To quickly get started developing Strolch, this projects provides scripts to checkout all the relevant projects and implements a Maven module so that building this projects builds all Strolch projects.</p>
<p>This bill of material is a Maven project which, when imported in one's own Strolch project, pulls in all required dependencies needed to set up a minimal working Strolch environment.</p>
<p>Implements a test base so that writing tests for Strolch is easy. It provides a RuntimeMock, which handles setting up and tearing down Strolch runtimes during tests.</p>
<p>A tutorial application which showcases how to setup Strolch as a standalone Java SE project and starts the Strolch runtime by means of a main-class.</p>
<p>A tutorial application which showcases how to setup Strolch as a standalone Java Webapp which can be deployed to a servlet container e.g. Apache Tomcat 7.</p>
</li>
</ul>
<h2>Development</h2>
<p>To start getting involved with Strolch Development, or create your own applications using Strolch, then see the <ahref="development.html">development page</a></p>