6 MapViewer PL/SQL API

Deprecated Feature: MapViewer PL/SQL API:

The MapViewer PL/SQL API is deprecated, and will not be included in future releases of the documentation.

Instead, you are encouraged to either (A) use one of the other supported MapViewer APIs, or (B) use Oracle Application Express (APEX) with the MapViewer JavaScript API.

This chapter describes the PL/SQL application programming interface (API) to MapViewer. This API consists of the PL/SQL package SDO_MVCLIENT, which is intended for Oracle Database users who want to access MapViewer services from inside an Oracle database. This package exposes most capabilities of MapViewer, and it handles all communication with the actual MapViewer server running on a middle tier on behalf of a user making map requests.

6.1 Installing the SDO_MVCLIENT Package

The SDO_MVCLIENT package is not currently installed by default. Instead, you must install the package by running two SQL scripts that are supplied with MapViewer: sdomvclh.sql and sdomvclb.sql.

To perform the installation, go to the sql directory under the $MAPVIEWER_HOME directory, start SQL*Plus, connect as a user that has the DBA role (for example, SYSTEM), and enter the following commands:

@sdomvclh
@sdomvclb

After you run these two scripts, exit SQL*Plus, go to the $MAPVIEWER_HOME/web/WEB-INF/lib directory, and use the shall command loadjava to load the mvclient.jar file into the MDSYS schema. For example (and assuming the use of the SYSTEM account with the password manager):

loadjava -force -schema mdsys -grant PUBLIC -user system mvclient.jar
Password: password

Database users can now use the SDO_MVCLIENT PL/SQL package, as described in Section 6.2.

6.2 Using the SDO_MVCLIENT Package

The SDO_MVCLIENT PL/SQL package communicates with a remote MapViewer service through the HTTP protocol. For each database session, it maintains a global MapViewer client handle, as well as the current map request and map response objects.

The usage model for the SDO_MVCLIENT package is almost identical to that of MapViewer JavaBean-based API (described in Chapter 4). Most methods implemented in the MapViewer JavaBean-Based API (oracle.lbs.mapclient.MapViewer) are available in this PL/SQL package, and the package uses the same method names and parameters used by the JavaBean-Based API. For usage and reference information about specific functions or procedures, see the description of the associated JavaBean-Based API. methods and interfaces in Chapter 4.

The basic workflow for accessing the MapViewer service through this PL/SQL package is almost identical to that for using the Java client API, except for some initial setup. Follow these major steps, each of which is described in a section to follow:

Grant network access (see Section 6.2.1).
Create a MapViewer client handle (see Section 6.2.2).
Prepare a map request (see Section 6.2.3).
Send the request to the MapViewer service (see Section 6.2.4).
Optionally, extract information from the map request (see Section 6.2.5).

6.2.1 Granting Network Access

Grant network access permission to each database user that will use the SDO_MVCLIENT package. For example, if database user SCOTT will need to use the package, you must enter a statement in the following general form while connected as a user with DBA privileges:

call dbms_java.grant_permission('SCOTT', 'SYS:java.net.SocketPermission',
                                'www.mycorp.com',
                                'connect, resolve' );

In the preceding example, change www.mycorp.com to the host on which the MapViewer service is running.

Depending on the Oracle Database version, you may also need to grant network access to the database user MDSYS, which owns the SDO_MVCILENT package. To do this, enter a statement in the following general form while connected as a user with DBA privileges:

call dbms_java.grant_permission('MDSYS', 'SYS:java.net.SocketPermission',
                                'www.mycorp.com:8888',
                                'connect, resolve' );

In the preceding example, change www.mycorp.com to the host on which the MapViewer service is running.

The call to dbms_java.grant_permission needs to be done only once for each affected database user; the permission remains valid for all subsequent database sessions for these users.

6.2.2 Creating a MapViewer Client Handle

Before each database session, you must create a MapViewer client handle before using any functions or procedures of the SDO_MVCLIENT package. The following example creates a MapViewer client handle:

connect scott
Enter password: password
call sdo_mvclient.createmapviewerclient(
     'http://www.mycorp.com:8888/mapviewer/omserver') ;

The preceding example creates, in the current session, a unique MapViewer client handle to the MapViewer service URL http://www.mycorp.com:8888/mapviewer/omserver. To use this example, change www.mycorp.com to the host on which the MapViewer service is running.

After you have created a MapViewer client handle, you can perform the following query to check that MapViewer is running correctly:

select sdo_mvclient.getdatasources() datasources from dual;

The SQL function sdo_mvclient.getdatasources() is part of the MapViewer PL/SQL package API; and when it is executed, it connects to the remote MapViewer server and gets a list of all known data sources. If the installation is successful and the MapViewer server is running, the result of the preceding example is output similar to the following, with the string array containing the names of the data sources that are defined in the MapViewer server:

DATASOURCES
--------------------------------------------------------------------------------
SDO_1D_STRING_ARRAY('mvdemo', 'wms')

6.2.3 Preparing a Map Request

Call various methods in the PL/SQL package to prepare a map request, which will eventually be sent to the MapViewer server for processing. You can specify the basic characteristics of the map to be created, and you can add temporary styles and multiple themes to the current map request.

Example 6-1 sets the data source and other map characteristics, adds a dynamically defined color style to the map request, and manipulates a theme.

Example 6-1 Preparing a Map Request

call sdo_mvclient.setDataSourceName('mvdemo');
call sdo_mvclient.setImageFormat('PNG_URL');
call sdo_mvclient.setAntiAliasing('true');
call sdo_mvclient.setBaseMapName('qa_map') ;
call sdo_mvclient.setBox(-122.3615, 37.4266, -121.1615, 37.6266);
call sdo_mvclient.setDevicesize(500,400);
 
call sdo_mvclient.addColorStyle('colorst', 'blue', 'yellow', 100,100);
 
select sdo_mvclient.addJDBCTheme('mvdemo', 'theme1',
       'select geom from states where state_abrv = ''CA''',
       'geom', '8307', 'C.RED', null, null, 'FALSE') from dual ;

6.2.4 Sending the Request to the MapViewer Service

The following example effectively sends the current map request to the remote MapViewer server for processing. It will return after the request has been processed at the server.

select sdo_mvclient.run() from dual;

You can also use such methods as sdo_mvclient.zoomIn() and sdo_mvclient.zoomOut() to get zoomed maps.

6.2.5 Extracting Information from the Map Request

The following example extracts the URL string of the generated map image:

select sdo_mvclient.getgeneratedMapImageURL() from dual;

After you have the URL of the map image, you can do various things, such as fetch and store the image in a database table, or present the map with other information on a HTML page.