doc/html/ch04.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   3    <title>Kapitel 4. Entwicklerdokumentation</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1-RC2"><link rel="home" href="index.html" title="Lx-Office: Installation, Konfiguration, Entwicklung"><link rel="up" href="index.html" title="Lx-Office: Installation, Konfiguration, Entwicklung"><link rel="prev" href="ch03s03.html" title="3.3. Excel-Vorlagen"><link rel="next" href="ch04s02.html" title="4.2. Entwicklung unter FastCGI"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Kapitel 4. Entwicklerdokumentation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch03s03.html">Zurück</a>&nbsp;</td><th width="60%" align="center">&nbsp;</th><td width="20%" align="right">&nbsp;<a accesskey="n" href="ch04s02.html">Weiter</a></td></tr></table><hr></div><div class="chapter" title="Kapitel 4. Entwicklerdokumentation"><div class="titlepage"><div><div><h2 class="title"><a name="d0e4243"></a>Kapitel 4. Entwicklerdokumentation</h2></div></div></div><div class="sect1" title="4.1. Globale Variablen"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="devel.globals"></a>4.1. Globale Variablen</h2></div></div></div><div class="sect2" title="4.1.1. Wie sehen globale Variablen in Perl aus?"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4249"></a>4.1.1. Wie sehen globale Variablen in Perl aus?</h3></div></div></div><p>Globale Variablen liegen in einem speziellen namespace namens
   4         "main", der von überall erreichbar ist. Darüber hinaus sind bareword
   5         globs global und die meisten speziellen Variablen sind...
   6         speziell.</p><p>Daraus ergeben sich folgende Formen:</p><div class="variablelist"><dl><dt><span class="term">
   7                      <code class="literal">$main::form</code>
   8                   </span></dt><dd><p>expliziter Namespace "main"</p></dd><dt><span class="term">
   9                      <code class="literal">$::form</code>
  10                   </span></dt><dd><p>impliziter Namespace "main"</p></dd><dt><span class="term">
  11                      <code class="literal">open FILE, "file.txt"</code>
  12                   </span></dt><dd><p>
  13                         <code class="varname">FILE</code> ist global</p></dd><dt><span class="term">
  14                      <code class="literal">$_</code>
  15                   </span></dt><dd><p>speziell</p></dd></dl></div><p>Im Gegensatz zu <span class="productname">PHP</span>&#8482; gibt es kein
  16         Schlüsselwort wie "<code class="function">global</code>", mit dem man
  17         importieren kann. <code class="function">my</code>, <code class="function">our</code>
  18         und <code class="function">local</code> machen was anderes.</p><div class="variablelist"><dl><dt><span class="term">
  19                      <code class="literal">my $form</code>
  20                   </span></dt><dd><p>lexikalische Variable, gültig bis zum Ende des
  21               Scopes</p></dd><dt><span class="term">
  22                      <code class="literal">our $form</code>
  23                   </span></dt><dd><p>
  24                         <code class="varname">$form</code> referenziert ab hier
  25               <code class="varname">$PACKAGE::form</code>.</p></dd><dt><span class="term">
  26                      <code class="literal">local $form</code>
  27                   </span></dt><dd><p>Alle Änderungen an <code class="varname">$form</code> werden am Ende
  28               des scopes zurückgesetzt</p></dd></dl></div></div><div class="sect2" title="4.1.2. Warum sind globale Variablen ein Problem?"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4350"></a>4.1.2. Warum sind globale Variablen ein Problem?</h3></div></div></div><p>Das erste Problem ist <span class="productname">FCGI</span>&#8482;.</p><p>
  29                <span class="productname">SQL-Ledger</span>&#8482; hat fast alles im globalen
  30         namespace abgelegt, und erwartet, dass es da auch wiederzufinden ist.
  31         Unter <span class="productname">FCGI</span>&#8482; müssen diese Sachen aber wieder
  32         aufgeräumt werden, damit sie nicht in den nächsten Request kommen.
  33         Einige Sachen wiederum sollen nicht gelöscht werden, wie zum Beispiel
  34         Datenbankverbindungen, weil die sehr lange zum Initialisieren
  35         brauchen.</p><p>Das zweite Problem ist <code class="function">strict</code>. Unter
  36         <code class="function">strict</code> werden alle Variablen die nicht explizit
  37         mit <code class="function">Package</code>, <code class="function">my</code> oder
  38         <code class="function">our</code> angegeben werden als Tippfehler angemarkert,
  39         dies hat, seit der Einführung, u.a. schon so manche langwierige Bug-Suche verkürzt.
  40         Da globale Variablen aber implizit mit Package angegeben werden, werden
  41         die nicht geprüft, und somit kann sich schnell ein Tippfehler einschleichen.</p></div><div class="sect2" title="4.1.3. Kanonische globale Variablen"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4383"></a>4.1.3. Kanonische globale Variablen</h3></div></div></div><p>Um dieses Problem im Griff zu halten gibt es einige wenige
  42         globale Variablen, die kanonisch sind, d.h. sie haben bestimmte vorgegebenen Eigenschaften,
  43         und alles andere sollte anderweitig umhergereicht werden.</p><p>Diese Variablen sind im Moment die folgenden neun:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
  44                      <code class="varname">$::form</code>
  45                   </p></li><li class="listitem"><p>
  46                      <code class="varname">%::myconfig</code>
  47                   </p></li><li class="listitem"><p>
  48                      <code class="varname">$::locale</code>
  49                   </p></li><li class="listitem"><p>
  50                      <code class="varname">$::lxdebug</code>
  51                   </p></li><li class="listitem"><p>
  52                      <code class="varname">$::auth</code>
  53                   </p></li><li class="listitem"><p>
  54                      <code class="varname">$::lx_office_conf</code>
  55                   </p></li><li class="listitem"><p>
  56                      <code class="varname">$::instance_conf</code>
  57                   </p></li><li class="listitem"><p>
  58                      <code class="varname">$::dispatcher</code>
  59                   </p></li><li class="listitem"><p>
  60                      <code class="varname">$::request</code>
  61                   </p></li></ul></div><p>Damit diese nicht erneut als Müllhalde missbraucht werden, im Folgenden
  62         eine kurze Erläuterung der bestimmten vorgegebenen Eigenschaften (Konventionen):</p><div class="sect3" title="4.1.3.1. $::form"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4447"></a>4.1.3.1. $::form</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Ist ein Objekt der Klasse
  63               "<code class="classname">Form</code>"</p></li><li class="listitem"><p>Wird nach jedem Request gelöscht</p></li><li class="listitem"><p>Muss auch in Tests und Konsolenscripts vorhanden
  64               sein.</p></li><li class="listitem"><p>Enthält am Anfang eines Requests die Requestparameter vom
  65               User</p></li><li class="listitem"><p>Kann zwar intern über Requestgrenzen ein Datenbankhandle
  66               cachen, das wird aber momentan absichtlich zerstört</p></li></ul></div><p>
  67                   <code class="varname">$::form</code> wurde unter <span class="productname">SQL
  68           Ledger</span>&#8482; als Gottobjekt für alles misbraucht. Sämtliche
  69           alten Funktionen unter SL/ mutieren <code class="varname">$::form</code>, das
  70           heißt, alles was einem lieb ist (alle Variablen die einem ans Herz
  71           gewachsen sind), sollte man vor einem Aufruf (!) von zum
  72           Beispiel <code class="function">IS-&gt;retrieve_customer()</code> in
  73           Sicherheit bringen. </p>
  74           Z.B. das vom Benutzer eingestellte Zahlenformat, bevor man Berechnung in einem
  75           bestimmten Format durchführt (SL/Form.pm Zeile 3552, Stand version 2.7beta), um
  76           dies hinterher wieder auf den richtigen Wert zu setzen:
  77           <pre class="programlisting">
  78             my $saved_numberformat    = $::myconfig{numberformat};
  79             $::myconfig{numberformat} = $numberformat;
  80             # (...) div Berechnungen
  81             $::myconfig{numberformat} = $saved_numberformat;
  82           </pre><p>Das Objekt der Klasse Form hat leider im Moment noch viele
  83           zentrale Funktionen die vom internen Zustand abhängen, deshalb
  84           bitte nie einfach zerstören oder überschreiben (zumindestens nicht kurz
  85           vor einem Release oder in Absprache über bspw. die devel-Liste ;-).
  86           Es geht ziemlich sicher etwas kaputt.</p><p>
  87                   <code class="varname">$::form</code> ist gleichzeitig der Standard Scope
  88           in den <span class="productname">Template::Toolkit</span>&#8482; Templates
  89           außerhalb der Controller: der Ausdruck <code class="function">[% var
  90           %]</code> greift auf <code class="varname">$::form-&gt;{var}</code> zu.
  91           Unter Controllern ist der Standard Scope anders, da lautet der
  92           Zugriff <code class="function">[% FORM.var %]</code>. In Druckvorlagen sind
  93           normale Variablen ebenfall im <code class="varname">$::form</code> Scope, d.h.
  94           <code class="function">&lt;%var%&gt;</code> zeigt auf
  95           <code class="varname">$::form-&gt;{var}</code>.
  96           Nochmal von der anderen Seite erläutert, innerhalb von (Web-)Templates sieht
  97           man häufiger solche Konstrukte:
  98           </p><pre class="programlisting">
  99             [%- IF business %]
 100             # (... Zeig die Auswahlliste Kunden-/Lieferantentyp an
 101             [%- END %]
 102          </pre><p>
 103         Entweder wird hier dann $::form-&gt;{business} ausgewertet oder aber der Funktion
 104         <code class="function">$form-&gt;parse_html_template</code> wird explizit noch ein zusätzlicher Hash
 105         übergeben, der dann auch in den (Web-)Templates zu Verfügung steht, bspw. so:
 106           <code class="function">$form-&gt;parse_html_template("is/form_header", \%TMPL_VAR);</code>
 107
 108           Innerhalb von Schleifen wird
 109           <code class="varname">$::form-&gt;{TEMPLATE_ARRAYS}{var}[$index]</code>
 110           bevorzugt, wenn vorhanden.</p>
 111           Zum Beispiel in SL/DO.pm welche über alle Positionen eines Lieferscheins
 112           in Schleife läuft:
 113           <pre class="programlisting">
 114             for $i (1 .. $form-&gt;{rowcount}) {
 115               (...)
 116               push @{ $form-&gt;{TEMPLATE_ARRAYS}{runningnumber} },   $position;
 117               push @{ $form-&gt;{TEMPLATE_ARRAYS}{number} },          $form-&gt;{"partnumber_$i"};
 118               push @{ $form-&gt;{TEMPLATE_ARRAYS}{description} },     $form-&gt;{"description_$i"};
 119          </pre></div><div class="sect3" title="4.1.3.2. %::myconfig"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4529"></a>4.1.3.2. %::myconfig</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Das einzige Hash unter den globalen Variablen</p></li><li class="listitem"><p>Wird spätestens benötigt wenn auf die Datenbank
 120               zugegriffen wird</p></li><li class="listitem"><p>Wird bei jedem Request neu erstellt.</p></li><li class="listitem"><p>Enthält die Userdaten des aktuellen Logins</p></li><li class="listitem"><p>Sollte nicht ohne Filterung irgendwo gedumpt werden oder
 121               extern serialisiert werden, weil da auch der Datenbankzugriff
 122               für diesen user drinsteht.</p></li><li class="listitem"><p>Enthält unter anderem Listenbegrenzung vclimit,
 123               Datumsformat dateformat und Nummernformat numberformat</p></li><li class="listitem"><p>Enthält Datenbankzugriffinformationen</p></li></ul></div><p>
 124                   <code class="varname">%::myconfig</code> ist im Moment der Ersatz für
 125           ein Userobjekt. Die meisten Funktionen, die etwas anhand des
 126           aktuellen Users entscheiden müssen, befragen
 127           <code class="varname">%::myconfig</code>.
 128           Innerhalb der Anwendungen sind dies überwiegend die Daten, die sich
 129           unter Programm-&gt;Einstellungen befinden, bzw. die Informationen über den
 130           Benutzer die über die Administrator-Schnittstelle (admin.pl) eingegeben wurden.
 131         </p></div><div class="sect3" title="4.1.3.3. $::locale"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4562"></a>4.1.3.3. $::locale</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse "Locale"</p></li><li class="listitem"><p>Wird pro Request erstellt</p></li><li class="listitem"><p>Muss auch für Tests und Scripte immer verfügbar
 132               sein.</p></li><li class="listitem"><p>Cached intern über Requestgrenzen hinweg benutzte
 133               Locales</p></li></ul></div><p>Lokalisierung für den aktuellen User. Alle Übersetzungen,
 134           Zahlen- und Datumsformatierungen laufen über dieses Objekt.</p></div><div class="sect3" title="4.1.3.4. $::lxdebug"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4580"></a>4.1.3.4. $::lxdebug</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse "LXDebug"</p></li><li class="listitem"><p>Wird global gecached</p></li><li class="listitem"><p>Muss immer verfügbar sein, in nahezu allen
 135               Funktionen</p></li></ul></div><p>
 136                   <code class="varname">$::lxdebug</code> stellt Debuggingfunktionen
 137           bereit, wie "<code class="function">enter_sub</code>" und
 138           "<code class="function">leave_sub</code>", mit denen in den alten Modulen ein
 139           brauchbares Tracing gebaut ist, "<code class="function">log_time</code>", mit
 140           der man die Wallclockzeit seit Requeststart loggen kann, sowie
 141           "<code class="function">message</code>" und "<code class="function">dump</code>" mit
 142           denen man flott Informationen ins Log (tmp/lx-office-debug.log) packen kann.</p>
 143           Beispielsweise so:
 144           <pre class="programlisting">
 145             $main::lxdebug-&gt;message(0, 'Meine Konfig:' . Dumper (%::myconfig));
 146             $main::lxdebug-&gt;message(0, 'Wer bin ich? Kunde oder Lieferant:' . $form-&gt;{vc});
 147
 148           </pre></div><div class="sect3" title="4.1.3.5. $::auth"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4616"></a>4.1.3.5. $::auth</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse "SL::Auth"</p></li><li class="listitem"><p>Wird global gecached</p></li><li class="listitem"><p>Hat eine permanente DB Verbindung zur Authdatenbank</p></li><li class="listitem"><p>Wird nach jedem Request resettet.</p></li></ul></div><p>
 149                   <code class="varname">$::auth</code> stellt Funktionen bereit um die
 150           Rechte des aktuellen Users abzufragen. Obwohl diese Informationen
 151           vom aktuellen User abhängen wird das Objekt aus
 152           Geschwindigkeitsgründen nur einmal angelegt und dann nach jedem
 153           Request kurz resettet.</p></div><div class="sect3" title="4.1.3.6. $::lx_office_conf"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4637"></a>4.1.3.6. $::lx_office_conf</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse
 154               "<code class="classname">SL::LxOfficeConf</code>"</p></li><li class="listitem"><p>Global gecached</p></li><li class="listitem"><p>Repräsentation der
 155               <code class="filename">config/lx_office.conf[.default]</code>-Dateien</p></li></ul></div><p>Globale Konfiguration. Configdateien werden zum Start gelesen
 156           und danach nicht mehr angefasst. Es ist derzeit nicht geplant, dass das
 157           Programm die Konfiguration ändern kann oder sollte.</p><p>Beispielsweise ist über den Konfigurationseintrag [debug]
 158                 die Debug- und Trace-Log-Datei wie folgt konfiguriert und verfügbar:</p><pre class="programlisting">[debug]
 159 file = /tmp/lx-office-debug.log</pre><p>ist der Key <code class="varname">file</code> im Programm als
 160           <code class="varname">$::lx_office_conf-&gt;{debug}{file}</code>
 161           erreichbar.</p><div class="warning" title="Warnung" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warnung]" src="../../../../system/docbook-xsl/images/warning.png"></td><th align="left">Warnung</th></tr><tr><td align="left" valign="top"><p>Zugriff auf die Konfiguration erfolgt im Moment über
 162             Hashkeys, sind also nicht gegen Tippfehler abgesichert.</p></td></tr></table></div></div><div class="sect3" title="4.1.3.7. $::instance_conf"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4673"></a>4.1.3.7. $::instance_conf</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse
 163               "<code class="classname">SL::InstanceConfiguration</code>"</p></li><li class="listitem"><p>wird pro Request neu erstellt</p></li></ul></div><p>Funktioniert wie <code class="varname">$::lx_office_conf</code>,
 164           speichert aber Daten die von der Instanz abhängig sind. Eine Instanz
 165           ist hier eine Mandantendatenbank.
 166           Beispielsweise überprüft
 167           </p><pre class="programlisting">$::instance_conf-&gt;get_inventory_system eq 'perpetual'</pre><p>
 168           ob die berüchtigte Bestandsmethode zur Anwendung kommt.</p></div><div class="sect3" title="4.1.3.8. $::dispatcher"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4694"></a>4.1.3.8. $::dispatcher</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Objekt der Klasse
 169               "<code class="varname">SL::Dispatcher</code>"</p></li><li class="listitem"><p>wird pro Serverprozess erstellt.</p></li><li class="listitem"><p>enthält Informationen über die technische Verbindung zum
 170               Server</p></li></ul></div><p>Der dritte Punkt ist auch der einzige Grund warum das Objekt
 171           global gespeichert wird. Wird vermutlich irgendwann in einem anderen
 172           Objekt untergebracht.</p></div><div class="sect3" title="4.1.3.9. $::request"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4712"></a>4.1.3.9. $::request</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Hashref (evtl später Objekt)</p></li><li class="listitem"><p>Wird pro Request neu initialisiert.</p></li><li class="listitem"><p>Keine Unterstruktur garantiert.</p></li></ul></div><p>
 173                   <code class="varname">$::request</code> ist ein generischer Platz um
 174           Daten "für den aktuellen Request" abzulegen. Sollte nicht für action
 175           at a distance benutzt werden, sondern um lokales memoizing zu
 176           ermöglichen, das garantiert am Ende des Requests zerstört
 177           wird.</p><p>Vieles von dem, was im moment in <code class="varname">$::form</code>
 178           liegt, sollte eigentlich hier liegen. Die groben
 179           Differentialkriterien sind:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Kommt es vom User, und soll unverändert wieder an den User? Dann <code class="varname">$::form</code>, steht da eh schon</p></li><li class="listitem"><p>Sind es Daten aus der Datenbank, die nur bis zum Ende des Requests gebraucht werden? Dann
 180               <code class="varname">$::request</code>
 181                      </p></li><li class="listitem"><p>Muss ich von anderen Teilen des Programms lesend drauf zugreifen? Dann <code class="varname">$::request</code>, aber Zugriff über
 182               Wrappermethode</p></li></ul></div></div></div><div class="sect2" title="4.1.4. Ehemalige globale Variablen"><div class="titlepage"><div><div><h3 class="title"><a name="d0e4754"></a>4.1.4. Ehemalige globale Variablen</h3></div></div></div><p>Die folgenden Variablen waren einmal im Programm, und wurden
 183         entfernt.</p><div class="sect3" title="4.1.4.1. $::cgi"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4759"></a>4.1.4.1. $::cgi</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>war nötig, weil cookie Methoden nicht als
 184               Klassenfunktionen funktionieren</p></li><li class="listitem"><p>Aufruf als Klasse erzeugt Dummyobjekt was im
 185               Klassennamespace gehalten wird und über Requestgrenzen
 186               leaked</p></li><li class="listitem"><p>liegt jetzt unter
 187               <code class="varname">$::request-&gt;{cgi}</code>
 188                      </p></li></ul></div></div><div class="sect3" title="4.1.4.2. $::all_units"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4775"></a>4.1.4.2. $::all_units</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>war nötig, weil einige Funktionen in Schleifen zum Teil
 189               ein paar hundert mal pro Request eine Liste der Einheiten
 190               brauchen, und de als Parameter durch einen Riesenstack von
 191               Funktionen geschleift werden müssten.</p></li><li class="listitem"><p>Liegt jetzt unter
 192               <code class="varname">$::request-&gt;{cache}{all_units}</code>
 193                      </p></li><li class="listitem"><p>Wird nur in
 194               <code class="function">AM-&gt;retrieve_all_units()</code> gesetzt oder
 195               gelesen.</p></li></ul></div></div><div class="sect3" title="4.1.4.3. %::called_subs"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4794"></a>4.1.4.3. %::called_subs</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>wurde benutzt um callsub deep recursions
 196               abzufangen.</p></li><li class="listitem"><p>Wurde entfernt, weil callsub nur einen Bruchteil der
 197               möglichen Rekursioenen darstellt, und da nie welche
 198               auftreten.</p></li><li class="listitem"><p>komplette recursion protection wurde entfernt.</p></li></ul></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch03s03.html">Zurück</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch04s02.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">3.3. Excel-Vorlagen&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top">&nbsp;4.2. Entwicklung unter FastCGI</td></tr></table></div></body></html>