Oracle Map Viewer 11g and JBOSS EAP 6.4.0 GA

I recently had the pleasure of installing Map Viewer into JBOSS and ran into all sorts of fun issues along the way. The purpose of this article is to document the steps that need to be taken to get Map Viewer deployed properly. This guide is being written as more of a rough draft reference so please excuse the lack of grammar and formatting.


As a note due to licensing I will be using the evaluation “Express” edition of Oracle Database and therefore some of the functionality of the Map Viewer editor will not work as it would if you are using a regular edition. Also, this installation is being done on Linux but it could easily be done on Windows as well just using Console (along with the differing commands) instead of Terminal.

Step 1: Download and install Java and JBoss. Make sure both environment variables JAVA_HOME and JBOSS_HOME are set to the location of the installations. Also, if you plan to run Oracle Database and JBoss on the same machine make sure to change the bind address in JBoss from 8080 to 8081 in “${JBOSS_HOME}/standalone/configuration/standalone.xml”. Just search for the only “8080” entry and change it to “8081”.

Step 2: Using the “adduser” script in “${JBOSS_HOME}/bin” add a user named “mvuser” as an Application User in the ApplicationRealm with role “map_admin_role”.

Step 3: Add the Oracle JDBC module to JBoss. For this you need to create the “module.xml” seen below and also place the Oracle JDBC dependency into the module’s main directory. This more or less allows you to reference this dependency from a deployment.

Now, download ojdbc6.jar (download) and place it in “${JBOSS_HOME}/modules/com/oracle/ojdbc6/main”.

Step 4: Prepare the Map Viewer deployable. Assume you downloaded the Map Viewer EAR file to “~/temp/”

There is a lot going on here so I’ll give a little explanation. The Map Viewer deployable is originally packaged within an EAR (enterprise archive) however it is unnecessary as there are no shared libs at the EAR level and Map Viewer is a single deployment. With the unzip command we uncompress the EAR and the WAR (web archive) and then rename the WAR to “mapviewer” as JBoss makes use of the deployment name as the context root if not specified in either a jboss-web.xml configuration file or an EAR’s application.xml. Next, as Map Viewer needs to make use of the Oracle JDBC driver we must add the JBoss module dependency. This can either be done with the creation of a jboss-deployment-structure.xml or more easily with adding the dependency to the MANIFEST file. Next, Map Viewer requires you to login as an administrator before you can do anything fun so we will make use of the Application User we made in Step 2 by adding the ApplicationRealm to users who are allowed to log in. Finally, we move the deployable into the JBoss deployments directory and, due to the deployable being uncompressed, need to trigger deployment with a *.dodeploy file.

*Note: If you are unfamiliar with “sed” the syntax can be kind of confusing. What you see above is:

  1. -i: Edits the file in place. This means all changes made be sed will be saved to the file
  2.  ‘4s/^/ some text/’: This is a regular expression that says at line 4 substitute ^ the starting position within the string with some text

Step 5: Check out the Admin webpage. Navigate to “http://localhost:8080/mapviewer” (8081 if you configured JBoss to bind to that port). Click on the “Admin” link the top right and login with the Application User you created in Step 2.

Step 6: Add a user/scheme to the Oracle Database for Map Viewer: Login to your Oracle database and run the following command replacing “ceres” with the host name of your database server:

Step 7: Run scripts to update the Oracle Database for Map Viewer and the Map Viewer Editor. Once again replace “ceres” with your Oracle database server host name.

The USER_SDO_CACHED_MAPS view is used by the Oracle Maps feature. It stores definitions of map tile cache instances. You must create this view manually by running the following script while connected as the SYSTEM user. The SQL script is located in “${JBOSS_HOME}/standalone/deployments/mapviewer.war/WEB-INF/admin/mcsdefinition.sql”

The USER_SDO_EDIT_SESSIONS view is used when using the Map Viewer Editor. You must create this view manually by running the following script while connected as the SYSTEM user. The SQL script is located in “${JBOSS_HOME}/standalone/deployments/mapviewer.war/WEB-INF/admin/sdedefinition.sql”

Step 8: Add a data source. Usually we would configure a JBoss data source in the JBoss configuration so that our data source could be found over JNDI however when you do this JNDI makes use of a generic data source wrapper which cannot be cast to the Oracle specific data source and causes a ClassCastException. Instead, we are going to configure a data source directly from the Map Viewer deployment. You can either do the following through the Map Viewer Admin Configuration or directly modifying the file “${JBOSS_HOME}/standalone/deployments/mapviewer.war/WEB-INF/conf/mapViewerConfig.xml”. Uncomment the “map_data_source” element at line 490 and modify it to look like the following:

The parameters are as follows:

  • name: The name of the data source. This will be used as the designator when selecting the data source from Map Viewer applications.
  • jdbc_host: The host name of the server where the Oracle Database is running. In my case “ceres”.
  • jdbc_sid: The Oracle System ID (SID) is used to uniquely identify a particular database on a system. As I am using the Express edition the default SID is “xe”. If using regular edition the default SID is “orcl”.
  • jdbc_port: The port that Oracle Database is listening for connections on.
  • jdbc_user: The scheme of the database. You can think of a user/scheme as a private area where database objects are stored and accessible only within that area.
  • jdbc_password: The password for the user/scheme. You will notice the exclamation point (!) in front of the password. This tells Map Viewer to encrypt the password upon deployment.
  • jdbc_mode: The JDBC driver mode.
  • number_of_mappers: Performance related.
  • allow_jdbc_theme_based_foi: Not quite sure.
  • editable: Determines if the objects within the scheme editable by the user. If using the Map Viewer Editor this must be true.

Once you’ve modified the data source restart JBoss and navigate back to “http://localhost:8080/mapviewer” (8081 if you configured JBoss to bind to that port). You should now see the “mapviewer” data source under “Datasources”

Step 9: Rejoice in accomplishment. Map Viewer is now installed and ready to be used.

Step 10: Oh, you actually want to validate that Map Viewer is working? Fine. A separate download from Oracle is the Map Viewer Demo (outside the scope of this document) which contains a nice little utility named “JView” that allows you to run queries against tables containing spatial data and renders said data on a map. Instead of going through the entire process of downloading the Map Viewer Demo and loading all the necessary data for it just copy the attached “jview.jsp” document into “${JBOSS_HOME}/standalone/deployments/mapviewer.war” and then navigate to “http://localhost:8080/mapviewer/jview.jsp”. From here you will be able to run your spatial queries. Also attached is a simple SQL script containing some Oracle geometries which will show up through JView. Long story short to validate the installation you need to:

  1. (Download) “colab.sql.txt”, rename it to “colab.sql” and run the script as “mvuser”: ~:$sqlplus mvuser:password@ceres @colab.sql
  2. (Download) “jview.jsp.txt”, rename it to “jview.jsp”, and place it in the Map Viewer Web Archive (WAR)
  3. Navigate to “http://localhost:8080/mapviewer/jview.jsp” and run the following query: “SELECT * FROM cola_markets2”. This should result in a nice drawing with a couple geometries on it.

Once you do this you should see something like: