Running MapViewer on a WebLogic server cluster

This post describes how to deploy and run MapViewer version 11g R1 on a basic WebLogic cluster.

For information and instructions on how to setup a simple WebLogic cluster, please check out this excellent blog post. If you followed his instructions, you will have a WebLogic domain that contains a cluster of 3 managed servers. Lets call this the main domain. You will also create a second domain that contains a load balancing servlet (HttpClusterServlet) deployed as its only web application. Lets call this the proxy domain. The main domain's managed servers will be listening on ports 7003,7004 and 7005, while the proxy domain will be listening on 7001. You will deploy MapViewer to the main domain (specifically, to its cluster which is composed of the 3 managed servers), but access MapViewer via port 7001 such as http://localhost:7001/mapviewer. Each web session accessing MapViewer will be redirected to one of the 3 managed server's in a round-robin fashion.

Load balancing servlet's web.xml
While following Andrejus' instructions, when it's about time to deploy the load balancing servlet to the proxy domain, you will need to create a web.xml file for the servlet. You can use the sample web.xml, however for MapViewer to function completely, I have attached my own web.xml below. The main difference is that in my example I added url patterns for .jspx, .png, .gif and .jpeg so these files also get redirected to the managed servers from the proxy servlet.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd";>

<web-app>

<servlet>
<servlet-name>HttpClusterServlet</servlet-name>
<servlet-class>
weblogic.servlet.proxy.HttpClusterServlet
</servlet-class>

<init-param>
<param-name>WebLogicCluster</param-name>
<param-value>
localhost:7003|localhost:7004|localhost:7005
</param-value>
</init-param>

</servlet>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>/mapviewer</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jsp</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.htm</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.html</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.js</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.png</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jspx</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.gif</url-pattern>
</servlet-mapping>

<servlet-mapping>
<servlet-name>HttpClusterServlet</servlet-name>
<url-pattern>*.jpeg</url-pattern>
</servlet-mapping>

</web-app>


Deploy MapViewer
Deploying MapViewer to a cluster is actually no different from deploying it to a regular WebLogic server. Basically, follow these simple steps (for more details, please check out the MapViewer User's Guide which has a step-by-step guide):

1. Create a WebLogic JDBC data source for your spatial database schema. Deploy (install) this data source to the cluster! This container data source will be the basis of the MapViewer data source to be created in step 3.
   
2. Unpack mapviewer.ear and setup the required directory tree structure (again details can be found in MapViewer's User's Guide). This will be the working directory tree for MapViewer! Every WLS clustered server will start its own MapViewer instance out of this directory. Each started MapViewer instance will then load the config file from the WEB-INF/conf folder, as well as saving all generated map images and tiles into this same directory tree. If your managed servers span different physical machines, then this folder needs to be on a shared network drive accessible by all the managed servers.
   
3. Modify the MapViewer config file, located in the WEB-INF/conf/ folder, to set a proper logging level. Most importantly, you need to create a MapViewer data source based on the container data source you created in step 1. A simple example of such a data source looks like this:
   <map_data_source name="mvdemo"
   container_ds="jdbc/mvdemo"
   number_of_mappers="7"
   allow_jdbc_theme_based_foi="true"
   />
   Another thing you must modify in the config file, is the <save_images_at> element. Make sure the url attribute is set to a URL that points to the proxy domain, for instance "http://localhost:7001/mapviewer/images". And change the path attribute to "../../images".
   
4. Go to the console web page of the main domain, and deploy MapViewer from the exploded directory tree. Note that when presented with the "Soure accessibility" page during deployment, make sure you select the last option ("I will make the deployment accessible from the following location")! This is extremely important, as it ensures the MapViewer files are shared by all managed servers, and generated tiles/maps are shared also.
5. After deployment is done, simply access MapViewer from your browser http://localhost:7001/mapviewer. Everything should work just fine as if you are accessing a normal MapViewer server.
   
6. Verify that there are 3 MapViewer instances are running. Go to the exploded MapViewer folder, and change into the directory mapviewer.ear/web.war/WEB-INF/conf/. There you should see a file mv_proc.id. Open it in any text editor, and you should see a number 3. This means MapViewer has acknowleged there are 3 separate instances running.
   

You now have a MapViewer deployed and running on a cluster of managed WebLogic servers. Each MapViewer instance will be accessing the same database schema using the same cluster-wide container data source for optimal usage of the JDBC connections. MapViewer will intelligently and automatically avoid file name conflicts when generating and saving map images, FOI images as well map tiles. This is critical in a clustered environment since all MapViewer instances share a single physical working directory tree (the exploded MapViewer folder).