Running Oracle Mapviewer in Apache Tomcat

I have been interested in trying out Oracle Mapviewer for some time, since I have been working with Oracle Spatial for several years, and finally decided to take time to evaluate it for adding some new visualization options for the spatial data where I work.

After reading briefly through the Mapviewer documentation, it became apparent that Oracle for obvious reasons wants you to use their application server. We already use Tomcat where I work, and since this was for evaluation purposes, and Mapviewer is essentially a J2EE web application, I figured I'd try to get it running in the Tomcat container.

Note that Oracle does say that Mapviewer should run in other containers--including Tomcat--but doesn't offer any instructions. There was some information in the forums, but I figured if I got it running, I'd post something to make it simpler for others.

Here are the details:
Note that I shall refer to the directory to which you installed Tomcat as [TOMCAT_HOME], and the directory where you have the Oracle database server installed as [ORACLE_SERVER_HOME].

1. First, here are the platform details
• Apache Tomcat 7.0.2
• JDK-6
• Windows environment (XP)
2. Download Mapviewer here. You shall need to unzip the downloaded file, then look for the file mapviewer.ear. When you find it, unzip this file (.ear files are just zip files), and from that file, extract the file mapviewer.war.
   
3. Assuming you have Tomcat installed and mapviewer.war, place mapviewer.war in [TOMCAT_HOME]\webapps
4. Start Tomcat by running startup.bat in the [TOMCAT_HOME]\bin directory. This shall start the tomcat container, and explode (meaning unzip, war files are zip files too) the mapviewer.war into a directory called mapviewer (all standard stuff here). The startup for mapviewer shall fail, because there are a few more libraries that are missing. If you open the catalina.[current date].log file in
   the [TOMCAT_HOME]\logs directory, you'll likely see the following Exception:
   

   Sep 21, 2010 8:38:34 AM org.apache.catalina.startup.HostConfig deployWAR
   SEVERE: Error deploying web application archive mapviewer.war
   java.lang.NoClassDefFoundError: oracle/i18n/util/LocaleMapper
   at oracle.xml.parser.v2.XMLReader.setEncoding(XMLReader.java:904)
   at oracle.xml.parser.v2.XMLReader.checkXMLDecl(XMLReader.java:3059)
   at oracle.xml.parser.v2.XMLReader.pushXMLReader(XMLReader.java:502)
   at oracle.xml.parser.v2.XMLReader.pushXMLReader(XMLReader.java:232)
   at oracle.xml.parser.v2.XMLParser.parse(XMLParser.java:218)
   ...
   Caused by: java.lang.ClassNotFoundException: oracle.i18n.util.LocaleMapper
   at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1666)
   at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1511)
   at java.lang.ClassLoader.loadClassInternal(ClassLoader.java:319)
   

   This is because mapviewer is looking for the class oracle.i18n.util.LocaleMapper which is not bundled with mapviewer. This class is part of the "Oracle Database Globalization Development Kit." There are 9 jar files that make up that kit. The jar that contains this missing class is called orai18n-mapping.jar, and it is provided with your Oracle 11 server installation. It can be found here:
   

   [ORACLE_SERVER_HOME]\jlib

   If you bought (or downloaded) oc4j, go to the [OC4J_HOME]\jdbc\lib directory, it should be there as well. I have oracle 11GR2 installed. In the orai18n-mapping.jar file I used, I opened the jar file in winzip, and in the Manifest.mf file, it had the following version information:
   

   Specification-Version: "Oracle Globalization Development Kit - 11.2.0.1.0 - Production, Build : 11

5. Shut tomcat down by running shutdown.bat in the bin directory. Place the orai18n.jar file in one of the following directories:
   
   1. [TOMCAT_HOME]\lib - This shall make this jar global to all applications including mapviewer.
   2. [TOMCAT_HOME]\webapps\mapviewer\WEB-INF\lib - This makes the jar available locally only to mapviewer. The downside is, if you remove mapviewer and redeploy it, you shall need to replace any jars in this directory again. Most non-developers shall probably prefer making the jar global as in choice a.
6. Restart tomcat again. You are going to get another exception when mapviewer tries to deploy:
   

   Sep 21, 2010 9:21:59 AM oracle.lbs.mapcache.MCSServlet init
   INFO: MapTileServer root path:  C:\javalib\apache-tomcat-7.0.2\webapps\mapviewer\
   Exception in thread "Thread-2" Sep 21, 2010 9:21:59 AM oracle.lbs.mapcache.MCSServlet init
   INFO: mbean domain: DefaultDomain
   java.lang.NoClassDefFoundError: oracle/sql/CLOB
   at oracle.lbs.mapcache.MapCacheServer.(MapCacheServer.java:110)
   at oracle.lbs.mapcache.MCSServlet$ColdStart.run(MCSServlet.java:119)
   at java.lang.Thread.run(Thread.java:619)
   Caused by: java.lang.ClassNotFoundException: oracle.sql.CLOB
   

   
   This is because it is missing oracle's jdbc driver. You can obtain this driver any number of ways. I recommend obtaining it from your oracle install again. To obtain, go here:[ORACLE_SERVER_HOME]\jdbc\lib.
   
   In the jdbc directory (the one above lib), there is a readme.txt file which explains the various versions of the jdbc drivers oracle installs. Choose the one that best suits you from the lib directory. For this example, I used ojdbc6.jar. Like the previous step, you can place this jar in Tomcat's lib directory, or in mapviewer's WEB-INF lib directory. Whichever suits you.
   
7. Shutdown Tomcat again, and restart. This time, the mapviewer should start up cleanly. Assuming you are running Tomcat in the default installation, it should be listening at port 8080. Open the following URL in your web browser: http://localhost:8080/mapviewer. Adjust accordingly if you are running on a different port.
   
   You should now see the mapviewer homepage. From here, you should probably set up the admin.