[Project] Updated strolch documentation
This commit is contained in:
parent
5062fc347f
commit
e7de771fb8
|
|
@ -3,7 +3,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="google-site-verification" content="CPhbjooaiTdROm7Vs4E7kuHZvBfkeLUtonGgcVUbTL8"/>
|
||||
<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="">
|
||||
|
|
@ -55,19 +55,19 @@
|
|||
<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>
|
||||
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>, <i>OrderMap</i>, <i>ActivityMap</i>
|
||||
instances from which you gain access to the Strolch objects.</p>
|
||||
runtime instance of Strolch. Each realm has its own <i>ResourceMap</i>, <i>OrderMap</i>, <i>ActivityMap</i>
|
||||
instances from which the TX retrieves the elements.</p>
|
||||
|
||||
<h2>Model</h2>
|
||||
|
||||
<p>The Strolch model is implemented in the project li.strolch.model.</p>
|
||||
|
||||
<p>The Strolch model consists of three root level elements: <i>Resource</i>, <i>Order</i> and <i>Activity</i>.
|
||||
Each element has at least the following attributes:</p>
|
||||
Each element has at least the following attributes:</p>
|
||||
<ul>
|
||||
<li>Id → the element's id</li>
|
||||
<li>Name → the element's name</li>
|
||||
|
|
@ -75,9 +75,9 @@
|
|||
</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 <i>Resource</i> would look like this:</p>
|
||||
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 <i>Resource</i> would look like this:</p>
|
||||
<pre class="pre-scrollable">
|
||||
try (StrolchTransaction tx = openTx(realmName)) {
|
||||
Resource resource = tx.getResourceBy("TestType", "MyTestResource");
|
||||
|
|
@ -201,19 +201,19 @@ try (StrolchTransaction tx = openTx(realmName)) {
|
|||
<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>
|
||||
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>
|
||||
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>
|
||||
layer. This allows for fast in-memory quries, but makes sure no data is lost when the agent is
|
||||
restarted.</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>
|
||||
configured for this realm. At runtime, a realm is then accessed from the ComponentContainer:</p>
|
||||
<pre class="pre-scrollable">
|
||||
ComponentContainer container = getAgent().getContainer();
|
||||
StrolchRealm realm = container.getRealm(StrolchConstants.DEFAULT_REALM);
|
||||
|
|
@ -226,19 +226,19 @@ try(StrolchTransaction tx = realm.openTx()) {
|
|||
<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>
|
||||
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>
|
||||
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 environment 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>Commands on the other hand are re-usable and should be implemented in such a way, that they encapsulate the
|
||||
use case's different actions. Commands are then passed to a transaction for execution and, when the
|
||||
transaction is committed, 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>
|
||||
<pre class="pre-scrollable">
|
||||
|
|
@ -376,23 +376,24 @@ public class SetParameterCommand extends Command {
|
|||
<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>
|
||||
integration build, so that we are sure no tests are broken. The CI is viewable at
|
||||
<a href="https://ci.4trees.ch" target="_blank">4trees CI Server</a>.</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>
|
||||
independently and not all parts are required in every context.</p>
|
||||
|
||||
<p><a href="https://github.com/4treesCH/strolch">Strolch on GitHub</a></p>
|
||||
<p><a href="https://github.com/4treesCH/strolch" target="_blank">Strolch on GitHub</a></p>
|
||||
|
||||
<h3>Main Strolch components</h3>
|
||||
<ul>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.model">li.strolch.model</a>
|
||||
|
||||
<p>This project implements the Strolch model. This is where you will find the different elements that
|
||||
can store data at runtime e.g. <i>Resources</i>, <i>Orders</i> and <i>Activities</i></p></li>
|
||||
can store data at runtime e.g. <i>Resources</i>, <i>Orders</i> and <i>Activities</i></p></li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.agent">li.strolch.agent</a>
|
||||
|
||||
<p>The agent is the Strolch runtime and is the component which implements the core Agent functionality.
|
||||
That is:</p>
|
||||
That is:</p>
|
||||
<ul>
|
||||
<li>Provide the Agent instance which loads the configuration and is the entry point to the runtime
|
||||
</li>
|
||||
|
|
@ -400,7 +401,8 @@ public class SetParameterCommand extends Command {
|
|||
</li>
|
||||
<li>Configure and maintain the realms, which implement the multi-client capability</li>
|
||||
<li>Provide a default ServiceHandler to perform Services at runtime</li>
|
||||
<li>Implements the realms which each can operate in different modes data store modes: CACHED, TRANSIENT
|
||||
<li>Implements the realms which each can operate in different modes data store modes: CACHED,
|
||||
TRANSIENT
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -420,17 +422,17 @@ public class SetParameterCommand extends Command {
|
|||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.persistence.postgresql">li.strolch.persistence.postgresql</a>
|
||||
|
||||
<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 CACHED.</p>
|
||||
RDBMS when the realm is configured to have a data store mode of CACHED.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.persistence.xml">li.strolch.persistence.xml</a>
|
||||
|
||||
<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 CACHED.</p>
|
||||
realm is configured to have a data store mode of CACHED.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.rest">li.strolch.rest</a>
|
||||
|
||||
<p>Implements a Restful API to communicate with the Strolch runtime from clients and external
|
||||
systems.</p>
|
||||
systems.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
|
@ -439,47 +441,32 @@ public class SetParameterCommand extends Command {
|
|||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.bom">li.strolch.bom</a>
|
||||
|
||||
<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>
|
||||
all required dependencies needed to set up a minimal working Strolch environment.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/master/li.strolch.testbase">li.strolch.testbase</a>
|
||||
|
||||
<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>
|
||||
handles setting up and tearing down Strolch runtimes during tests.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3>Example projects</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<a href="https://github.com/4treesCH/strolch/tree/develop/li.strolch.planningwebapp">li.strolch.planningwebapp</a>
|
||||
|
||||
<p>A show case application for us in planning and scheduling use-cases.</p>
|
||||
</li>
|
||||
<li>
|
||||
<a href="https://github.com/4treesCH/strolch/tree/develop/li.strolch.tutorialapp">li.strolch.tutorialapp</a>
|
||||
|
||||
<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>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/li.strolch.tutorialwebapp">li.strolch.tutorialwebapp</a>
|
||||
|
||||
<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 8.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal">strolch_minimal</a>
|
||||
|
||||
<p>A minimal project to get started with strolch.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal_rest">strolch_minimal_rest</a>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal_rest" target="_blank">strolch_minimal_rest</a>
|
||||
|
||||
<p>A minimal project to get started using REST with Strolch.</p>
|
||||
</li>
|
||||
<li><a href="https://github.com/4treesCH/strolch-bookshop" target="_blank">Strolch Bookshop</a>
|
||||
|
||||
<p>An example implentation of services etc. where we show how to use Strolch by implementing a simple
|
||||
book shop.</p>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2>Development</h2>
|
||||
|
||||
<p>To start getting involved with Strolch Development, or create your own applications using Strolch, then see
|
||||
the <a href="development.html">development page</a></p>
|
||||
the <a href="development.html">development page</a></p>
|
||||
|
||||
</div>
|
||||
<!-- /.content -->
|
||||
|
|
@ -516,7 +503,7 @@ public class SetParameterCommand extends Command {
|
|||
s.parentNode.insertBefore(g, s);
|
||||
})();
|
||||
</script>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt=""/></p></noscript>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt="" /></p></noscript>
|
||||
<!-- End Piwik Code -->
|
||||
|
||||
</body>
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="google-site-verification" content="CPhbjooaiTdROm7Vs4E7kuHZvBfkeLUtonGgcVUbTL8"/>
|
||||
<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="">
|
||||
|
|
@ -64,24 +64,20 @@ cd strolch
|
|||
mvn clean install -DskipTests</pre>
|
||||
|
||||
<p><b>Note:</b> To run the tests you will need to configure the PostgreSQL Databases. See the README in the
|
||||
module.</p>
|
||||
module.</p>
|
||||
|
||||
<p>After running the Maven build, you will have a full build of all Strolch projects. Now you can start
|
||||
modifying the projects, and add your own features, or, far more interesting, start developing your projects
|
||||
using the Strolch agent.</p>
|
||||
modifying the projects, and add your own features, or, far more interesting, start developing your projects
|
||||
using the Strolch agent.</p>
|
||||
|
||||
<h2>Strolch Project Configuration</h2>
|
||||
<p>To use Strolch in your own projects, look at the two tutorial apps on how they are configured. You can also
|
||||
simply copy the projects, modify the Maven POMs and remove what ever you do not need.</p>
|
||||
simply copy the projects, modify the Maven POMs and remove what ever you do not need.</p>
|
||||
|
||||
<p>The following sections describe the Strolch configuration files and folder structure.</p>
|
||||
|
||||
<p>You can also use the minimal project structures:</p>
|
||||
<ul>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal">strolch_minimal</a></li>
|
||||
<li><a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal_rest">strolch_minimal_rest</a>
|
||||
</li>
|
||||
</ul>
|
||||
<p>You can also use the minimal project structure:
|
||||
<a href="https://github.com/4treesCH/strolch/tree/develop/strolch_minimal_rest">strolch_minimal_rest</a></p>
|
||||
|
||||
<h3>Project Structure</h3>
|
||||
<p>Strolch requires two main directories under the Strolch root:</p>
|
||||
|
|
@ -91,8 +87,11 @@ mvn clean install -DskipTests</pre>
|
|||
<li>StrolchConfiguration.xml → Main Strolch configuration file. There you configure the
|
||||
different realms, environments etc.
|
||||
</li>
|
||||
<li>PrivilegeConfig.xml → Configuration of the Privilege library</li>
|
||||
<li>PrivilegeModel.xml → Configuration file with the differen users, roles and privileges</li>
|
||||
<li>PrivilegeConfig.xml → Configuration of the privilege management.</li>
|
||||
<li>PrivilegeUsers.xml → Configuration file with the different users and their role
|
||||
associations.
|
||||
</li>
|
||||
<li>PrivilegeRoles.xml → Configuration file with the different roles and privileges.</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>../data/ → contains the Strolch model and any other data which is modified at runtime.
|
||||
|
|
@ -101,179 +100,19 @@ mvn clean install -DskipTests</pre>
|
|||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>../tmp/ → contains any temporary files, e.g. log files etc.</li>
|
||||
</ul>
|
||||
|
||||
<h3>Maven POM</h3>
|
||||
<p>Strolch is built using Maven, so here we show the minimum Maven POM.</p>
|
||||
<p>Strolch is built using Maven, so here we show the minimum Maven POM for a web application:</p>
|
||||
|
||||
<h4>Simple Java App POM</h4>
|
||||
<p>This POM creates a compressed file which contains a runnable Strolch instance. Just unpack and run the <i>startup.sh</i>
|
||||
script.</p>
|
||||
<pre class="pre-scrollable">
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<properties>
|
||||
<strolch.version>1.0.0-SNAPSHOT</strolch.version>
|
||||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||||
<finalName>strolch_app</finalName>
|
||||
<m2eclipse.wtp.contextRoot>${finalName}</m2eclipse.wtp.contextRoot>
|
||||
<buildTimestamp>${maven.build.timestamp}</buildTimestamp>
|
||||
</properties>
|
||||
|
||||
<groupId>org.example</groupId>
|
||||
<artifactId>org.example.strolch.app</artifactId>
|
||||
<version>1.2.3</version>
|
||||
<name>org.example.strolch.app</name>
|
||||
|
||||
<scm>
|
||||
<developerConnection>scm:git:https://git.example.org/strolch_app.git</developerConnection>
|
||||
</scm>
|
||||
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>li.strolch</groupId>
|
||||
<artifactId>li.strolch.bom</artifactId>
|
||||
<type>pom</type>
|
||||
<version>${strolch.version}</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
|
||||
<dependencies>
|
||||
<!-- main -->
|
||||
<dependency>
|
||||
<groupId>li.strolch</groupId>
|
||||
<artifactId>li.strolch.model</artifactId>
|
||||
<version>${strolch.version}</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>li.strolch</groupId>
|
||||
<artifactId>li.strolch.agent</artifactId>
|
||||
<version>${strolch.version}</version>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>li.strolch</groupId>
|
||||
<artifactId>li.strolch.service</artifactId>
|
||||
<version>${strolch.version}</version>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.slf4j</groupId>
|
||||
<artifactId>slf4j-log4j12</artifactId>
|
||||
<scope>runtime</scope>
|
||||
<version>1.7.2</version>
|
||||
</dependency>
|
||||
|
||||
<!-- test dependencies -->
|
||||
<dependency>
|
||||
<groupId>junit</groupId>
|
||||
<artifactId>junit</artifactId>
|
||||
<scope>test</scope>
|
||||
<version>4.11</version>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
<build>
|
||||
<finalName>${finalName}</finalName>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>src/main/resources</directory>
|
||||
<filtering>true</filtering>
|
||||
<includes>
|
||||
<include>**/componentVersion.properties</include>
|
||||
</includes>
|
||||
</resource>
|
||||
<resource>
|
||||
<directory>src/main/resources</directory>
|
||||
<filtering>false</filtering>
|
||||
<excludes>
|
||||
<exclude>**/componentVersion.properties</exclude>
|
||||
</excludes>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>3.0</version>
|
||||
<configuration>
|
||||
<source>1.7</source>
|
||||
<target>1.7</target>
|
||||
<showDeprecation>true</showDeprecation>
|
||||
<showWarnings>true</showWarnings>
|
||||
<compilerArgument>-Xlint:all</compilerArgument>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.codehaus.mojo</groupId>
|
||||
<artifactId>buildnumber-maven-plugin</artifactId>
|
||||
<version>1.2</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>validate</phase>
|
||||
<goals>
|
||||
<goal>create</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<doCheck>false</doCheck>
|
||||
<doUpdate>false</doUpdate>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-jar-plugin</artifactId>
|
||||
<configuration>
|
||||
<archive>
|
||||
<manifest>
|
||||
<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
|
||||
<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
|
||||
|
||||
<!-- When creating an executable jar, use copy-dependencies plugin with libs in lib/ dir: -->
|
||||
<mainClass>li.strolch.tutorialapp.main.Main</mainClass>
|
||||
<addClasspath>true</addClasspath>
|
||||
<classpathPrefix>lib/</classpathPrefix>
|
||||
</manifest>
|
||||
</archive>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-assembly-plugin</artifactId>
|
||||
<configuration>
|
||||
<descriptor>src/assembly/bin.xml</descriptor>
|
||||
<finalName>tutorial-app-${project.version}</finalName>
|
||||
</configuration>
|
||||
<executions>
|
||||
<execution>
|
||||
<phase>package</phase>
|
||||
<goals>
|
||||
<goal>single</goal>
|
||||
</goals>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project></pre>
|
||||
|
||||
<h4>Webapp POM</h4>
|
||||
<p>This creates a simple WAR which starts Strolch after deployed to a servlet container.</p>
|
||||
<pre class="pre-scrollable">
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<properties>
|
||||
<strolch.version>1.2.3</strolch.version>
|
||||
<strolch.version>1.6.47</strolch.version>
|
||||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||||
<warFinalName>strolch_webapp</warFinalName>
|
||||
<m2eclipse.wtp.contextRoot>${warFinalName}</m2eclipse.wtp.contextRoot>
|
||||
|
|
@ -445,15 +284,23 @@ mvn clean install -DskipTests</pre>
|
|||
<h3>Tools used</h3>
|
||||
The following tools are used to develop Strolch and Strolch-based projects:
|
||||
<ul class="list-unstyled">
|
||||
<li><a href="https://www.eclipse.org/downloads/"><img style="height: 50px" class="img-thumbnail"
|
||||
<li><a href="https://www.eclipse.org/downloads/"><img style="height: 50px"
|
||||
class="img-thumbnail"
|
||||
src="https://www.eclipse.org/downloads/packages/sites/all/themes/solstice/_themes/solstice_packages/logo.png"
|
||||
alt="Eclipse Luna JEE version"/></a></li>
|
||||
<li><a href="https://maven.apache.org/"><img width="250" style="height: 50px; margin-top: 10px"
|
||||
alt="Eclipse Luna JEE version" /></a></li>
|
||||
<li><a href="https://www.jetbrains.com/idea/download/#section=linux"><img style="height: 50px"
|
||||
class="img-thumbnail"
|
||||
src="https://upload.wikimedia.org/wikipedia/commons/d/d5/IntelliJ_IDEA_Logo.svg"
|
||||
alt="IntelliJ IDEA" /></a></li>
|
||||
<li><a href="https://maven.apache.org/"><img width="250"
|
||||
style="height: 50px; margin-top: 10px"
|
||||
class="img-thumbnail"
|
||||
src="http://maven.apache.org/images/maventxt_logo_200.gif"
|
||||
alt="Apache Maven 3.0"/></a></li>
|
||||
<li><a href="http://git-scm.com/"><img style="height: 50px; margin-top: 10px" class="img-thumbnail"
|
||||
src="http://git-scm.com/images/logo@2x.png" alt="git scm"/></a></li>
|
||||
alt="Apache Maven 3.0" /></a></li>
|
||||
<li><a href="http://git-scm.com/"><img style="height: 50px; margin-top: 10px"
|
||||
class="img-thumbnail"
|
||||
src="http://git-scm.com/images/logo@2x.png"
|
||||
alt="git scm" /></a></li>
|
||||
</ul>
|
||||
|
||||
</div><!-- /.content -->
|
||||
|
|
@ -467,12 +314,12 @@ mvn clean install -DskipTests</pre>
|
|||
|
||||
</div><!-- /.container -->
|
||||
|
||||
<!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
|
||||
<!-- 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 -->
|
||||
<!-- Include all compiled plugins (below), or include individual xsd as needed -->
|
||||
<script src="js/bootstrap.min.js"></script>
|
||||
|
||||
<!-- Piwik -->
|
||||
<!-- Piwik -->
|
||||
<script type="text/javascript">
|
||||
var _paq = _paq || [];
|
||||
_paq.push(['trackPageView']);
|
||||
|
|
@ -489,8 +336,8 @@ mvn clean install -DskipTests</pre>
|
|||
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 -->
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt="" /></p></noscript>
|
||||
<!-- End Piwik Code -->
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@
|
|||
<ul>
|
||||
<li>REST Endpoints → expose an API to access the Strolch agent outside of the Java VM</li>
|
||||
<li>Services and Commands → implements business logic</li>
|
||||
<li>Queries → implements specific queries against the Strolch model</li>
|
||||
<li>Searches → implements specific queries against the Strolch model</li>
|
||||
<li>Components → Implements additional logic, which is best implement as a component. E.g. active
|
||||
components which have threads, etc.
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -55,19 +55,21 @@
|
|||
<ul>
|
||||
<li>1 <code>Service</code> per use-case, should mostly delegate to <code>Commands</code>.</li>
|
||||
<li><code>Commands</code> implement use-cases or parts of it, and are thus reusable.</li>
|
||||
<li>Subclass <code>ResourceQuery</code> and <code>OrderQuery</code> when implementing use-case specific
|
||||
querying - this allows privilege checking.
|
||||
<li>Subclass <code>ResourceSearch</code>, <code>OrderSearch</code> and <code>ActivitySearch</code> when
|
||||
implementing use-case specific search - this allows privilege checking.
|
||||
</li>
|
||||
<li>One Transaction at a time - no TX inside of another TX.</li>
|
||||
<li>Commands are added to TXs and performed on close: <code>tx.addCommand(Command)</code> and then <code>tx.commitOnClose()</code>
|
||||
</li>
|
||||
<li>Use <code>tx.flush() and as late as possible in your TX <code>tx.commitOnClose()</code></code>
|
||||
<li>Use <code>tx.flush() if you need to perform first some work and then as late as possible call <code>tx.commitOnClose()</code></code>
|
||||
</li>
|
||||
<li>Only access <code>ElementMap</code>s if really no other way, mostly use <code>tx.get*By()</code>, <code>tx.findBy()</code>
|
||||
and queries - if a specific get is missing, then add the method to <code>StrolchTransaction</code> and
|
||||
send a pull request!
|
||||
</li>
|
||||
<li>Don't write logic in REST API beans. Delegate to other classes, making your code reusable!</li>
|
||||
<li>Use <code>tx.stream*()</code> methods to iterate over all elements, if you don't want to use a search.
|
||||
</li>
|
||||
<li>Don't write logic in REST API beans. Delegate to other services, making your code reusable!</li>
|
||||
<li>Transform to JSON using the <code>StrolchElementToJsonVisitor</code>.</li>
|
||||
<li>References between objects is done by adding a <code>ParameterBag</code> with the id
|
||||
<code>relations</code> to the object and then <code>StringParameters</code> with the value being the ID,
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="google-site-verification" content="CPhbjooaiTdROm7Vs4E7kuHZvBfkeLUtonGgcVUbTL8"/>
|
||||
<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="">
|
||||
|
|
@ -52,7 +52,7 @@
|
|||
|
||||
<div class="content">
|
||||
<p>A Strolch runtime configuration comprises two parts: a configuration part, and a model part. The
|
||||
configuration are files located in the <code>..config/</code> folder, and the model are files located in the
|
||||
configuration are files located in the <code>..config/</code> folder, and the model are files located in the
|
||||
<code>../data</code> folder.</p>
|
||||
|
||||
|
||||
|
|
@ -64,8 +64,10 @@
|
|||
<dd>→ configures the Strolch agent</dd>
|
||||
<dt>PrivilegeConfig.xml</dt>
|
||||
<dd>→ configures user management</dd>
|
||||
<dt>PrivilegeModel.xml</dt>
|
||||
<dd>→ contains the users and roles in an XML based user management</dd>
|
||||
<dt>PrivilegeUsers.xml</dt>
|
||||
<dd>→ contains the users in an XML based user management file</dd>
|
||||
<dt>PrivilegeRoles.xml</dt>
|
||||
<dd>→ contains the roles and privileges in an XML based user management</dd>
|
||||
</dl>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
@ -73,15 +75,15 @@
|
|||
<h2>StrolchConfiguration.xml</h2>
|
||||
|
||||
<p>The <i>StrolchConfiguration.xml</i> file configures the Strolch agent. The <i>StrolchConfiguration.xml</i>
|
||||
defines the following:</p>
|
||||
defines the following:</p>
|
||||
<ul>
|
||||
<li><code><StrolchConfiguration></code> root element</li>
|
||||
|
||||
<li><code><env id="xxx"></code> different environments with the possibility of having a global
|
||||
environment for configuration valid in multiple environments.
|
||||
environment for configuration valid in multiple environments.
|
||||
<ul>
|
||||
<li><code><Runtime></code> element which defines the agents name and a few other properties
|
||||
e.g. <code>locale</code> and <code>verbose</code>:
|
||||
e.g. <code>locale</code> and <code>verbose</code>:
|
||||
<ul>
|
||||
<li><code><applicationName></code> the agent's name</li>
|
||||
|
||||
|
|
@ -89,7 +91,7 @@
|
|||
|
||||
<li><code><locale></code> the agent's internal locale for log messages etc.</li>
|
||||
<li><code><verbose></code> the logging level for some internal logging. (Logging is
|
||||
mostly done using log4j over slf4j)
|
||||
mostly done using log4j over slf4j)
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -97,32 +99,37 @@
|
|||
</li>
|
||||
|
||||
<li><code><Component></code> elements for each component used in the agent. A component is configured
|
||||
by defining the following child elements:
|
||||
by defining the following child elements:
|
||||
<ul>
|
||||
<li><code><name></code> the name of the component, use when defining dependencies between
|
||||
components. The name is mostly set to the simple name of the interface of the component
|
||||
components. The name is mostly set to the simple name of the interface
|
||||
of the component
|
||||
</li>
|
||||
|
||||
<li><code><api></code> the full class name to the interface of the component. During runtime
|
||||
this interface will be used to access the component e.g.: <code>ServiceHandler svcHandler =
|
||||
agent.getContainer().getComponent(ServiceHandler.class);</code>
|
||||
this interface will be used to access the component e.g.: <code>ServiceHandler
|
||||
svcHandler
|
||||
=
|
||||
agent.getContainer().getComponent(ServiceHandler.class);</code>
|
||||
</li>
|
||||
|
||||
<li><code><impl></code> the full class name of the concrete implementation of the component.
|
||||
During initialization this class will be instantiated and registered under the component name
|
||||
and interface. This class must extend the class
|
||||
<code>li.strolch.agent.api.StrolchComponent</code>
|
||||
During initialization this class will be instantiated and registered
|
||||
under the component name and interface. This class must extend the
|
||||
class <code>li.strolch.agent.api.StrolchComponent</code>
|
||||
</li>
|
||||
|
||||
<li><code><depends></code> any number of these elements, where the content is the name of
|
||||
another component, on which this component depends. Depending components are initialized and
|
||||
started after the component they depend on and are stopped and destroyed before
|
||||
another component, on which this component depends. Depending
|
||||
components are initialized and started after the component they
|
||||
depend on and are stopped and destroyed before
|
||||
</li>
|
||||
|
||||
<li><code><Properties></code>
|
||||
<ul>
|
||||
<li><code><...></code> any number of properties which the component requires. The
|
||||
element's name will be the key with which the value can be accessed at runtime.
|
||||
element's name will be the key with which the value can be
|
||||
accessed at runtime.
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -131,16 +138,17 @@
|
|||
</ul>
|
||||
|
||||
<p><b>Note:</b> When a property is missing, and the component has a hard coded default value, then when the
|
||||
component is initialized, the use of the default value and its key is logged. This makes it easy to see
|
||||
which new properties can be configured. Should the component not define a default value, then the component
|
||||
will thrown an exception on initialization. In this case it can be a good moment to read the JavaDoc (or
|
||||
source code) for the component in question to see how it is configured.</p>
|
||||
component is initialized, the use of the default value and its key is logged. This makes it easy
|
||||
to see which new properties can be configured. Should the component not define a default value,
|
||||
then the component will thrown an exception on initialization. In this case it can be a good
|
||||
moment to read the JavaDoc (or source code) for the component in question to see how it is
|
||||
configured.</p>
|
||||
|
||||
<h2>Privilege Configuration</h2>
|
||||
|
||||
<p>In Strolch authentication and authorization is baked in. To open a transaction, and thus access the Strolch
|
||||
model, a Certificate object is required, which means the user has been authenticated and possibly
|
||||
authorized.</p>
|
||||
model, a Certificate object is required, which means the user has been authenticated and possibly
|
||||
authorized.</p>
|
||||
|
||||
<p>The <i>PrivilegeConfig.xml</i> defines the following:</p>
|
||||
<ul>
|
||||
|
|
@ -150,65 +158,62 @@
|
|||
<ul>
|
||||
<li><code><Parameters></code> base configuration properties for Privilege</li>
|
||||
<li><code><EncryptionHandler></code> configures the hashing algorithms and other
|
||||
encryption specific configuration
|
||||
encryption specific configuration
|
||||
</li>
|
||||
<li><code><PersistenceHandler></code> configures the persistence of the roles and
|
||||
users
|
||||
users
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code><Policies></code> configures the available privilege policies at runtime, the name
|
||||
is referenced from the model file
|
||||
is referenced from the model file
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>The <code>PrivilegeModel.xml</code> defines the following and is used when in <code>PrvilegeConfig.xml</code>
|
||||
the <code>PersistenceHandler</code> is set to
|
||||
<code>ch.eitchnet.privilege.handler.XmlPersistenceHandler</code>:</p>
|
||||
<p>The <code>PrivilegeUsers.xml</code> and <code>PrivilegeRoles.xml</code> define the users and roles and is
|
||||
used when in <code>PrvilegeConfig.xml</code> the <code>PersistenceHandler</code> is set to <code>ch.eitchnet.privilege.handler.XmlPersistenceHandler</code>:
|
||||
</p>
|
||||
<ul>
|
||||
<li><code><UsersAndRoles></code> root element
|
||||
<li><code><Users></code> configures all users
|
||||
<ul>
|
||||
<li><code><Users></code> configures all users
|
||||
<li><code><User></code> configures a specific user
|
||||
<ul>
|
||||
<li><code><User></code> configures a specific user
|
||||
<li><code><Firstname></code> configures a user's first name</li>
|
||||
<li><code><Lastname></code> configure a user's last name</li>
|
||||
<li><code><State></code> configures the user's state, see <code>ch.eitchnet.privilege.model.UserState</code>
|
||||
</li>
|
||||
<li><code><Locale></code> configure the user's locale</li>
|
||||
<li><code><Roles></code> configures the user's roles
|
||||
<ul>
|
||||
<li><code><Firstname></code> configures a user's first name</li>
|
||||
<li><code><Lastname></code> configure a user's last name</li>
|
||||
<li><code><State></code> configures the user's state, see <code>ch.eitchnet.privilege.model.UserState</code>
|
||||
</li>
|
||||
<li><code><Locale></code> configure the user's locale</li>
|
||||
<li><code><Roles></code> configures the user's roles
|
||||
<ul>
|
||||
<li><code><Role></code> adds a role to the user</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code><Properties></code> configures user specific properties. What
|
||||
properties are used is not specified and is dependent on the concrete agent
|
||||
<ul>
|
||||
<li><code><Property></code> defines a single property</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code><Role></code> adds a role to the user</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><code><Properties></code> configures user specific properties. What properties are
|
||||
used is not specified and is dependent on the concrete
|
||||
agent
|
||||
<ul>
|
||||
<li><code><Property></code> defines a single property</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li><code><Roles></code> configures all roles
|
||||
<li><code><Roles></code> configures all roles
|
||||
<ul>
|
||||
<li><code><Role></code> configures a specific role
|
||||
<ul>
|
||||
<li><code><Role></code> configures a specific role
|
||||
<li><code><Privilege></code> configures a specific privilege for this role
|
||||
<ul>
|
||||
<li><code><Privilege></code> configures a specific privilege for this role
|
||||
<ul>
|
||||
<li><code><AllAllowed></code> if set to true, then defines that all
|
||||
values associated with this privilege are allowed
|
||||
</li>
|
||||
<li><code><Allow></code> defines one allowed value for this privilege
|
||||
</li>
|
||||
<li><code><Deny></code> defines one denied value for this privilege
|
||||
</li>
|
||||
</ul>
|
||||
<li><code><AllAllowed></code> if set to true, then defines that all values
|
||||
associated with this privilege are allowed
|
||||
</li>
|
||||
<li><code><Allow></code> defines one allowed value for this privilege
|
||||
</li>
|
||||
<li><code><Deny></code> defines one denied value for this privilege
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -221,25 +226,35 @@
|
|||
<h2>Implementing a StrolchComponent</h2>
|
||||
|
||||
<p>Implementing a strolch component requires an interface, which defines the component's API and a concrete
|
||||
class which implements the interface and extends the class <code>StrolchComponent</code>.</p>
|
||||
class which implements the interface and extends the class <code>StrolchComponent</code>.</p>
|
||||
|
||||
<p>The StrolchComponent class adds the state model to the class, which transitions as follows:<br/> <code>UNDEFINED
|
||||
=> SETUP => INITIALIZED => STARTED <=> STOPPED => DESTROYED</code></p>
|
||||
<p>The StrolchComponent class adds the state model to the class, which transitions as follows:<br /> <code>UNDEFINED
|
||||
=>
|
||||
SETUP
|
||||
=>
|
||||
INITIALIZED
|
||||
=>
|
||||
STARTED
|
||||
<=>
|
||||
STOPPED
|
||||
=>
|
||||
DESTROYED</code>
|
||||
</p>
|
||||
|
||||
<p>Components can switch between <code>STARTED</code> and <code>STOPPED</code>, but once <code>DESTROYED</code>
|
||||
no further state change is possible. The component's state is changed by changes to the agent's lifecycle.
|
||||
no further state change is possible. The component's state is changed by changes to the agent's lifecycle.
|
||||
</p>
|
||||
|
||||
<p>A component's state is changed by a call to the appropriate method on the component, override the methods as
|
||||
necessary. Note that it is good practice that the <code>initialize()</code>-method is used to get all the
|
||||
configuration properties, and that they should there be evaluated and that the method so return quickly. The
|
||||
necessary. Note that it is good practice that the <code>initialize()</code>-method is used to get all the
|
||||
configuration properties, and that they should there be evaluated and that the method so return quickly. The
|
||||
<code>start()</code>-method is called after the agent's initialization and should be where additional
|
||||
threads are started. Correctly implementing these methods allows to quickly detect a wrongly configured
|
||||
agent, which might take longer to start for whatever reason.</p>
|
||||
threads are started. Correctly implementing these methods allows to quickly detect a wrongly configured
|
||||
agent, which might take longer to start for whatever reason.</p>
|
||||
|
||||
<p>The following shows a basic implementation of a component on the basis of a post initializer (a component
|
||||
which performs some actions in its <code>start()</code>-method which should be done after everything else is
|
||||
started in the agent).</p>
|
||||
which performs some actions in its <code>start()</code>-method which should be done after everything else is
|
||||
started in the agent).</p>
|
||||
|
||||
<pre>
|
||||
public class SimplePostInitializer
|
||||
|
|
@ -304,7 +319,7 @@ PostInitializer postInitializer = getContainer().getComponent(PostInitializer.cl
|
|||
<h2>Starting the agent</h2>
|
||||
|
||||
<p>When a Strolch runtime is started, then the root path to the runtime configuration must be passed. In Java
|
||||
this is done by calling:</p>
|
||||
this is done by calling:</p>
|
||||
<pre>
|
||||
StrolchAgent agent = new StrolchAgent();
|
||||
agent.setup(environment, rootPath);
|
||||
|
|
@ -312,14 +327,8 @@ agent.initialize();
|
|||
agent.start();
|
||||
</pre>
|
||||
|
||||
<p>For command line based applications there is also a main starter which takes command line arguments. The main
|
||||
starter handles stopping the agent by pressing Ctrl+c.</p>
|
||||
<pre>
|
||||
MainStarter starter = new MainStarter(); mainStarter.start(args);
|
||||
</pre>
|
||||
|
||||
<p>And in Servlet 3.0 applications one would implement the <code>javax.servlet.ServletContextListener</code>
|
||||
interface, add the <code>@WebListener</code> annotation to the class and in the
|
||||
<p>In Servlet 3.0 applications one would implement the <code>javax.servlet.ServletContextListener</code>
|
||||
interface, add the <code>@WebListener</code> annotation to the class and in the
|
||||
<code>contextInitialized()</code>-method start Strolch:</p>
|
||||
<pre>
|
||||
String realPath = sce.getServletContext().getRealPath("/WEB-INF");
|
||||
|
|
@ -367,7 +376,7 @@ this.agent.start();
|
|||
s.parentNode.insertBefore(g, s);
|
||||
})();
|
||||
</script>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt=""/></p></noscript>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt="" /></p></noscript>
|
||||
<!-- End Piwik Code -->
|
||||
|
||||
</body>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
|
@ -3,7 +3,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||
<meta name="google-site-verification" content="CPhbjooaiTdROm7Vs4E7kuHZvBfkeLUtonGgcVUbTL8"/>
|
||||
<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="">
|
||||
|
|
@ -48,7 +48,7 @@
|
|||
<h1 class="page-title">Strolch Overview</h1>
|
||||
|
||||
<p class="lead page-description">This page describes the Strolch software agent and the motivation behind its
|
||||
development.</p>
|
||||
development.</p>
|
||||
</div>
|
||||
|
||||
<div class="content">
|
||||
|
|
@ -56,148 +56,168 @@
|
|||
<h2>Overview</h2>
|
||||
|
||||
<p>Strolch is an open source component based software agent written in Java and can be compared, in a light
|
||||
sense, with the Java EE stack: Strolch takes care of persistence, implements Services for use cases,
|
||||
Commands as re-usable algorithms and has a parameterized data model.</p>
|
||||
sense, with the Java EE stack: Strolch takes care of persistence, implements Services for use cases, Commands
|
||||
as re-usable algorithms and has a parameterized data model.</p>
|
||||
|
||||
<p>Strolch has an intrinsic understanding for mandates, which are called realms so that a single agent can be
|
||||
used to implement applications with multiple users/customers for instance in SaaS environments.</p>
|
||||
used to implement applications with multiple users/customers for instance in SaaS environments.</p>
|
||||
|
||||
<p>The parameterized data model consists of three top level objects, Resources, Orders and Activities. These
|
||||
objects can have any number of ParameterBags which in turn can have any number of Parameters on them. This
|
||||
allows for a very dynamic modelling of data structures including modification at run time. Multiple ready to
|
||||
use Parameter types are already implemented which handle the primitive types in Java including
|
||||
ListParameters for collections of these primitive types.</p>
|
||||
objects can have any number of ParameterBags which in turn can have any number of Parameters on them. This
|
||||
allows for a very dynamic modelling of data structures including modification at run time. Multiple ready to
|
||||
use Parameter types are already implemented which handle the primitive types in Java including ListParameters
|
||||
for collections of these primitive types.</p>
|
||||
|
||||
<p>One of the main features of the Strolch agent, is that persistence is handled transparently and the user must
|
||||
not be worried about databases and the likes. Currently there are two implementations for persisting the
|
||||
Strolch model, a PostgreSQL and an XML file persistence. Currently both persistence layers persist the data
|
||||
by converting to XML and storing it into the database. The XML file persistence stores each object in its
|
||||
own file.</p>
|
||||
not be worried about databases and the likes. Currently there are two implementations for persisting the
|
||||
Strolch model, a PostgreSQL and an XML file persistence. Currently both persistence layers persist the data
|
||||
by converting to XML and storing it into the database. The XML file persistence stores each object in its own
|
||||
file.</p>
|
||||
|
||||
<p>The agent itself has a small memory footprint and requires very few components to start. For the agent to be
|
||||
useful it needs additional functionality which is implemented in StrolchComponents. Each component is
|
||||
registered via its Java interface on the agent and is bound to the life cycle of the agent. When the agent
|
||||
is started, these components can be retrieved and used to perform any number of functionalities. This is the
|
||||
preferred way to extend the Strolch agent. There are a number of components already implemented, e.g. the
|
||||
ServiceHandler which executes Services in a controlled fashion and can validate authorized access to these
|
||||
services.</p>
|
||||
useful it needs additional functionality which is implemented in StrolchComponents. Each component is
|
||||
registered via its Java interface on the agent and is bound to the life cycle of the agent. When the agent is
|
||||
started, these components can be retrieved and used to perform any number of functionalities. This is the
|
||||
preferred way to extend the Strolch agent. There are a number of components already implemented, e.g. the
|
||||
ServiceHandler which executes Services in a controlled fashion and can validate authorized access to these
|
||||
services.</p>
|
||||
|
||||
<p>No software product is complete without a system for authentication and authorization. Strolch implements
|
||||
this by using the Privilege framework which has been written by Robert von Burg. The standard ServiceHandler
|
||||
detects the existence of the PrivilegeHandler and then validates that the user has authorization to perform
|
||||
the service. This framework is implemented as its own Strolch component, thus can be retrieved at any time
|
||||
during execution to perform fine grained and special authorization validation.</p>
|
||||
this by using the Privilege framework which has been written by Robert von Burg. The standard ServiceHandler
|
||||
detects the existence of the PrivilegeHandler and then validates that the user has authorization to perform
|
||||
the service. This framework is implemented as its own Strolch component, thus can be retrieved at any time
|
||||
during execution to perform fine grained and special authorization validation.</p>
|
||||
|
||||
<h2>Motivation</h2>
|
||||
|
||||
<p>A question often asked is why create Strolch. What are its benefits in contrast to using Java SE with an
|
||||
OR-Mapper like Hibernate, or using Java EE on JBoss or Glassfish? Especially since many of the features
|
||||
existing in those stacks needed to be re-created in Strolch.</p>
|
||||
OR-Mapper like Hibernate, or using Java EE on JBoss or Glassfish? Especially since many of the features
|
||||
existing in those stacks needed to be re-created in Strolch.</p>
|
||||
|
||||
<p>The first answer to this question is that those systems are often overly complicated and bloated. Java SE
|
||||
with Hibernate certainly is a viable option when it comes to being light-weightier but Hibernate, even
|
||||
though it is supposed to, often fails to truly help remove the need to really understand an RDBMS. Often
|
||||
enough Hibernate will just get in the way of the most important part of development: writing the business
|
||||
code. Being an OR-Mapper which is supposed to implement all the nitty-gritty details of an RDBMS system,
|
||||
Hibernate, and JPA for that matter, still often has the developer go back to understanding these
|
||||
details.</p>
|
||||
with Hibernate certainly is a viable option when it comes to being light-weightier but Hibernate, even though
|
||||
it is supposed to, often fails to truly help remove the need to really understand an RDBMS. Often enough
|
||||
Hibernate will just get in the way of the most important part of development: writing the business code.
|
||||
Being an OR-Mapper which is supposed to implement all the nitty-gritty details of an RDBMS system, Hibernate,
|
||||
and JPA for that matter, still often has the developer go back to understanding these details.</p>
|
||||
|
||||
<p>Strolch tries a different approach to persistence. Instead of writing pojos/entities, Strolch's model has the
|
||||
concept that each element's attributes are part of a composition pattern: each attribute is its own object
|
||||
and thus can be dynamically changed at runtime, but also makes persistence of such an element generic.
|
||||
Instead of having fixed attributes for a concrete class, these parameters are stored in a map and are
|
||||
accessed through the parameter's ID.</p>
|
||||
concept that each element's attributes are part of a composition pattern: each attribute is its own object
|
||||
and thus can be dynamically changed at runtime, but also makes persistence of such an element generic.
|
||||
Instead of having fixed attributes for a concrete class, these parameters are stored in a map and are
|
||||
accessed through the parameter's ID.</p>
|
||||
|
||||
<p>Assigning an ID to an attribute for accessing of course brings its own downsides, i.e. the parameter might
|
||||
simply not be there, when being accessed. This is certainly an issue that the developer must handle, when
|
||||
implementing a project using Strolch, but allows the developer to not need to worry about persistence, as
|
||||
this is generically handled.</p>
|
||||
simply not be there, when being accessed. This is certainly an issue that the developer must handle, when
|
||||
implementing a project using Strolch, but allows the developer to not need to worry about persistence, as
|
||||
this is generically handled.</p>
|
||||
|
||||
<p>Since the persistence is generically handled, and Strolch stays lightweight on its requirements at runtime,
|
||||
the developer can quickly get down to what is important for business value: Writing the business logic and
|
||||
the presentation layer. Here too Strolch tries to help the developer by bringing in concepts which are easy
|
||||
to follow: Use cases are implemented as Services, and re-usable business logic is put into Commands.</p>
|
||||
the developer can quickly get down to what is important for business value: Writing the business logic and
|
||||
the presentation layer. Here too Strolch tries to help the developer by bringing in concepts which are easy
|
||||
to follow: Use cases are implemented as Services, and re-usable business logic is put into Commands.</p>
|
||||
|
||||
<p>There will be reasons against using Strolch, as there will be against using the Java EE stack, or an
|
||||
OR-Mapper or even the Java ecosystem for that fact. Important is to note, that the concepts behind Strolch
|
||||
are nothing new, but have been implemented in at least two previous proprietary products. Since those
|
||||
products are not accessible to the public, it was decided that a re-implementation might be of use to the
|
||||
programming community at large.</p>
|
||||
OR-Mapper or even the Java ecosystem for that fact. Important is to note, that the concepts behind Strolch
|
||||
are nothing new, but have been implemented in at least two previous proprietary products. Since those
|
||||
products are not accessible to the public, it was decided that a re-implementation might be of use to the
|
||||
programming community at large.</p>
|
||||
|
||||
<p>Currently there is at least one company using Strolch in a commercial project which helps drive Strolch's
|
||||
development and further motivates its existence.</p>
|
||||
development and further motivates its existence.</p>
|
||||
|
||||
<p>Strolch is an open source project and licensed under the Apache License 2.0.</p>
|
||||
|
||||
<h2>Technologoy</h2>
|
||||
|
||||
<p>Strolch is written in Java and is programmed against the JDK 8. Strolch runs on any JRE 8 compliant
|
||||
environment. Strolch is tested on the Oracle JRE 8.</p>
|
||||
environment. Strolch is tested on the Oracle JRE 8.</p>
|
||||
|
||||
<h3>Dependencies</h3>
|
||||
|
||||
<p>Strolch strives to use as few external dependencies as possible, so that the Strolch runtime is not bloated
|
||||
unnecessarily. The following list of Strolch dependencies is a summary and was created using mvn
|
||||
dependency:tree on the strolch_minimal project on the 2016-09-16.</p>
|
||||
unnecessarily. The following list of Strolch dependencies is a summary and was created using mvn
|
||||
dependency:tree on the strolch_minimal project for release 1.6.47.</p>
|
||||
|
||||
<h4>Basic runtime dependencies</h4>
|
||||
<p>Logging</p>
|
||||
<ul>
|
||||
<li>commons-cli:commons-cli:jar:1.2:compile
|
||||
<p>Implements the command line parameter parsing when starting from a main class</p></li>
|
||||
|
||||
<li>org.postgresql:postgresql:jar:9.4.1208.jre7:compile
|
||||
<p>Implements the PostgreSQL Persistence layer used by li.strolch.persistence.postgresql</p></li>
|
||||
<li>com.zaxxer:HikariCP:jar:2.3.6:compile
|
||||
<p>Implements connection pooling for JDBC access</p></li>
|
||||
|
||||
<li>com.google.code.gson:gson:jar:2.3.1:compile
|
||||
<p>Used to transform to JSON</p></li>
|
||||
|
||||
<li>javax.activation:activation:jar:1.1:compile
|
||||
<p>Used when sending e-mails</p></li>
|
||||
<li>javax.mail:mail:jar:1.5.0-b01:compile
|
||||
<p>Used when sending e-mails</p></li>
|
||||
|
||||
<li>log4j:log4j:jar:1.2.17:runtime
|
||||
<p>Used for logging</p></li>
|
||||
<li>org.slf4j:slf4j-api:jar:1.7.2:compile
|
||||
<p>Used for logging</p></li>
|
||||
<li>org.slf4j:slf4j-log4j12:jar:1.7.2:runtime
|
||||
<p>Used for logging</p></li>
|
||||
<li>org.slf4j:slf4j-api:jar:1.7.25</li>
|
||||
<li>ch.qos.logback:logback-classic:jar:1.2.3</li>
|
||||
<li>ch.qos.logback:logback-core:jar:1.2.3</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h4>Web Restful dependencies</h4>
|
||||
|
||||
<p>If you want to access Strolch using the RESTful API, then we got you covered - but sadly RESTful service
|
||||
development requires quite a few extra dependencies:</p>
|
||||
<p>Utils</p>
|
||||
<ul>
|
||||
<li>com.github.petitparser.java-petitparser:petitparser-core:jar:2.0.2:compile</li>
|
||||
<li>javax.annotation:javax.annotation-api:jar:1.2:compile</li>
|
||||
<li>javax.servlet:javax.servlet-api:jar:3.0.1:provided</li>
|
||||
<li>javax.validation:validation-api:jar:1.1.0.Final:compile</li>
|
||||
<li>javax.ws.rs:javax.ws.rs-api:jar:2.0:compile</li>
|
||||
<li>org.eclipse.persistence:org.eclipse.persistence.antlr:jar:2.5.0:compile</li>
|
||||
<li>org.eclipse.persistence:org.eclipse.persistence.asm:jar:2.5.0:compile</li>
|
||||
<li>org.eclipse.persistence:org.eclipse.persistence.core:jar:2.5.0:compile</li>
|
||||
<li>org.eclipse.persistence:org.eclipse.persistence.moxy:jar:2.5.0:compile</li>
|
||||
<li>org.glassfish.hk2.external:aopalliance-repackaged:jar:2.3.0-b05:compile</li>
|
||||
<li>org.glassfish.hk2.external:javax.inject:jar:2.3.0-b05:compile</li>
|
||||
<li>org.glassfish.hk2:hk2-api:jar:2.3.0-b05:compile</li>
|
||||
<li>org.glassfish.hk2:hk2-locator:jar:2.3.0-b05:compile</li>
|
||||
<li>org.glassfish.hk2:hk2-utils:jar:2.3.0-b05:compile</li>
|
||||
<li>org.glassfish.hk2:osgi-resource-locator:jar:1.0.1:compile</li>
|
||||
<li>org.glassfish.jersey.bundles.repackaged:jersey-guava:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-servlet-core:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-servlet:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.core:jersey-client:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.core:jersey-common:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.core:jersey-server:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.ext:jersey-entity-filtering:jar:2.11:compile</li>
|
||||
<li>org.glassfish.jersey.media:jersey-media-moxy:jar:2.11:compile</li>
|
||||
<li>org.javassist:javassist:jar:3.18.1-GA:compile</li>
|
||||
<li>javax.mail:javax.mail-api:jar:1.6.0</li>
|
||||
<li>com.sun.mail:javax.mail:jar:1.6.0</li>
|
||||
<li>javax.activation:activation:jar:1.1</li>
|
||||
</ul>
|
||||
|
||||
<p>Testing</p>
|
||||
<ul>
|
||||
<li>junit:junit:jar:4.12</li>
|
||||
<li>org.hamcrest:hamcrest-core:jar:1.3</li>
|
||||
<li>org.hamcrest:hamcrest-library:jar:1.3</li>
|
||||
<li>org.mockito:mockito-core:jar:2.0.8-beta</li>
|
||||
<li>org.objenesis:objenesis:jar:2.1</li>
|
||||
</ul>
|
||||
|
||||
<p>Model</p>
|
||||
<ul>
|
||||
<li>com.google.code.gson:gson:jar:2.8.2</li>
|
||||
</ul>
|
||||
|
||||
<p>SOQL</p>
|
||||
<ul>
|
||||
<li>org.abego.treelayout:org.abego.treelayout.core:jar:1.0.3</li>
|
||||
<li>org.antlr:antlr-runtime:jar:3.5.2</li>
|
||||
<li>org.antlr:antlr4-runtime:jar:4.7</li>
|
||||
<li>org.antlr:antlr4:jar:4.7</li>
|
||||
<li>org.antlr:ST4:jar:4.0.8</li>
|
||||
<li>org.glassfish:javax.json:jar:1.0.4</li>
|
||||
<li>com.ibm.icu:icu4j:jar:58.2</li>
|
||||
</ul>
|
||||
|
||||
<p>PostgreSQL</p>
|
||||
<ul>
|
||||
<li>com.zaxxer:HikariCP:jar:2.7.1</li>
|
||||
<li>org.postgresql:postgresql:jar:42.1.4</li>
|
||||
</ul>
|
||||
|
||||
<p>REST</p>
|
||||
<ul>
|
||||
<li>javax.annotation:javax.annotation-api:jar:1.3.1</li>
|
||||
<li>javax.servlet:javax.servlet-api:jar:3.1.0</li>
|
||||
<li>javax.ws.rs:javax.ws.rs-api:jar:2.1</li>
|
||||
</ul>
|
||||
|
||||
<p>REST testing</p>
|
||||
<ul>
|
||||
<li>javax.validation:validation-api:jar:1.1.0.Final</li>
|
||||
<li>org.glassfish.grizzly:grizzly-framework:jar:2.3.28</li>
|
||||
<li>org.glassfish.grizzly:grizzly-http-server:jar:2.3.28</li>
|
||||
<li>org.glassfish.grizzly:grizzly-http-servlet:jar:2.3.28</li>
|
||||
<li>org.glassfish.grizzly:grizzly-http:jar:2.3.28</li>
|
||||
<li>org.glassfish.hk2:hk2-api:jar:2.5.0-b32</li>
|
||||
<li>org.glassfish.hk2:hk2-locator:jar:2.5.0-b32</li>
|
||||
<li>org.glassfish.hk2:hk2-utils:jar:2.5.0-b32</li>
|
||||
<li>org.glassfish.hk2:osgi-resource-locator:jar:1.0.1</li>
|
||||
<li>org.glassfish.hk2.external:aopalliance-repackaged:jar:2.5.0-b32</li>
|
||||
<li>org.glassfish.hk2.external:javax.inject:jar:2.5.0-b32</li>
|
||||
<li>org.glassfish.jersey.bundles.repackaged:jersey-guava:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-grizzly2-http:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-grizzly2-servlet:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-servlet-core:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.containers:jersey-container-servlet:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.core:jersey-client:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.core:jersey-common:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.core:jersey-server:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.media:jersey-media-jaxb:jar:2.25.1</li>
|
||||
<li>org.glassfish.jersey.test-framework:jersey-test-framework-core:jar:2.25.1</li>
|
||||
<li>org.javassist:javassist:jar:3.20.0-GA</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h4>API</h4>
|
||||
|
||||
<p>Check out the <a href="api.html">API page</a> to see how to use Strolch.</p>
|
||||
|
|
@ -237,7 +257,7 @@
|
|||
s.parentNode.insertBefore(g, s);
|
||||
})();
|
||||
</script>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt=""/></p></noscript>
|
||||
<noscript><p><img src="http://piwik.eitchnet.ch/piwik.php?idsite=2" style="border:0;" alt="" /></p></noscript>
|
||||
<!-- End Piwik Code -->
|
||||
|
||||
</body>
|
||||
|
|
|
|||
Loading…
Reference in New Issue