Wiki-Quellcode von IPluginWorkflowNode

Zeige letzte Bearbeiter
1 {{content/}}
2
3 == Schnittstelle IPluginWorkflowNode ==
4
5 Diese Schnittstelle ermöglicht es, eine eigenen Node-Typ zum Workflow hinzuzufügen. Eine Node ist hierbei ein Knoten im Syntaxbaum einer Workflow-Verarbeitungskette. Der Wurzelknoten jedes solchen Syntaxbaums hat den Node-Typ "Sequenz". Ein Beispiel für solch einen Syntaxbaum ist etwa:
6
7 * Sequenz
8 ** Aktion "E-Mail versenden"
9 ** Bedingung
10 *** Sequenz (If)
11 **** Aktion "Textdatei erzeugen"
12 **** Aktion "PDF befüllen"
13 *** Sequenz (Else)
14 **** Aktion "HTTP-Request"
15 **** Aktion "Word befüllen"
16 ** Aktion "Externe Resource herunterladen"
17 ** Switch (Wert [%tf1%])
18 *** Default-Case
19 **** Sequenz
20 ***** Aktion "Textdatei erzeugen"
21 *** Switch-Case (wenn Wert gleich 1)
22 **** Sequenz
23 ***** Aktion "Textdatei erzeugen"
24 *** Switch-Case (wenn Wert gleich 2)
25 **** Sequenz
26 ***** Aktion "Textdatei erzeugen"
27 ** Aktion "Abschlussseite"
28 ** Experiment
29 *** Sequenz
30 **** Aktion "HTTP-Request ausführen"
31 *** Sequenz
32 **** Aktion "E-Mail an Administrator senden"
33
34 Dabei ist
35
36 * die Sequenz ist ein Knoten, welche seine Kinderknoten der Reihe nach ausführt
37 * die Bedingung ein Knoten, welcher eine Bedingung überprüft und je nach Resultat einen der beiden Kinderknoten ausführt (If-Zweig und Else-Zweig)
38 * der Switch ein Knoten, welcher einen Wert gegen den Wert der Kinderknoten (Default-Case und Switch-Case) vergleicht und dann alle Kinderknoten ausführt, die einen passenden Wert haben
39 * das Experiment (Try-Catch) ein Knoten, welcher versucht, den ersten Kinderknoten (Try-Block) auszuführen. Schlägt dies mit einer unbehandelten Ausnahme fehl, wird der zweite Kinderknoten (Catch-Block) ausgeführt.
40 * die Aktion ein Knoten, der keine Kinderknoten hat und lediglich in Java definierte Logik ausführt
41
42 Mit diesem Interface können somit nicht nur Aktionen, sondern auch andere Knoten implementiert werden, die den Kontrollfluss beeinflussen.
43
44 === Methodensignaturen ===
45
46 Die vollständige Dokumentation findet sich {{javadoc package="de.xima.fc.plugin.interfaces.workflow" name="IPluginWorkflowNode"}} in der JavaDoc zu diesem Interface{{/javadoc}}. Im Folgenden einige der wichtigsten Methoden:
47
48 {{panel title="{{code language='java'~}~}public INodeHandler<?> getNodeHandler(){{/code~}~}" triggerable="false" initial="visible" fullwidth="true" styleClass="xm-code-panel"}}
49 Diese Methode muss die Implementierung von {{javadoc package="de.xima.fc.interfaces.workflow.nodes" name="INodeHandler"}}INodeHandler{{/javadoc}} zurückliefern, welche durch das Plugin bekannt gemacht werden soll. //INodeHandler// enthält alle Methoden, um die Workflow-Node konfigurieren zu können.
50 {{/panel}}
51
52 == Schnittstelle IPluginActionNodeHandler / APluginActionNodeHandler ==
53
54 {{figure image="plugin_demo-workflow-element.png"}}
55 Das Ergebnis des Demo-Workflow-Element-Plugins. Zeigt die im Workflow-Designer eingebundene Aktion.
56 {{/figure}}
57
58 Dieses Schnittstelle enthält viele Default-Implementierungen für reine abarbeitende Aktionen, die den Kontrollfluss nicht beeinflussen und lediglich in Java implementierte Logik ausführen. Es ist damit einfach möglich, eigene Workflow-Aktionen in das bestehende System hinzuzufügen.
59
60 Wir empfehlen, die abstrakte Klasse //APluginActionNodeHandler// zu verwenden. Falls das Plugin eine andere Superklasse haben soll, kann stattdessen das Mixin-Interface //IPluginActionNodeHandler// genutzt werden.
61
62 Eine Implementierung einer Workflow-Aktion besteht dabei üblicherweise aus mehreren Komponenten:
63
64 * Implementierung einer Modelklasse zur Datenhaltung der Eigenschaften einer Workflow-Aktion (diese Klasse muss von //BaseActionProps// erben)
65 * eine Enum-Implementierung zur Definition möglicher Fehlercodes, welche durch die Workflow-Aktion zurück geliefert werden können.
66 * Implementierung der //IPluginActionNodeHandler// Schnittstelle unter Einbeziehung der definierten Modelklasse
67 * eine XHTML-Seite zur Konfiguration und Anzeige der Eigenschaften der Workflow-Aktion
68 * optional eine Managed-Bean-Implementierung (basierend auf der Schnittstelle //INodePropertyPluginBean//), um die XHTML-Seite (View) mit den Daten und der Geschäftslogik zu verknüpfen. Diese ist optional und nur erforderlich, wenn die XHTML-Seite spezielle Logik enthalten soll, wie etwa ein Button zum Prüfen Testen eines Webservices.
69
70 === Methodensignaturen ===
71
72 Die vollständige Dokumentation findet sich {{javadoc package="de.xima.fc.workflow.mixin" name="IPluginActionNodeHandler"}} in der JavaDoc zu diesem Interface{{/javadoc}}. Im Folgenden einige der wichtigsten Methoden:
73
74 Erforderlich sind neben //getName// noch folgende zwei Methoden:
75
76 {{panel title="{{code language='java'~}~}public INormalCompletionResult execute(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException{{/code~}~}" fullwidth="true" initial="hidden" triggerable="true" styleClass="xm-code-panel"}}
77 Hier erfolgt die Implementierung der Business-Logik des Plugins. Über //params.getWorkflowContext()// kann auf die Modelklasse mit der Konfiguration zugegriffen werden. Über //params.getWorkflowContext()// stehen viele Hilfsmethoden bereit, die verwendet werden sollten, anstellte Funktionen selber zu implementieren. Beispielsweise kann via //params.getWorkflowContext().http().requestResponseRedirect(URI)// eine Weiterleitung nach Ausführung des Workflows angestoßen werden.
78 Alle Werte, welche die Aktion im Erfolgsfall zurück geben soll, müssen dem Datentyp entsprechen, welcher durch die Methode getSuccessValueDescriptor(IValueDescriptorFactory) definiert wird. Wenn diese Methode nicht implementiert ist, wird durch die Aktion kein Wert zurück gegeben.
79 {{/panel}}
80
81 {{panel title="{{code language='java'~}~}public String getPropertiesViewXhtmlName(){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
82 Liefert den Namen (ohne Pfad-Angabe) zur XHTML-Seite, welche zur Konfiguration und Anzeige der Eigenschaften der Workflow-Aktion dient. Die XHTML-Seite muss in der Plugin-JAR im Ordner //WEB-INF/ui// liegen. Soll ein anderer Ordner genutzt werden, muss //getPropertiesViewXhtmlPath// überschrieben werden.
83 Eine Implementierung ist erforderlich.
84 {{/panel}}
85
86 Wird das Mixin-Interface //IPluginActionNodeHandler// verwendet, muss noch //getPluginInitializeData// implementiert werden, welche nur den Wert zurückgibt, der in der //initialize//-Methode übergeben wurde.
87
88 Alle weiteren Methoden können optional bei Bedarf überschrieben werden. Auszugsweise hier einige Methoden:
89
90 {{panel title="{{code language='java'~}~}public IElementCategory getMainCategory(IGetElementPrototypesParams params){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
91 Definiert die Haupt-Kategorie, in der die Workflow-Aktion innerhalb des Workflow-Designers zur Auswahl angezeigt wird (links-seitige Auswahl).
92 Die Implementierung dieser Methode ist optional. Erfolgt keine Implementierung, so wird die Workflow-Aktion standardmäßig unter der Rubrik "Aktionen" eingeordnet.
93 {{/panel}}
94
95 {{panel title="{{code language='java'~}~}public IElementCategory getSubCategory(IGetElementPrototypesParams params){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
96 Definiert die Unter-Kategorie, in der die Workflow-Aktion innerhalb des Workflow-Designers zur Auswahl angezeigt wird (links-seitige Auswahl).
97 Die Implementierung dieser Methode ist optional. Erfolgt keine Implementierung, so wird die Workflow-Aktion standardmäßig unter der Rubrik "Allgemein" eingeordnet.
98 {{/panel}}
99
100 {{panel title="{{code language='java'~}~}public IValueDescriptor<?, ? extends IValueBuilder<?>> getSuccessValueDescriptor(IValueDescriptorFactory factory){{/code~}~}" fullwidth="true" triggerable="true" initial="hidden" styleClass="xm-code-panel"}}
101 Wenn Sie Werte in der Workflow-Aktion zurückgeben (und über Variablen/Platzhalter für andere Aktionen verfügbar machen möchten), muss diese Methode implementiert werden. Weiterhin muss sichergestellt werden, dass in der Methode {{code language='java'}}execute(INodeExecutionParams){{/code}} bei der Ausführung die entsprechenden Werte in der definierten Rückgabestruktur gesetzt werden. Falls die execute-Methode Werte zurückliefert, welche nicht in dieser Methode definiert sind, werden diese Werte ignoriert.
102 Die Implementierung dieser Methode ist optional, wenn die Workflow-Aktion keine Werte zurück geben soll.
103 {{/panel}}
104
105 {{panel title="{{code language='java'~}~}public IUnionValueDescriptor<String> getErrorValueDescriptor(IValueDescriptorFactory factory){{/code~}~}" fullwidth="true" initial="hidden" triggerable="true" styleClass="xm-code-panel"}}
106 Diese Methode definiert dabei alle möglichen Ausprägungen von Fehlercodes, die in der Workflow-Aktion auftreten können. Jeder Fehlercode kann dabei unterschiedliche zusätzliche Informationen zurück liefern. Welche dies genau sind, ist am jeweiligen Fehlercodes zu definieren.
107
108 Wenn in der ~{~{code~}~}execute~{~{/code~}~} eine nicht behandelter Fehler auftritt, so wird standardmäßig der allgemeine Fehlercode ~{~{code~}~}ERROR_CODE_GENERAL~{~{/code~}~} zurück geliefert.
109
110 Diese Methode ist zu implementieren, wenn die Aktion benutzerdefinierte Fehlercodes zurück geben soll und diese über zusätzliche Informationen verfügen müssen. Wenn "nur" eine Unterscheidung nach Fehlercodes genügt, so muss nur die Methode ~{~{code~}~}getErrorCodeClass~{~{\code~}~} implementiert werden und auf die entsprechende Enum-Klasse mit den Fehlercodes verweisen.
111 {{/panel}}
112
113 {{panel title="{{code language='java'~}~}public Class<? extends Enum<?>> getErrorCodeClass(){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
114 Gibt den Typ der Enumeration zurück, welcher die Fehlertypen definiert, die während der Ausführung der Workflow-Aktion auftreten können.
115 Wenn diese Methode nicht implementiert ist, existieren keinen benutzerdefinierten Fehler in der Aktion.
116 Im Fall einer Ausnahme innerhalb der Aktions-Verarbeitung wird diese dann als allgemeine Ausnahme behandelt und der Fehlercode ~{~{code~}~}ERROR_CODE_GENERAL~{~{/code~}~} zurück geliefert.
117 {{/panel}}
118
119 {{panel title="{{code language='java'~}~}public IFileValueDescriptor getFileValueDescriptor(){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
120 Diese Methode ist zu implementieren, wenn die Workflow-Aktion Dateien zurückgeben kann.
121 Diese Workflow-Aktion kann dann von anderen Aktionen ausgewählt werden, die Dateien erfordern.
122 Wenn die Workflow-Aktion keine Dateien bereitstellt, ist die Methode zu entfernen.
123 {{/panel}}
124
125 {{panel title="{{code language='java'~}~}public Class<? extends INodePropertyPluginBean<TData>> getMainPluginBeanClass(){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
126 Liefert die Bean-Klasse zurück, welche im Zusammenspiel mit der XHTML-Seite genutzt werden soll. Die Implementierung dieser Methode ist optional. Der XHTML-Seite wird immer die Variable //model// zur Verfügung gestellt, welche auf die Modelklasse verweist.
127 {{/panel}}
128
129 == Schnittstelle IPluginConditionNodeHandler / APluginConditionNodeHandler ==
130
131 {{version major="7" minor="1" patch="0" /}}
132
133 Diese Schnittstelle enthält Default-Implementierung für reine If-Else-Bedingungen. Damit ist es einfacher möglich, eine If-Else-Bedingung zu implementieren, welche eine Bedingung prüft und je nach Resultat den If-Zweig oder den Else-Zweig ausführt.
134
135 Wir empfehlen, die abstrakte Klasse //APluginConditionNodeHandler// zu verwenden. Falls das Plugin eine andere Superklasse haben soll, kann stattdessen das Mixin-Interface //IPluginConditionNodeHandler// genutzt werden.
136
137 === Methodensignaturen ===
138
139 Die vollständige Dokumentation findet sich {{javadoc package="de.xima.fc.workflow.mixin" name="IPluginConditionNodeHandler"}} in der JavaDoc zu diesem Interface{{/javadoc}}. Im Folgenden einige der wichtigsten Methoden:
140
141 Erforderlich sind neben //getName// noch folgende zwei Methoden:
142
143 {{panel title="{{code language='java'~}~}public boolean evaluateCondition(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException{{/code~}~}" fullwidth="true" initial="hidden" triggerable="true" styleClass="xm-code-panel"}}
144 Hier erfolgt die Implementierung der Business-Logik der Bedingung. Diese Methode muss zurückliefern, ob die Bedingung erfüllt ist. Über //params.getWorkflowContext()// kann auf die Modelklasse mit der Konfiguration zugegriffen werden. Über //params.getWorkflowContext()// stehen viele Hilfsmethoden bereit, die verwendet werden sollten, anstellte Funktionen selber zu implementieren.
145 {{/panel}}
146
147 {{panel title="{{code language='java'~}~}public String getPropertiesViewXhtmlName(){{/code~}~}" triggerable="true" initial="hidden" fullwidth="true" styleClass="xm-code-panel"}}
148 Liefert den Namen (ohne Pfad-Angabe) zur XHTML-Seite, welche zur Konfiguration und Anzeige der Eigenschaften der Workflow-Aktion dient. Die XHTML-Seite muss in der Plugin-JAR im Ordner //WEB-INF/ui// liegen. Soll ein anderer Ordner genutzt werden, muss //getPropertiesViewXhtmlPath// überschrieben werden.
149 {{/panel}}
150
151 Wird das Mixin-Interface //IPluginConditionNodeHandler// verwendet, muss noch //getPluginInitializeData// implementiert werden, welche nur den Wert zurückgibt, der in der //initialize//-Methode übergeben wurde.
152
153 Alle weiteren Methoden sind wie bei Aktion optional.