Add documentation for modules (MOAID-47)

author: Thomas Knall <t.knall@datentechnik-innovation.com> 2015-02-05 16:56:31 +0100
committer: Thomas Knall <t.knall@datentechnik-innovation.com> 2015-02-05 16:56:31 +0100
commit: e8f5883a7982b8f5682c917f214d607a3cadb489 (patch)
tree: 2cb5eff03e7aaf58c52f5832a79e96940313973c /id/server/doc
parent: b864faef2864cc28df98d778e2221bf2cf911954 (diff)
download: moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.tar.gz
moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.tar.bz2
moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.zip
3 files changed, 405 insertions, 0 deletions
diff --git a/id/server/doc/handbook/index.html b/id/server/doc/handbook/index.html
index c3b25b390..7e89b7c8f 100644
--- a/id/server/doc/handbook/index.html
+++ b/id/server/doc/handbook/index.html
@@ -32,6 +32,8 @@
     <dd>Erl&auml;utert die Integration in bestehende Online-Applikationen und beschreibt die beigelegten Demo Applikationen</dd>
     <dt><a href="./additional/additional.html">Zusatzinformationen</a></dt>
     <dd>Spezifiziert allgemeine Funktionen des Modules MOA-ID-Auth</dd>
+    <dt><a href="./moduledevinfo/moduledevinfo.html">Informationen f&uuml;r Modul-Entwickler</a></dt>
+    <dd>Enth&auml;lt Informationen f&uuml;r Entwickler von MOA-ID Modulen.</dd>
   </dl>
   <dl>
     <dt>&nbsp;</dt>
diff --git a/id/server/doc/handbook/moduledevinfo/ProcessDefinition.xsd b/id/server/doc/handbook/moduledevinfo/ProcessDefinition.xsd
new file mode 100644
index 000000000..d6ab7ae46
--- /dev/null
+++ b/id/server/doc/handbook/moduledevinfo/ProcessDefinition.xsd
@@ -0,0 +1,53 @@
+ď»ż<?xml version="1.0" encoding="UTF-8"?>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+	targetNamespace="http://reference.e-government.gv.at/namespace/moa/process/definition/v1"
+	xmlns:tns="http://reference.e-government.gv.at/namespace/moa/process/definition/v1"
+	elementFormDefault="qualified" version="1.0">
+
+	<xsd:element name="ProcessDefinition">
+		<xsd:complexType>
+			<xsd:sequence>
+				<xsd:choice minOccurs="0" maxOccurs="unbounded">
+					<xsd:element name="StartEvent" type="tns:StartEventType" />
+					<xsd:element name="Task" type="tns:TaskType" />
+					<xsd:element name="Transition" type="tns:TransitionType" />
+					<xsd:element name="EndEvent" type="tns:EndEventType" />
+				</xsd:choice>
+			</xsd:sequence>
+			<xsd:attribute name="id" type="xsd:ID" use="required" />
+		</xsd:complexType>
+	</xsd:element>
+
+	<xsd:complexType name="ProcessNodeType" abstract="true">
+		<xsd:attribute name="id" type="xsd:ID" use="required" />
+	</xsd:complexType>
+
+	<xsd:complexType name="StartEventType">
+		<xsd:complexContent>
+			<xsd:extension base="tns:ProcessNodeType" />
+		</xsd:complexContent>
+	</xsd:complexType>
+
+	<xsd:complexType name="TransitionType">
+		<xsd:attribute name="from" type="xsd:IDREF" use="required" />
+		<xsd:attribute name="to" type="xsd:IDREF" use="required" />
+		<xsd:attribute name="id" type="xsd:ID" />
+		<xsd:attribute name="conditionExpression" type="xsd:string" />
+	</xsd:complexType>
+
+	<xsd:complexType name="EndEventType">
+		<xsd:complexContent>
+			<xsd:extension base="tns:ProcessNodeType" />
+		</xsd:complexContent>
+	</xsd:complexType>
+
+	<xsd:complexType name="TaskType">
+		<xsd:complexContent>
+			<xsd:extension base="tns:ProcessNodeType">
+				<xsd:attribute name="async" type="xsd:boolean" default="false"/>
+				<xsd:attribute name="class" type="xsd:string" />
+			</xsd:extension>
+		</xsd:complexContent>
+	</xsd:complexType>
+
+</xsd:schema>
diff --git a/id/server/doc/handbook/moduledevinfo/moduledevinfo.html b/id/server/doc/handbook/moduledevinfo/moduledevinfo.html
new file mode 100644
index 000000000..c9cae99f3
--- /dev/null
+++ b/id/server/doc/handbook/moduledevinfo/moduledevinfo.html
@@ -0,0 +1,350 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+
+<head>
+	<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
+	<title>MOA-ID - Informationen für Modul-Entwickler</title>
+	<link rel="stylesheet" href="../common/MOA.css" type="text/css">
+	<style type="text/css">
+	span {
+		font-family: 'Courier New';
+		font-size: 10pt;
+		color: #000000;
+	}
+	.sc0 {
+		font-weight: bold;
+	}
+	.sc1, .sc12, .sc13 {
+		color: #0000FF;
+	}
+	.sc3 {
+		color: #FF0000;
+	}
+	.sc6 {
+		font-weight: bold;
+		color: #8000FF;
+	}
+	.sc8 {
+	}
+	.sc9 {
+		color: #008000;
+	}
+	.sc11 {
+		color: #0000FF;
+	}
+	table {
+		border-collapse: collapse;
+	}
+	table, th, td {
+		border: thin solid gray;
+	}
+	</style>
+</head>
+
+<body link="#990000">
+
+	<table class="logoTable" width="100%" border="0" cellspacing="0"
+		cellpadding="10">
+		<tr>
+			<td align="center" class="logoTitle" width="267">
+				<img src="../common/LogoBKA.png" alt="Logo BKA" width="267" height="37" align="left">
+			</td>
+			<td align="center" class="logoTitle">Dokumentation</td>
+			<td align="center" class="logoTitle" width="123">
+				<img src="../common/LogoEGIZ.png" alt="Logo EGIZ" width="230" height="81" align="right">
+			</td>
+		</tr>
+	</table>
+	<hr />
+	
+	<p class="title">
+		<a href="../index.html">MOA-ID (Identifikation)</a>
+	</p>
+	<p class="subtitle">Informationen für Modul-Entwickler</p>
+	<hr />
+
+
+	<h1>Inhalt</h1>
+	<ol>
+		<li>
+			<p>
+				<a href="#uebersicht">Übersicht</a>
+			</p>
+		</li>
+		<li>
+			<p>
+				<a href="#prozesse">Prozesse</a>
+			</p>
+			<ol>
+				<li><a href="#tasks">Aufgaben (Tasks)</a></li>
+				<li><a href="#transitions">Transitions</a></li>
+			</ol>
+		</li>
+		<li>
+			<p>
+				<a href="#module">Module</a>
+			</p>
+			<ol>
+				<li><a href="#processselection">Metadaten und Prozessauswahl</a></li>
+				<li>
+					<p>
+						<a href="#discovery">Discovery</a>
+					</p>
+					<ol>
+						<li><a href="#serviceloader">Service Loader Mechanismus</a></li>
+						<li><a href="#springbean">Spring Bean Discovery</a></li>
+					</ol>
+				</li>
+			</ol>
+		</li>
+	</ol>
+	<hr />
+
+
+	<h1>
+		<a name="uebersicht" id="uebersicht">1 &Uuml;bersicht</a>
+	</h1>
+	<p>
+		MOA-ID ab Version 2.3 ermöglicht die dynamische Erweiterung um zusätzliche Funktionalität durch die Nutzung der
+		integrierten Modularchitektur.<br/>
+		Entwickler können nun eigene Prozesse, um die MOA-ID erweitert werden soll, definieren (z.B. Unterstützung
+		eines speziellen Authentifizierungsworkflows, Erweiterung um Vollmachten oder ausländische Identitäten etc).
+		MOA-ID bietet eine Ablaufsteuerung ("ProcessEngine"), die einzelne Aufgaben (Tasks) entsprechend einer vorgegebenen Prozessdefinition
+		abarbeiten kann.
+	</p>
+	<p>
+		Mehrere Prozesse können zu einzelnen Modulen zusammengefasst werden. Ein Modul, typischerweise repräsentiert durch eine separate JAR-Datei, wird	automatisch erkannt, sobald sich
+		dieses im Classpath der Anwendung befindet. Damit stehen die in diesem Modul definierten Prozesse MOA-ID
+		automatisch zu Verfügung.
+	</p>
+	<p>
+		Beim Starten eines Authentifizierungsvorgangs speichert MOA-ID die zu diesem Zeitpunkt zu Verfügung stehenden
+		Informationen (Ergebnis der BKU-Auswahl, Auswahl des Herkunftslandes, Wunsch nach Vollmachten-Nutzung etc.) in
+		eine Datenstruktur ("ExecutionContext"). Module	entscheiden dann auf Basis dieser Informationen, ob sie entsprechende Prozesse für den gegebenen Kontext anbieten können. Sobald ein
+		passender Prozess gefunden wurde, beginnt die MOA-ID ProcessEngine mit der Ausführung der darin definierten
+		Aufgaben.
+	</p>
+	<p>
+		Bei diesen Aufgaben handelt es sich typischerweise um einzelne synchrone oder asynchrone Schritte eines kompletten
+		Authentifizierungsvorgangs wie z.B. das Erstellen eines HTML-Formulars zum Auslesen der Personenbindung (synchron),
+		das Empfangen und Verarbeiten einer	Personenbindung (asynchron), das Aushandeln einer Session mit dem Vollmachtenportal (synchron) etc.
+		Jeder Task erhält bei Ausführung automatisch Zugriff auf den ExecutionContext, der von Task zu Task weitergereicht, zum Austausch bzw. Akkumulieren von Daten dient und schließlich auch persistiert wird.
+		Darüber hinaus steht jeweils HttpServletRequest und HttpServletResponse zu Verfügung.
+	</p>
+
+	<h1>
+		<a name="prozesse" id="prozesse">2 Prozesse</a>
+	</h1>
+	<p>
+		Ein Prozess definiert sich primär über seine Tasks, die es in einer bestimmten Abfolge abzuarbeiten gilt. Um welche Tasks es sich handelt und wie die Abfolge unter welchen Bedingungen aussieht wird in einer
+		ProzessDefinition in Form eines XML-Dokuments festgelegt. 
+	</p>
+	<p>Siehe <a href="ProcessDefinition.xsd">ProcessDefinition.xsd</a>.<br/>&nbsp;</p>
+	
+	<p>
+		Die folgende Prozessdefinition zeigt als Beispiel den internen Standard-Authentifizierungsprozess von MOA-ID. Dieser unterstützt Vollmachten uns ausländische Identitäten:<br/>&nbsp;
+	</p>
+	<div style="float: left; white-space: pre; line-height: 1; background: #FFFFFF; "><span class="sc1">&lt;?xml</span><span class="sc8"> </span><span class="sc3">version</span><span class="sc8">=</span><span class="sc6">"1.0"</span><span class="sc8"> </span><span class="sc3">encoding</span><span class="sc8">=</span><span class="sc6">"UTF-8"?&gt;</span><span class="sc0">
+</span><span class="sc1">&lt;pd:ProcessDefinition</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"DefaultAuthentication"</span><span class="sc8"> </span><span class="sc3">xmlns:pd</span><span class="sc8">=</span><span class="sc6">"http://reference.e-government.gv.at/namespace/moa/process/definition/v1"</span><span class="sc1">&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8">    </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.CreateIdentityLinkFormTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyIdentityLinkTask"</span><span class="sc8">        </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyAuthenticationBlockTask"</span><span class="sc8"> </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.VerifyCertificateTask"</span><span class="sc8">         </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8">           </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.GetMISSessionIDTask"</span><span class="sc8">           </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8">    </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.CertificateReadRequestTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.PrepareAuthBlockSignatureTask"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Task</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8">              </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.internal.tasks.GetForeignIDTask"</span><span class="sc8">              </span><span class="sc3">async</span><span class="sc8">=</span><span class="sc6">"true"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;pd:StartEvent</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"start"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"start"</span><span class="sc8">                     </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"createIdentityLinkForm"</span><span class="sc8">    </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"!ctx['identityLinkAvailable'] || ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyIdentityLink"</span><span class="sc8">        </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"prepareAuthBlockSignature"</span><span class="sc8"> </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"certificateReadRequest"</span><span class="sc8">    </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyCertificate"</span><span class="sc8">         </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8"> </span><span class="sc3">conditionExpression</span><span class="sc8">=</span><span class="sc6">"ctx['useMandate']"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"verifyAuthBlock"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"getMISSessionID"</span><span class="sc8">           </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;pd:Transition</span><span class="sc8"> </span><span class="sc3">from</span><span class="sc8">=</span><span class="sc6">"getForeignID"</span><span class="sc8">              </span><span class="sc3">to</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    
+    </span><span class="sc1">&lt;pd:EndEvent</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"end"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+</span><span class="sc1">&lt;/pd:ProcessDefinition&gt;</span><span class="sc0">
+</span></div>
+<p style="clear:left;">&nbsp;</p>
+	
+	<p>
+		Jede Prozessbeschreibung muss zwingend ein <code>StartEvent</code> und ein <code>EndEvent</code> enthalten.
+		Einzelne Aufgaben sind durch <code>Task</code>-Elemente gekennzeichnet, wobei via Attribut <code>async</code>
+		festgelegt wird ob es sich dabei um einen synchronen (Standardeinstellung) oder um einen asynchronen Task handelt (siehe auch <a href="#tasks">Abschnitt 2.1</a>).
+	</p>
+
+	<h2>
+		<a name="tasks" id="tasks">2.1 Aufgaben (Tasks)</a>
+	</h2>
+	<p>
+		Aus technischer Sicht sind Aufgaben einfache Klassen, die die abstrakte Klasse <code>at.gv.egovernment.moa.id.process.springweb.MoaIdTask</code> (moa-id-lib-xy.jar)
+		implementieren. Diese definiert lediglich eine <code>execute</code>-Methode, die aufgerufen wird, sobald der Task
+		von der ProcessEngine gestartet wird. Über diese Methode erhält der Task Zugriff auf den ExecutionContext sowie
+		auf HttpServletRequest und HttpServletResponse. Der HttpServletRequest und der ExecutionContext können nun ausgewertet, bzw. falls notwendig der ExecutionContext und die HttpServletResponse auch manipuliert werden.
+	</p>
+	<p>
+		Als Beispiele typischer Tasks können die Klassen im package <code>at.gv.egovernment.moa.id.auth.modules.internal.tasks</code> herangezogen werden.<br/>
+	</p>
+
+	<h2>
+		<a name="transitions" id="transitions">2.2 Transitions</a>
+	</h2>
+	<p>
+		Die Abfolge der einzelnen Task wird in der Prozessbeschreibung durch die <code>Transition</code>-Elemente
+		bestimmt. Diese weisen die zwei verpflichtenden Attribute <code>from</code> und <code>to</code> auf, die jeweils einen Task (oder StartEvent) referenzieren <strong>von</strong> (<code>from</code>) dem die ProzessEngine <strong>zu</strong> (<code>to</code>) weiteren Task (oder EndEvent) traversiert. Betrachtet man einen
+		Prozess als Graphen, dann sind die Tasks als Knoten und die Transitions als Kanten anzusehen.
+	</p>
+	<p>
+		Jede Prozessausführung beginnt mit dem <code>StartEvent</code>. Von diesem ausgehend werden alle möglichen
+		Transitions zu anderen Tasks untersucht. Die erste Transition, die eine gültige Verbindung zu einem anderen Task
+		aufweist wird für die weitere Prozessausführung herangezogen. Transitions können über das Attribut
+		<code>conditionExpression</code> mit einer Art Policy ausgestattet werden, die festlegt, ob eine Transition verwendet
+		werden kann oder nicht. Dies ermöglicht eine bedingte Ausführung von Tasks.
+	</p>
+	<p>
+		Expressions müssen sich in eine booleschen Wert auflösen lassen: <code>true</code> (genauso
+		wie ein nicht gesetztes <code>conditionExpression</code>-Attribut) bedeutet, dass die Transition verwendet werden kann,
+		<code>false</code> bedeutet, dass die Transition nicht verwendet wird.
+		Bei den Expressions handelt es sich um <a href="http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/html/expressions.html">Spring EL Expressions</a>,
+		die einen leichten Zugriff auf den ExecutionContext, HttpServletRequestParameter sowie beliebige Spring-Beans ermöglichen:
+	</p>	
+	<table cellspacing="0" cellpadding="5">
+		<tr>
+			<th>Bezeichner</th>
+			<th>Beispiel</th>
+			<th>Bedeutung</th>
+		</tr>
+		<tr>
+			<td><code>ctx</code></td>
+			<td><code>!ctx['identityLinkAvailable']</code></td>
+			<td>Erlaubt das Auswerten einzelner Variablen aus dem ExecutionContext, in diesem Fall einer booleschen Variable <code>identityLinkAvailable</code></td>
+		</tr>
+		<tr>
+			<td><code>requestParameter</code></td>
+			<td><code>requestParameter['myParam'] != null</code></td>
+			<td>Greift auf RequestParameter aus dem HttpServletRequest zurück und ermöglicht so eine Requestparameter abhängige Abfolge von Tasks.</td>
+		</tr>
+		<tr>
+			<td><code>@</code></td>
+			<td><code>@mySpringBean.isFoo()</code></td>
+			<td>Greift auf ein Bean (in diesem Fall mit dem Namen <code>mySpringBean</code>) aus dem Spring ApplicationContext zurück.</td>
+		</tr>
+	</table>
+
+	<h1>
+		<a name="module" id="module">3 Module</a>
+	</h1>
+	<p>
+		Bei einem Modul handelt es sich grundsätzlich lediglich um eine logische Gruppierung von Prozessen.
+		Module sind bedingt durch ihr automatisches Discovery als eine Art Plug-in zu betrachten, weshalb sie typischerweise
+		auch in eigene JAR-Dateien ausgelagert vorliegen.
+	</p>
+	<p>Als Beispiel eines solchen Moduls kann das STORK-Modul (<code>moa-id-module-stork-xy.jar</code>) gesehen werden.
+
+	<h2>
+		<a name="processselection" id="processselection">3.1 Metadaten und Prozessauswahl</a>
+	</h2>
+	<p>
+		Jedes Modul muss das Interface <code>at.gv.egovernment.moa.id.auth.modules.AuthModule</code> implementieren, über
+		das der ProcessEngine zum einen Metadaten zu Verfügung gestellt werden, diese zum anderen aber auch die Prozessauswahl
+		(siehe <a href="#uebersicht">Abschnitt&nbsp;1</a>) abgewickelt wird.
+	</p>
+	<p>
+		<dl>
+			<dt><code>int getPriority()</code></dt>
+			<dd>Über diese Methode gibt das Modul seine Priorität bekannt. Dies beeinflusst die Reihenfolge des Moduls
+			bei der Abfrage nach passenden Prozessen beim Starten eines Authentifizierungsprozesses.<br/>
+			Standardpriorität ist <code>0</code>. Module die vorgereiht werden sollen, müssen eine höhere Priorität aufweisen.</dd>
+		</dl>
+		<dl>
+			<dt><code>String[] getProcessDefinitions()</code></dt>
+			<dd>Hierüber gibt das Modul die Prozessdefinitionen (bzw. ResourceUris zu den entsprechenden XML-Dateien) bekannt.
+			Diese werden automatisch von MOA-ID geparst und registriert.
+			</dd>
+		</dl>
+		<dl>
+			<dt><code>String selectProcess(ExecutionContext context)</code></dt>
+			<dd>Diese Methode wird von MOA-ID beim Starten eines Authentifizierungsprozesses aufgerufen. Der ExecutionContext
+			wird mit den in oben in <a href="#uebersicht">Abschnitt&nbsp;1</a> erwähnten Informationen befüllt und dieser
+			dann der <code>selectProcess</code>-Methode übergeben. Diese entscheidet, ob ein passender Prozess zu Verfügung
+			steht oder nicht. Eine eventuelle modulinterne Priorisierung muss das Modul selbst vornehmen.</dd>
+		</dl>
+	</p>
+	<p>
+		Als Beispiel kann die Implementierung des STORK-Moduls herangezogen werden: <code>at.gv.egovernment.moa.id.auth.modules.stork.STORKAuthModuleImpl</code><br/>
+		Nähere Informationen sind der Javadoc Dokumentation des AuthModule Interfaces zu entnehmen.
+	</p>
+	
+	<h2>
+		<a name="discovery" id="discovery">3.2 Discovery</a>
+	</h2>
+	<p>
+		Das bereits erwähnte automatische Discovery von Modulen beschränkt sich nun auf das automatische Auffinden der
+		jeweiligen <code>AuthModule</code>-Implementierung. MOA-ID sieht zwei Varianten vor, derartige Implementierung
+		aufzufinden. Welche der beiden zur Anwendung kommt (es können notfalls auch beide kombiniert werden), bleibt dem Modulentwickler überlassen.
+	</p>
+
+	<h3>
+		<a name="serviceloader" id="serviceloader">3.2.1 Service Loader Mechanismus</a>
+	</h3>
+	<p>
+		Diese Variante sieht vor, dass jedes Modul (d.h. jede JAR-Datei) eine Datei <code>META-INF/services/at.gv.egovernment.moa.id.auth.modules.AuthModule</code>
+		enhält, das die vorhandenen AuthModule-Implementierungen auflistet:
+	</p>
+	<pre>at.gv.egovernment.moa.id.auth.modules.internal.DefaultAuthModuleImpl
+at.gv.egovernment.moa.id.auth.modules.mymodule.MyAuthModuleImpl</pre>
+	<p>
+		Nähere Informationen zu diesem Mechanismus können hier entnommen werden:
+		<a href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">Javadoc ServiceLoader</a> bzw. <a href="http://docs.oracle.com/javase/tutorial/ext/basics/spi.html">Java Tutorials: Creating Extensible Applications</a>
+	</p>
+	
+	<h3>
+		<a name="springbean" id="springbean">3.2.2 Spring Bean Discovery</a>
+	</h3>
+	<p>
+		Für den Fall, dass Module auf Basis des Spring Frameworks entwickelt werden, kann die AuthModule-Implementierung auch als Spring Bean erfolgen.
+	</p>
+	<p>
+		MOA-ID sucht beim Starten im Classpath nach Bean-Definitionen, die der Dateinamenskonvention <code>*.authmodule.beans.xml</code>
+		entsprechen und importiert diese. Über diesen Mechanismus können modulspezifische Spring Beans geladen bzw. initialisiert werden, u.a. auch AuthModule-Beans.<br/>&nbsp;
+	</p>
+	<p>Beispiel: <code>STORK.authmodule.beans.xml</code><br/>&nbsp;</p>
+	
+	<div style="float: left; white-space: pre; line-height: 1; background: #FFFFFF; "><span class="sc12">&lt;?</span><span class="sc1">xml</span><span class="sc8"> </span><span class="sc3">version</span><span class="sc8">=</span><span class="sc6">"1.0"</span><span class="sc8"> </span><span class="sc3">encoding</span><span class="sc8">=</span><span class="sc6">"UTF-8"</span><span class="sc13">?&gt;</span><span class="sc0">
+</span><span class="sc1">&lt;beans</span><span class="sc8"> </span><span class="sc3">xmlns</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/beans"</span><span class="sc8">
+    </span><span class="sc3">xmlns:xsi</span><span class="sc8">=</span><span class="sc6">"http://www.w3.org/2001/XMLSchema-instance"</span><span class="sc8">
+    </span><span class="sc3">xmlns:context</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/context"</span><span class="sc8">
+    </span><span class="sc3">xsi:schemaLocation</span><span class="sc8">=</span><span class="sc6">"http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd"</span><span class="sc1">&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;context:annotation-config</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+
+    </span><span class="sc1">&lt;bean</span><span class="sc8"> </span><span class="sc3">id</span><span class="sc8">=</span><span class="sc6">"storkAuthModule"</span><span class="sc8"> </span><span class="sc3">class</span><span class="sc8">=</span><span class="sc6">"at.gv.egovernment.moa.id.auth.modules.stork.STORKAuthModuleImpl"</span><span class="sc1">&gt;</span><span class="sc0">
+        </span><span class="sc1">&lt;property</span><span class="sc8"> </span><span class="sc3">name</span><span class="sc8">=</span><span class="sc6">"priority"</span><span class="sc8"> </span><span class="sc3">value</span><span class="sc8">=</span><span class="sc6">"0"</span><span class="sc8"> </span><span class="sc11">/&gt;</span><span class="sc0">
+    </span><span class="sc1">&lt;/bean&gt;</span><span class="sc0">
+
+</span><span class="sc1">&lt;/beans&gt;</span><span class="sc0">
+</span></div>
+	<p style="clear:left;">&nbsp;</p>	
+	
+	<p>&nbsp;</p>
+	<p>&nbsp;</p>
+</body>
+</html>
author	Thomas Knall <t.knall@datentechnik-innovation.com>	2015-02-05 16:56:31 +0100
committer	Thomas Knall <t.knall@datentechnik-innovation.com>	2015-02-05 16:56:31 +0100
commit	e8f5883a7982b8f5682c917f214d607a3cadb489 (patch)
tree	2cb5eff03e7aaf58c52f5832a79e96940313973c /id/server/doc
parent	b864faef2864cc28df98d778e2221bf2cf911954 (diff)
download	moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.tar.gz moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.tar.bz2 moa-id-spss-e8f5883a7982b8f5682c917f214d607a3cadb489.zip