This post describes how to deploy the Oracle Spatial’s Map Visualization Component (map viz) that is shipped with Oracle database 19.3 to a Tomcat 9 instance.
The Map Viz Component ships as a zip file mapviewer.ear.zip, which can be found in an Oracle database 19.3 instance’s <oracle_home>/md/jlib directory.
Note that the bundled mapviewer.ear.zip file is intended for and tested with Oracle WebLogic Server 22.214.171.124.0+ only. It needs additional jar files and edits to web.xml in order to work with other containers such as Tomcat 9.
Also note that it's best to define MapViewer data sources directly in its config file instead of trying to define it in Tomcat, for simplicity.
The detailed steps for Tomcat 9 are given below.
Step 1: unzip the file mapviewer.ear.zip into a folder named mapviewer.ear.
Step 2: Locate the web.war sub-folder in the mapviewer.ear folder. Rename this sub-folder to “mapviewer”.
Step 3: Use a text editor to open the web.xml inside the “mapviewer/WEB-INF” folder. Modify the login-config as follows:
Remove the “CLIENT-CERT” and the comma, leaving only “FORM” as the content of the <auth-method> tag to make it <auth-method>FORM</auth-method>.
Save the changes.
Step 4: Download common dependent 3rd party jar files that are included in Weblogic :
The mapviewer.ear shipped with Oracle Database 19.3 does not bundle a number of required JAR files which exist in a Weblogic server environment. So, in order for it to work in Tomcat manually download those missing JAR files and add them to the “mapviewer/WEB-INF/lib” folder.
There are 3 sets of JAR files (Jersey, Jackson parser, JDBC) that need to be downloaded.
Java REST API Jersey2:
Unzip and then copy each jar file in each sub-folder (api, ext, lib) and paste into the “mapviewer/WEB-INF/lib” folder.
Jersey2 Companion Jars:
These two jars should also be copied into the “mapviewer/WEB-INF/lib” folder.
Jackson JSON Parser:
Copy and paste these three JAR files into the “mapviewer/WEB-INF/lib” folder.
Oracle JDBC Driver:
Finally, go to the Oracle Database 19c JDBC Driver & UCP Downloads page (https://www.oracle.com/database/technologies/appdev/jdbc-ucp-19c-downloads.html), and download the 19.3 JDBC Thin driver (odjbc8.jar), the Universal Connection Pool (ucp.jar) and the companion jars:
Unzip or untar the downloaded archive and then copy and paste all the files, in each sub-folder, with the extension “.jar” to the “mapviewer/WEB-INF/lib” folder.
The next step is deploying the mapviewer.ear toTomcat. But first we need to make sure Tomcat is set up to allow users to log in as a MapViewer administrator. This is typically done by editing the Tomcat server config file as shown below.
Locate and open the file <apache-tomcat-home>/conf/tomcat-users.xml in a text editor.
Add these two lines before the </tomcat-users> tag:
<user username="admin" password="<chosen_admin_pwd>" roles="map_admin_role"/>
The creates a new Tomcat role named “map_admin_role”, and a Tomcat user named “admin”, with the newly created role (needed by the Map Viz Component at runtime to recognize a logged in user as a MapViewer administrator). If necessary designate other existing Tomcat users as Map Viz Component admin by adding the “map_admin_role” to that user’s roles list.
Note: A user pointed out that an additional set of changes need to be made for Tomcat. Add the following at the end of the catalina.properties file.
That got rid of an "Invalid CSRF token" that they experienced.
You may need to restart Tomcat for the above to take effect.
Now we are finally ready to deploy and run the Map Viz Component in Tomcat 9.
To deploy the Map Viz Component, simply copy the folder “mapviewer” and paste it inside the Tomcat’s web apps folder: <apache-tomcat-home>/webapps/.
Your folder structure should now look like the screenshot below:
Once copied, Tomcat should automatically notice the new web application and start it up. Alternatively, you may need to log into Tomcat’s admin web application and manually start the newly deployed application “/mapviewer”.
To test that the Map Viz Component is working, simply access its URL from a browser:
Log in as a Tomcat user with the “map_admin_role” role when prompted.