lacam/developer


Diese Seiten richten sich vor allem an den Entwickler, der die zugrunde liegende Platform durch Plugins erweitern will.

Ein Plugin beschreiben - die descriptor.xml

lacam wurde so programmiert, dass es einem Entwickler erlaubt, durch eigene Plugins die Fähigkeiten des Systems zu erweitern. Dazu muss jedoch jedes Plugin auf eine spezielle Weise für das System beschrieben werden, damit es problemlos mit anderen Plugins im System kooperieren kann. Eine solche Datei wird als Descriptor bezeichnet und beinhaltet alle für das System relevante Meta-Informationen über das Plugin. Ein Descriptor im XML-Format verfasst und folgt somit auch den Syntax-Regeln der XML-Sprache.

Die descriptor.xml verstehen

Ein Descriptor ist in drei Teilen aufgebaut, wobei immer mindestens einer von diesen vorhanden sein muss.

Den ersten Teil stellt der library-Tag dar, der die Klassen beschreibt, die im Plugin vorhanden sind.
Der zweite Teil ist der run-Tag, der den Aufruf enthält, der bei der Initialisierung des Plugins getätigt werden muss.
Der dritte Teil besteht aus eine Reihe von task-Tags, die mögliche mit dem Plugin kommende Tasks definieren.

Wir werden uns hier vor allem dem ersten und dem zweiten Teil widmen, da hier alle relevanten Informationen über das Plugin enthälten sind.

zurück

Ein Beispiel

Als Referenz für die folgenden Beschreibungen verwenden wir als ein Beispiel einen das System fast voll ausnutzenden Descriptor.:


01	<!DOCTYPE descriptor SYSTEM "descriptor.dtd">
02	<descriptor>
03	  <library>
04	    <class path="lacam/exapmle/Example.class" name="lacam.example.Exampe" version="someCRC" type="datasource">
05	      <author>some author</author>
06	      <description>
07	          DE?"Eine Beschreibung auf Deutsch";
08	          "A description in english"
09	      </description>
10	      <default_parameterlist>
11	        <parameter type="String" name="plugin.languagepack">DE?${plugin_name}/language/german.lp</parameter>
12	      </default_parameterlist>
13	      <implied_parameterlist>
14	        <parameter type="String" name="optional.param">
15	          DE?"Eine Beschreibung auf Deutsch";
16	          "A description in english";
17	        </parameter>
18	      </implied_parameterlist>
19	      <required_parameterlist>
20	        <parameter type="String" name="required.param">
21	          DE?"Eine Beschreibung auf Deutsch";
22	          "A description in english";
23	        </parameter>
24	      </required_parameterlist>
25	    </class>
26	  </library>
27	  <run>
28	    <class name="taskbuilder.actions.InitWizard" version="tskbuilder_0.01" path="" type="ignorable"/>
29	    <method name="initiAtStart"/>
30	    <parameterlist>
31	      <!-- version -->
32	      <parameter type="String" name="some_param">some_value</parameter>
33	    </parameterlist>
34	  </run>
35	  <task name="example task">
36	    <author>some author</author>
37	    <description>
38	      "some description"
39	    </description>
40	    <datasource>
41	      <class path="" name="lacam.conjointdata.datasources.NewConjointDesignDialog" version="conjointdata_0.1_newds" type="datasource"/>
42	    </datasource>
43	    <datasource>
44	      <class path="" name="lacam.processes.DefaultDatasource" version="1" type="datasource"/>
45	      <parameterlist>
46	        <invoke name="test">
47	          <class path="" name="lacam.utils.Toolkit" version="" type="native"/>
48	          <method name="print"/>
49	          <parameterlist>
50	            <parameter type="String">Starting Datasource process...</parameter>
51	          </parameterlist>
52	        </invoke>
53	        <parameter type="Integer">10</parameter>
54	      </parameterlist>
55	    </datasource>
56	    <preprocess>
57	      <class path="" name="lacam.conjointprocessing.ConjointPreprocess" version="conjointpp_0.1_cpp" type="preprocess"/>
58	    </preprocess>
59	    <modelmanager>
60	      <class path="" name="lacam.conjointmanagement.ConjointModelManager" version="conjointmm_0.1_cmm" type="modelmanager"/>
61	    </modelmanager>
62	    <userinterface>
63	      <class path="" name="lacam.conjointui.ui.FullBasicConjointUI" version="fbconjointui_0.1_cui" type="userinterface"/>
64	    <parameterlist>
65	      <parameter type="String">GERMAN?${plugin_name}/language/german.lp</parameter>
66	    </parameterlist>
67	    </userinterface>
68	    <analysis>
69	      <class path="" name="lacam.processes.DefaultAnalysis" version="5" type="analysis"/>
70	    </analysis>
71	    <postprocess>
72	      <class path="" name="lacam.processes.DefaultPostprocess" version="6" type="postprocess"/>
73	    </postprocess>
74	    <datatarget>
75	      <class path="" name="lacam.processes.DefaultDatatarget" version="7" type="datatarget"/>
76	    </datatarget>
77	    <datatarget>
78	      <class path="" name="lacam.processes.DefaultDatatarget" version="7" type="datatarget"/>
79	    </datatarget>
80	  </task>	
81	</descriptor>
zurück

Der library-Tag

Der library-Tag ist eine Aufzälung von class-Tags und beschreibt somit die relevanten Klassen des Plugins. Der library-Tag erlaubt keine Attribute.

zurück

Der run-Tag

Der run-Tag wird dazu verwendet, einen bestimmten Prozeduraufruf beim Systemstart auszuführen. Deswegen ist der Inhalt des run-Tags immer die Abfolge von genau einem class-Tag gefolgt von einem methode-Tag und abschließend einem parameterlist-Tag.
Im Beispiel wird in Zeile 27 des o.a. Descriptors die statische Methode 'initAtStart' der Klasse 'InitWizard' aufgerufen.

Achtung: Der run-Tag erlaubt nur Aufrufe statischer Methoden.

zurück

Der task-Tag

Der task-Tag beschreibt einen lacam-Task (s. lacam/tutorial). Der Inhalt dieses Tags muss sich strikt an die folgende Reihenfolge halten:

[<author>], [<description>], (<datasource>)+, <preprocessor>, <modelmanager>, <userinterface>, <analysis>, <postprocess>, (<datatarget>)+

wobei die in [ ] stehenden Tags optional sind und die in ( )+ stehenden Tags mindestens einmal vorkommen müssen. Die nicht in [ ] stehenden Tasks werden im Folgenden als 'Step'-Tags bezeichnet.
Das Beschreiben eines Tasks ist eine mühevolle Aufgabe, da in einem Task jeweils z.B. die Klassen richtig referenziert werden müssen. Aus diesem Grund stellt lacam das Plugin 'Taskbuilder' zur Verfügung, mit dem ein Task bearbeitet, erstellt oder aus einem Descriptor gelöscht werden kann. Diese Aufgaben werden jeweils in 'Einen lacam-Task erstellen, 'Bearbeiten eines Tasks' und in 'Löschen eines Tasks' beschrieben.
Auszufüllende Attribute
name Das Attribut beschreibt den Namen des Tasks. Hier sollte darauf geachtet werden, keine XML-Sonderzeichen zu benutzen.


zurück

Der class-Tag

Der class Tag definiert eine Klasse durch ihren Namen, ihre Version und ihren Typ und gibt den Pfad zu dieser Klasse an. Wie man an dem Beispiel erkennen kann, kommt der class-Tag in vielen Kontexten vor. Letzendlich wird er aber immer dazu verwendet, dem System möglichst genau mitzuteilen welche Klasse nun in diesem Kontext geladen und instanziiert werden soll.
So wird im Beispiel in der Zeile 04 des o.a. Descriptors der class-Tag dazu verwendet, ein Mapping zwischen den beschreibenden Attributen wie dem description- oder dem author-Tag und der Klasse herzustellen. In der Zeile 28 hingegen wird die Klasse angegeben, die beim Systemstart instanziiert werden soll und im Kontext des task-Tags wird auf die Klasse verwiesen, die den entsprechenden Arbeitsschritt erledigen soll.

Auszufüllende Attribute
path Das Attribut beschreibt den Pfad zu der Datei, die diese Klasse repräsentiert.
Der Pfad bezieht sich immer relativ auf das eigene Archiv.
Der Wert dieses Attributes kann bei Klassen des Typs native leer gelassen werden.
name Das Attribut beschreibt den kompletten Klassennahmen inklusive des Package der Klasse in dem bekannten JAVA Format.
Eine Klasse im Package muster mit dem Namen MusterClass hätte im Attribut name den Wert muster.MusterClass.
version Das Attribut beschreibt eine eindeutige Versionsnummer, die gleichzeitig von dem System als Identifizierung benutzt wird.
type Definiert den Typ der Klasse.
Laut DTD sind dafür die Typen datasource, preprocess, modelmanager, userinterface, analysis, postprocess, datatarget, native und ignorable zulässig.
Jeder Typ außer native und ignorable beschreibt einen Schritt im Workflow.
Das Attribut ignoreable sollte dann verwendet werden, wenn die Klasse Parameter über den Descriptor erhalten soll und auch so instanziiert werden muss.
Das Attribut native darf nur im Zusammenhang mit einer Klasse des JRE im Kontext eines run- oder invoke-Tags verwendet werden.
Optional kann einer Klasse im Kontext des library-Tags durch einen author-Tag ein Autor und durch einen description-Tag eine Beschreibung hinzugefügt werden. Der Inhalt des description-Tags muss der Syntax folgen, die in 'Internationalisierung' beschrieben wird.

zurück

Der method-Tag

Der method-Tag darf nur im Kontext eines invoke- oder eines run-Tags benutzt werden. Er benennt die statische Methode der im gleichen Kontext durch den class-Tag beschrieben Klasse.

Auszufüllende Attribute
name Der Name der Methode
zurück

Der parameterlist-Tag

Der parameterlist-Tag kapselt eine geordnete Aufzählung von parameter-Tags und stellt die Liste der Parameter, die je nach Kontext der init(Properties parametermap)-Methode, der Methode eines run-Tags oder eines invoke-Tags übergeben werden.

Achtung: Bei der Übergabe der Parameter an die Methode eines run-Tags oder eines invoke-Tags muss die Liste der Parameter unbedingt in ihrer Reihenfolge der Reihenfolge des Methodenheaders in der Java-Klasse entsprechen, da hier die java.lang.Reflection-Mechanismen benutzt werden. Im Kontext eines der 'Step'-Tags (s. 'Der task-Tag') ist jedoch die Reihenfolge der Parameter nicht von Relevanz, da dort die Parameter in einer Hashmap gespeichert übergeben werden.

zurück

Der default_parameterlist-Tag

Der default_parameterlist-Tag darf nur im Kontext des library-Tasks benutzt werden und beschreibt die Menge der Parameter, die auf jeden Fall der zugehörigen Klasse übergeben werden. Der parameter-Tag kapselt hier den Wert des Parameters und muss das in 'Internationalisierung' beschriebe Format haben. Im Beispiel wird in Zeile 10 des o.a. Descriptors das Language-Pack des Plugins als ein Standard-Parameter übergeben.

zurück

Der implied_parameterlist-Tag

Der implied_parameterlist-Tag darf nur im Kontext des library-Tasks benutzt werden und beschreibt die Menge der Parameter, die für die zugehörige Klasse optional sind. Der parameter-Tag kapselt hier die Beschreibung des Parameters und muss das in 'Internationalisierung' beschriebe Format haben. Siehe Zeile 13 im Beispiel.

zurück

Der required_parameterlist-Tag

Der required_parameterlist-Tag darf nur im Kontext des library-Tasks benutzt werden und beschreibt die Menge der Parameter, die für die zugehörige Klasse auf jeden Fall benötigt werden. Der parameter-Tag kapselt hier die Beschreibung des Parameters und muss das in 'Internationalisierung' beschriebene Format haben. Siehe Zeile 19 im Beispiel.

zurück

Der parameter-Tag

Der parameter-Tag beschreibt einen Parameter durch seinen Typ, Namen und je nach Kontext Wert oder Beschreibung.

Auszufüllende Attribute
name Der Name des Parameters, anhand dessen dieser in der Hashmap gefunden werden kann.
type Der Basistyp des Parameters. Hier sind erlaubt: Integer, Boolean, String, Float, Double, Character, Long, Short, Byte. Alle anderen Typen werden als String behandelt.
zurück

Der invoke-Tag

Der invoke-Tag folgt der gleichen Syntax wie der run-Tag und darf nur im Kontex von parameterlist-Tags verwendet werden. Er sollte dazu benutzt werden, dynamische (benutzerspezifische) Parameter zu erzeugen.

zurück

Der 'Step'-Tag

Der in 'Der task-Tag' erwähnte 'Step'-Tag beschreibt einen Schritt in einem lacam-Task. Er beinhaltet genau einenclass- und genau eine parameterlist -Tag.

zurück

Der author-Tag

Der author-Tag gibt den Autor einer Klasse oder eines Tasks an. Die Angaben sollten durch CDATA gekapselt werden, um Konflikte mit der XML-Syntax zu vermeiden.

zurück

Der description-Tag

Analog zum author-Tag gibt der description-Tag die Beschreibung zu einem Task oder zu einer Klasse an. Die Angaben sollten durch CDATA gekapselt werden, um Konflikte mit der XML-Syntax zu vermeiden. Der description-Tag erlaubt es, seinen Inhalt der Sprache des lacam-Systems anzupassen. Dazu sollte der Inhalt der im 'Internationalisierung' beschrieben Syntax entsprechen.

zurück

Internationalisierung

Syntax für die descriptor.xml

Bei der Programmierung von lacam wurde konsequent darauf geachtet, dass lacam nicht nur auf einem Rechner in einer Sprache funktioniert, sondern man durch einmaliges Schreiben eines Descriptors oder eines Tasks direkt das Land bzw. die Sprache berücksichtigen kann. Dazu verwendet lacam eine einfache Syntax, die überall in einem Descriptor benutzt werden kann, wo Internationalisierung Sinn macht. (Es gibt durchaus auch Tags, wie der author-Tag, wo Internationalisierung keinen Sinn macht).

Um einen Wert in der descriptor.xml zu internationalisieren, schreibt man die jeweiligen Werte im Format [<Sprache>?"<Wert>"]+ auf. Dabei sind für <Sprache> die ersten beiden Buchstaben einer Sprache als Großbuchstaben einzustzen. Z.B.: DE für Deutsch oder EN für Englisch. Weitere Sprachenformat können java.util.Locale entnommen werden. Wird einem in " " stehendem Wert nicht <Sprache>? vorangestellt wird dieser Wert als Standard-Wert betrachtet und dann genommen, wenn kein spezifischer Wert gefunden werden konnte.

Siehe z.B. Zeile 15 im obenstehenden Descriptor.

zurück