Karten in Application Express: Installation und Konfiguration von MapViewer und Oracle MAPS

Dieses Dokument gliedert sich in folgende Abschnitte:

Oracle MapViewer und Oracle MAPS: Was ist das?
Oracle MapViewer Software herunterladen und einrichten
Administrator-Password des MapViewer (OC4J) neu setzen
Bereitstellen von ausreichend Hauptspeicher für Oracle MapViewer
Empfohlene Vorbereitungen für Oracle MAPS
Einrichten der MapViewer Client Bibliothek in der Datenbank

1. Oracle MapViewer und Oracle MAPS: Was ist das?

Mit Oracle MapViewer und Oracle MAPS können Sie Karten auf Basis von Geodaten in der Oracle-Datenbank generieren und in Ihre Anwendungen einbauen. Während der Name Oracle MapViewer die Software bezeichnet, welche die eigentliche Karte erzeugt (Abbildung 1), stellt Oracle MAPS die Karte als moderne AJAX-Oberfläche bereit, wie man sie von Google MAPS her bereits kennt. Oracle MAPS ist kein separates Softwarepaket, vielmehr ist es im Oracle MapViewer enthalten.

Abbildung 1: Architektur des Oracle MapViewer

Abbildung 1 zeigt die "klassische" Nutzung der MapViewer Software: In einem Map Request wird unter genau festgelegt, wie die zu generierende Karte auszusehen hat:

Kartenausschnitt
Kartengröße
Titel
Hintergrundfarbe
Bildformat der Karte (JPG, PNG, ...)
Einzelne Bestandteile der Karte (Layer)
Zeichenstil für die einzelnen Bestandteile
...

Der Map Request wird im XML-Format an den Server übermittelt. Sie brauchen den XML-Code aber glücklicherweise nicht selbst zu schreiben; dies übernehmen Bibliotheken für Sie. Die Karte entsteht als Bild und wird als Map Reponse wieder an den Aufrufer zurückgeliefert.

Der Server benötigt zum Erstellen der Karte nun Informationen über die Art und Weise, wie die geometrischen Elemente dargestellt werden sollen. So muss man dem MapViewer mitteilen, dass er die Linienzüge, die in der Tabelle AUTOBAHNEN enthalten sind, bspw. als rot-gelbe Linie darstellen soll. Diese Definitionen werden ebenfalls in der Datenbank gespeichert und zwar in den Tabellen USER_SDO_MAPS, USER_SDO_THEMES und USER_SDO_STYLES). Wenn Sie die NAVTEQ-Demodaten aus dem Oracle Technet installieren, sind darin bereits Kartendefinitionen enthalten.

Mit dem MapBuilder-Werkzeug (Abbildung 2), welches als Datei mapbuilder.jar zusammen mit der MapViewer-Software ausgeliefert wird, kann aus Aussehen der Karten komplett selbst definiert werden. Die Styles definieren, wie etwas gezeichnet wird, die Themes legen fest, wo die Daten herkommen und welcher Style zur Darstellung verwendet wird. Die Base Maps bestehen schließlich aus mehreren übereinandergelegten Themes und bilden so eine vordefinierte Karte. Sie können sich mit dem MapBuilder auch die bereits vorhandenen Kartendefinitionen der NAVTEQ Demodaten (World Sample) ansehen und ggfs. verändern.

Abbildung 2: Kartendefinitionen mit dem Oracle Map Builder

Oracle MAPS berücksichtigt die Tatsache, dass in den meisten Fällen stets die gleiche Karte an den Endanwender ausgeliefert wird. Es ist also nicht nötig, die immer wieder angefragten Karten ständig neu zu erstellen. Aus diesem Grund werden in Oracle MAPS sog. Map Tile Layers (in älteren Versionen auch Map Caches genannt) eingerichtet (Abbildung 2).

Abbildung 2: Oracle MAPS: Map Tile Layers"

In einem Map Tile Layer ist das Aussehen der Karte und die möglichen Zoom Levels vorkonfiguriert. Der Kartenraum wird in Kacheln (Tiles) unterteilt und Oracle MAPS generiert alle Kacheln für alle Zoom Levels im voraus. Eine einmal generierte Kachel wird dann solange für alle Nutzer wiederverwendet, bis sie explizit aus dem Cache gelöscht wird. Es ist klar, dass die Performance damit massiv verbessert wird - diese Performance ist auch die Basis für die AJAX-Weboberfläche, auf der die Karte bspw. mit Drag & Drop verschoben werden kann. Der Endanwender bekommt eine Oberfläche, wie er sie von Diensten wie Google Maps her kennt, aber mit eigenen Daten aus der eigenen Infrastruktur.

2. Oracle MapViewer Software herunterladen und einrichten

Wie schon beschrieben, ist die MapViewer-Software als Java-(J2EE)-Applikation realisiert. Das bedeutet, dass er einen Java Application Server als Laufzeitumgebung benötigt - direkt in der Datenbank bzw. in Application Express kann der MapViewer nicht laufen. Als Laufzeitumgebung empfiehlt sich entweder der Oracle Weblogic Server oder der "klassische" Oracle Containers for J2EE (OC4J).

Die Lizensierung der MapViewer-Software erfolgt ebenfalls gemeinsam mit der Oracle Fusion Middleware. In den Oracle Weblogic-Lizenzen ist er ebenso enthalten wie in den früheren Application Server Java Edition Lizenzen.

Die MapViewer-Software muss nicht auf dem gleichen Rechner wie die Datenbank bzw. Application Express laufen. Die Kommunikation zwischen MapViewer und Application Express wird über das Netzwerk laufen, so dass Sie hier die freie Wahl haben.

Stellen Sie sicher, dass eine Java-Umgebung (JDK) in der Version 1.5 oder höher bereit steht. Sie ermitteln die Version, indem Sie in der "DOS-Box" (Windows) oder in einem Terminal (Unix/Linux) folgendes eingeben:
```
/home/oracle> java -version
java version "1.5.0_05"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_05-b05)
Java HotSpot(TM) Client VM (build 1.5.0_05-b05, mixed mode)
```
Laden Sie das MapViewer QuickStart Kit aus dem OTN herunter. Navigieren Sie - ausgehend von der OTN-Startseite - zu Database, dort zu Spatial - Location Services, von dort zu Software und schließlich zu Oracle Fusion Middleware MapViewer. Laden Sie das QuickStart Kit herunter - Sie erhalten ein ZIP-Archiv mit dem Namen mapviewer10133wls.zip.
Wenn Sie dieses Archiv auspacken, finden Sie darin unter anderem wiederum ein Archiv mv10133_qs.zip. Packen Sie dieses ebenfalls aus - Sie erhalten eine für den MapViewer fertig vorkonfigurierte Umgebung, welche Sie sofort starten können.
Tun Sie dies mit dem vorhandenen Skript start.sh bzw. der Batchdatei start.bat. Sie werden bei diesem ersten Start nach einem Administratorpasswort gefragt - dies können Sie frei vergeben. Anschließend fährt die Java-Umgebung hoch und initialisiert den MapViewer. Wenn dieser Vorgang abgeschlossen ist, stoppen Sie die Umgebung wieder (Ctrl-C) - denn nun muss der MapViewer für Ihre Datenbank eingerichtet werden (Wohlgemerkt: Der MapViewer läuft im Gegensatz zu Application Express außerhalb der Datenbank, benötigt also Informationen zum Datenbankzugriff).
Navigieren Sie dazu (ausgehend vom Verzeichnis, in welches Sie das QuickStart Kit ausgepackt haben) in das Verzeichnis mit der Datei mapViewerConfig.xml und editieren Sie diese. Im folgenden ist dies beispielhaft für Linux dargestellt:
```
../OC4J> ls
bin          j2ee       javavm  jlib  rdbms       soap  startup  webservices
diagnostics  javacache  jdbc    lib   Readme.txt  sqlj  uix

.../OC4J> cd j2ee
.../OC4J/j2ee> cd home
.../OC4J/j2ee/home> cd applications/
.../OC4J/j2ee/home/applications> cd mapviewer/
.../OC4J/j2ee/home/applications/mapviewer> cd web/
.../OC4J/j2ee/home/applications/mapviewer/web> cd WEB-INF/
.../OC4J/j2ee/home/applications/mapviewer/web/WEB-INF> cd conf/
.../OC4J/j2ee/home/applications/mapviewer/web/WEB-INF/conf> vi mapViewerConfig.xml
```
Bewegen Sie sich ans Ende der Datei. Dort werden sie einen Bereich map_data_source vorfinden. Ändern Sie diesen so um, dass er in etwa wie folgt aussieht. Verwenden Sie das Datenbankschema, in welchem sich die Geodaten befinden (es kann, aber muss nicht das Parsing Schema Ihrer Application Express-Anwendung sein). Achten Sie darauf, dass Ihre Definition nicht etwa mit  auskommentiert ist. Sie können auch mehrere Data Sources erstellen; erstellen Sie dann mehrere XML-Tags <map_data_source>. Den Namen der Data Source (hier: world) verwenden Sie später beim Arbeiten mit dem MapViewer oder Oracle MAPS. Typischerweise werden Sie dann bei jeder Anfrage an den Server eine Data Source angeben.
```
<map_data_source name="world"
                 jdbc_host="[Datenbank-Rechnername]"
                 jdbc_sid="[Oracle-SID]"
                 jdbc_port="[TCP/IP-Port des Oracle Listeners: normalerweise 1521]"
                 jdbc_user="[Datenbank-Username (Schema mit den Geodaten)]"
                 jdbc_password="![Datenbank-Passwort]"
                 jdbc_mode="thin"
                 number_of_mappers="3"
/>
```
Wenn der Datenbankzugriff nicht funktioniert, kann die MapViewer-Software keine Karten erzeugen; alle Angaben müssen hier also sehr exakt sein. Lassen Sie sich im Zweifelsfall von Ihrem Datenbankadministrator helfen. Das führende Ausrufezeichen beim Passwort ist wichtig - dadurch wird es beim ersten Start des MapViewers verschlüsselt. Wenn Sie fertig sind, speichern Sie die Datei ab.
Wechseln Sie nun zurück ins Verzeichnis, in dem Sie das ZIP-Archiv ausgepackt haben und starten Sie den MapViewer dann wieder mit dem Skript start.sh bzw. der Batchdatei start.cmd.
Testen Sie das Systen schließlich, in dem Sie mit einem Web Browser folgende URL aufrufen:
```
http://[Server-name]:8888/mapviewer
```
Das Ergebnis sollte dann in etwa wie folgt aussehen.

Abbildung 3: Willkommensseite des Oracle Application Server MapViewer

Der MapViewer steht nun zur Entgegennahme von Anfragen bereit. Wenn Sie auf das Symbol Admin oben rechts klicken und sich dann mit dem Benutzernamen oc4jadmin und dem bei ersten Starten eingegebenen Passwort anmelden, können Sie die konfigurierten Data Sources unter Data Sources links betrachten. Beachten Sie aber bitte, dass in der Web-Oberfläche vorgenommene Änderungen an den Data Sources nicht in die XML-Datei geschrieben werden, beim nächsten Start des MapViewers gehen sie also verloren - am besten ändern Sie die Datenquellen also stets in der XML-Datei mapViewerConfig.xml.

3. Administrator-Password des MapViewer (OC4J) neu setzen

Wenn Sie das bei der Installation gesetzte Administrator-Passwort nicht mehr wissen, navigieren Sie in das Verzeichnis, in welches Sie die MapViewer-Software ausgepackt haben und setzen Sie das Passwort wie folgt neu:

.../OC4J $ cd j2ee
.../OC4J/j2ee $ cd home
.../OC4J/j2ee/home $ cd config
.../OC4J/j2ee/home/config $ vi system-jazn-data.xml

Suchen Sie in der XML-Datei system-jazn-data.xml den Eintrag für oc4jadmin und tragen Sie das neue Passwort mit einem führenden Ausrufezeichen wie folgt unter credentials ein:

<user>
  <name>oc4jadmin</name>
  <display-name>OC4J Administrator</display-name>
  <guid>84E9EB00B5CC11DB9F58212C13902763</guid>
  <description>OC4J Administrator</description>
  <credentials>!mapviewer</credentials>
</user>

Speichern Sie die Datei und starten Sie den MapViewer neu.

4. Bereitstellen von ausreichend Hauptspeicher für Oracle MapViewer

Es ist wichtig, dass der MapViewer ausreichend Hauptspeicher zum Generieren der Karten allokieren kann. Der Standardwert von 64MB für den Java Heap Space, welches standardmäßig gilt, reicht in vielen Fällen nicht aus. Ändern Sie daher das Skript start.sh bzw. die Batchdatei start.cmd wie folgt, um (in diesem Beispiel) 512MB bereitzustellen.

#!/bin/sh
cd oc4j/j2ee/home; java -server -Xmx512M -Djava.awt.headless=true -jar oc4j.jar

5. Empfohlene Vorbereitungen für Oracle MAPS

Wenn Sie den Apache Webserver und nicht das Oracle11g Embedded Gateway nutzen, ist es zu empfehlen, Application Express und den MapViewer so einzurichten, dass es nach außen aussieht, als ob MapViewer und Application Express auf dem gleichen Server laufen würden. Dadurch vereinfacht sich die weitere Arbeit mit Oracle MAPS - unbedingt erforderlich sind diese Vorbereitungsschritte jedoch nicht. Eine mögliche Situation sieht aktuell folgendermaßen aus.

Application Express: http://[host]:7780/pls/apex
Application Express: http://[host]:8888/mapviewer

Im ersten Schritt soll demnach sichergestellt werden, dass der MapViewer unter dem gleichen Hostnamen und dem gleichen TCP/IP-Port wie Application Express erreichbar ist.

Glücklicherweise ist dies ganz einfach: Mit dem Apache Modul mod_proxy können Sie genau dies erreichen. Zur Durchführung der folgenden Schritte benötigen Sie Zugriff auf den Server, auf welchem Application Express läuft - lassen Sie sich bei Bedarf von Ihrem Administrator helfen. Navigieren Sie auf dem Server in die Apache-Datei httpd.conf. Achten Sie darauf, dass die hier dargestellten Verzeichnisse in Ihrer Umgebung u.U. anders benannt sind. Insbesondere wenn Sie den Oracle HTTP-Server basierend auf Apache 2.0 nutzen, heißen die Verzeichnisse anders (bspw. "ohs" anstelle von "Apache").

/home/oracle $ cd $HTTP_SERVER_HOME
/oracle/u01/app/oracle/product/Companion $ cd Apache/Apache/conf
/oracle/u01/app/oracle/product/Companion/Apache/Apache/conf $ vi httpd.conf

Stellen Sie sicher, dass das Modul mod_proxy geladen wird - die ensprechende LoadModule-Anweisung darf nicht mit einem # auskommentiert sein:

:
LoadModule dbm_auth_module    libexec/mod_auth_dbm.so
LoadModule digest_module      libexec/mod_digest.so
LoadModule proxy_module       libexec/libproxy.so
LoadModule cern_meta_module   libexec/mod_cern_meta.so
LoadModule expires_module     libexec/mod_expires.so
:

Wenn Sie den Oracle HTTP Server basierend auf Apache 2.0 verwenden, sieht das Laden des Proxy-Moduls etwas anders aus:

:
LoadModule dbm_auth_module    modules/mod_auth_dbm.so
LoadModule digest_module      modules/mod_digest.so
LoadModule proxy_module       modules/mod_proxy.so
LoadModule proxy_http_module  modules/mod_proxy_http.so
LoadModule cern_meta_module   modules/mod_cern_meta.so
:

Navigieren Sie nun zur Datei dads.conf, in welcher die Application Express-Konfiguration enthalten ist (manche Application Express-Installationen verwenden auch die Datei marvel.conf):

/oracle/u01/app/oracle/product/Companion/Apache/Apache/conf $ cd $COMPANION_CD_HOME
/oracle/u01/app/oracle/product/Companion $ cd Apache/modplsql/conf
/oracle/u01/app/oracle/product/Companion/Apache/modplsql/conf $ vi dads.conf

Fügen Sie der Datei dads.conf folgende Zeilen hinzu:

ProxyRequests On
ProxyPass /mapviewer/ http://[mapviewer-host]:8888/mapviewer/
ProxyPassReverse /mapviewer/ http://[mapviewer-host]:8888/mapviewer/
NoCache *

Auch diese Einträge sehen etwas anders aus, wenn Sie den Oracle HTTP Server basierend auf Apache 2.0 verwenden.

ProxyRequests On
ProxyVia      Off
ProxyPass /mapviewer http://[mapviewer-host]:8888/mapviewer

Starten Sie den Apache-Server anschließend neu. Testen Sie das Proxy-Modul, in dem Sie im Browser die URL von Application Express eingeben, anstelle von /pls/apex oder /pls/apex geben Sie jedoch /mapviewer/ ein. Sie sollten dann die MapViewer-Startseite sehen.

Abbildung 2: Zugriff auf den Oracle MapViewer über Hostnamen und TCP/IP-Port von Application Express

6. Einrichten der MapViewer Client Bibliothek in der Datenbank

Die folgenden Schritte sind für Oracle MAPS nicht notwenig; Sie benötigen sie nur dann, wenn Sie mit dem MapViewer "klassisch" arbeiten möchten, also jede darzustellende Karte vom MapViewer komplett neu erstellt werden soll. In den meisten praktischen Fällen ist jedoch eher die Nutzung von Oracle MAPS zu empfehlen.

Die nun folgenden Schritte sind erforderlich, damit Ihre Application Express-Anwendung mit dem MapViewer kommunizieren, also Map Requests via HTTP an diesen und Map Responses von diesem empfangen kann. Dazu muss ein PL/SQL-Paket in die Datenbank eingespielt werden. Mit diesem PL/SQL-Paket werden Sie später in der Lage sein, Karten vom MapViewer anzufordern. Sie benötigen für diese Schritte DBA-Privilegien auf Ihrer Datenbank.

Laden Sie die MapViewer Client-Bibliothek aus dem Oracle Technet herunter. Packen Sie das ZIP-Archiv aus. Spielen Sie dann die Datei mvclient14.jar als DBA mit dem loadjava-Kommando der Oracle-Datenbank wie folgt ein (das loadjava-Kommando wird aus der Betriebssystem-Ebene heraus aufgerufen).
```
.../> ls
sqlmvclient14.zip

.../> unzip sqlmvclient14.zip
  
  inflating: sdomvclb.sql
  inflating: sdomvclh.sql
  inflating: sqlmvxlient.readme
  inflating: mvclient14.jar
  inflating: readme.txt

.../> loadjava -force -schema mdsys -grant PUBLIC -user system/[Passwort] mvclient14.jar
```

Loggen Sie sich nun mit SQL*Plus als DBA in Ihre Datenbank ein und starten Sie die beiden SQL-Skripte sdomvclb.sql und sdomvclh.sql.

$ sqlplus system/[Passwort]

SQL*Plus: Release 10.2.0.2.0 - Production on Tue Feb 20 11:58:15 2007

Copyright (c) 1982, 2005, Oracle.  All Rights Reserved.


Connected to:
Oracle Database 10g Enterprise Edition Release 10.2.0.2.0 - Production
With the Partitioning, Oracle Label Security, OLAP and Data Mining options

SQL> start sdomvclh.sql
SQL> start sdomvclb.sql

Nun müssen Sie noch einige Rechte vergeben: Sowohl das Schema MDSYS als auch das Parsing Schema Ihrer Application Express-Anwendung benötigen zur Kommunikation mit dem MapViewer entsprechende Netzwerk-Privilegien. Den Namen Ihres Parsing Schemas finden Sie in den Anwendungsattributen .

Abbildung 4: Anwendungsattribute: Parsing Schema

Setzen Sie (mit DBA-Privilegien) folgende SQL-Anweisungen ab:

$ sqlplus system/[Passwort]

SQL*Plus: Release 10.2.0.2.0 - Production on Tue Feb 20 11:58:15 2007

Copyright (c) 1982, 2005, Oracle.  All Rights Reserved.


Connected to:
Oracle Database 10g Enterprise Edition Release 10.2.0.2.0 - Production
With the Partitioning, Oracle Label Security, OLAP and Data Mining options

SQL> call dbms_java.grant_permission(
  2       'MDSYS',
  3       'SYS:java.net.SocketPermission',
  4       '[Mapviewer-Hostname]:8888',
  5       'connect, resolve'
  6     );

SQL> call dbms_java.grant_permission(
  2       '[Parsing-Schema]', 
  3       'SYS:java.net.SocketPermission',
  4       '[Mapviewer-Hostname]:8888',
  5       'connect, resolve'
  6     );

Nun existiert in Ihrer Datenbank das PL/SQL-Paket SDO_MVCLIENT. Dies können Sie jetzt nutzen, um eine Karte anzufordern und in Ihre Anwendung zu integrieren.

Zurück zur Community-Seite