Pentaho Analysis Services: Installing Mondrian 1.1.5 on Windows with PostgreSQL

Installing Mondrian 1.1.5 on Windows with PostgreSQL (8.x)

## Contents

1. About these installation notes
2. Download and extract the distribution files
3. Set up your environment
4. Load the test database
5. Install Mondrian (build the "mondrian.war" file)
6. Deploy the application
7. Disclaimer

## 1. About these installation notes

The binary distribution of Mondrian 1.1.5 works well with little or no tweaking, with the Access database (.mdb file) provided with the distribution. Getting it to work with PostgreSQL however, requires some tweaking, and the most reliable way to get it up and running is to rebuild the "mondrian.war" from the source (available as part of the binary distribution).
These installation notes will help you install Mondrian in the following environment:

- OS: Windows XP/2000 (for database and servlet container)
- JDK: JDK 1.5.0_01
- Database: PostgreSQL 8.0
- Servlet container: Tomcat 5.0.28

You should still be able to use these installation instructions with variations in the above environment (e.g., a different version of Tomcat or a different version of PostgreSQL, etc.). However, it is more than likely that in case of version differences, some steps may either be redundant (e.g., if you are installing on a higher version of Tomcat) or some steps may be missing (e.g., if you are installing on a lower version of Tomcat).

These notes have been produced based on Patrick Tallman's instructions for installing on Windows. Those instructions appear to be based on Mondrian 1.0.1 and therefore appeared out of sync with Mondrian 1.1.5. These notes retain significant portions of Patrick Tallman's instructions, but excludes portions that are now redundant and addresses some issues not specifically addressed earlier. The instructions have also been reorganized.

Please note the use of the following symbols in this document:

[!]: indicates an instruction/observation that requires special attention (either because you must be careful with the version or because it can result in a common human error).

[#]: indicates an explanation/special notice usually intended to explain a particular approach or remind you of a previous situation.

## 2. Download and extract the distribution files

Along with the Mondrian distribution, you must also download the JPivot distribution because the build script uses a .war file from the JPivot distribution. The distribution is available at the following URLs:

- Mondrian: http://sourceforge.net/projects/mondrian - download Mondrian 1.1.5 from this URL
- JPivot: http://sourceforge.net/projects/jpivot/ - download "JPivot Web Frontend" from this URL

Once you have downloaded the distribution files, extract them as follows:

1. Extract the contents of mondrian-1.1.5.zip. This will create a folder called "mondrian-1.1.5". It is recommended that you rename this to "mondrian-1.1.5-bin". This is only for housekeeping purposes and has no bearing whatsoever on the installation process. This folder (either "mondrian-1.1.5" or "mondrian-1.1.5-bin/", depending on whether you chose to rename the directory or not) will hereinafter be referred to as %BIN_LOCATION%.
2. Create a folder called "mondrian-1.1.5-src" at the same level as "%BIN_LOCATION%".
3. Extract the contents of mondrian-1.1.5-src.zip (located in "%BIN_LOCATION%/dist/") into the folder "mondrian-1.1.5-src". All contents will automatically get created in the folder "mondrian-1.1.5-src/mondrian-1.1.5/". If you wish, for disambiguity and ease of housekeeping, you may move all contents from "mondrian-1.1.5-src/mondrian-1.1.5/" directly into "mondrian-1.1.5-src/". This folder (either "mondrian-1.1.5-src/mondrian-1.1.5" or "mondrian-1.1.5-src/", depending on whether you chose to move the contents or not) will hereinafter be referred to as %DEV_LOCATION%.
4. Extract the contents of jpivot-1.4.0.zip. This will contain a file called "jpivot.war". Copy this file into "%DEV_LOCATION%/lib".

## 3. Set up your environment

This section walks you through the steps to set up your environment to build the Mondrian web archive. As part of setting up the environment, you need to ensure that you have the resources described in this section. If you do not have the latest/recommended versions, you may need to download them from the URLs specified. Once you have downloaded these resources, you must set up certain environment variables.

#### Resources

You will need (to download) the following in order to set up your environment:

- JDK: JDK 1.5 or higher (http://java.sun.com/j2se/1.5.0/download.jsp)
- Servlet container: Tomcat 5.x
- Database: PostgreSQL 8.0 or higher (http://www.pervasivepostgres.com/downloads/ or http://www.postgresql.org/download/)
- JDBC driver: PostgreSQL JDBC driver (http://jdbc.postgresql.org/)

Typically, the above will suffice if you need to merely deploy a binary distribution that you have downloaded. In order to build the "mondrian.war" from source, you will require the following additional resources.

[!] While variations of the database (and therefore of the JDBC driver) or of the servlet container are possible, the following cannot be changed in the deployment environment since there is a strong dependency on these packages/components.

- Xalan: Xalan 2.7.0 or higher recommended (http://xml.apache.org/xalan-j/) (Xalan is an XSLT processor that helps you convert XML documents into other formats; typically, HTML)
- Ant: Ant 1.5.x (http://archive.apache.org/dist/ant/binaries/).
  [!] The latest release is Ant 1.6.5, but a few problems have been reported with this version. It is therefore recommended that you use 1.5.x
- JUnit: JUnit - 3.8.x recommended (http://www.junit.org/index.htm)

It is likely that one or more of these components or an older version of it, is already installed on your system. Please contact your System Administrator if you need help finding out if you have an older version, or with installation of any of these softwares that you have to download. Installation instructions for each of the above are available on the respective websites from which you will download these resources.

#### Environment variables

Once you have installed/ascertained that you have all the above components, you must set up some environment variables (these are used by the build script):

- ANT_HOME
- CATALINA_HOME
- JAVA_HOME
- JUNIT_HOME
- XALAN_HOME

You may skip this step (setting up environment variables) if you wish, but you must then take care of it in the build script. It is strongly recommended that you address this at this point by setting up environment variables, unless you have a strong reason not to do so.

## 4. Load the test database

The Mondrian distribution is accompanied by a test database (the classic "Foodmart" database). This database must be loaded for you run the examples available with the distribution. You will have to make use of the following resources from the distribution to load the database.

- mondrian.test.loader.MondrianFoodMartLoader: A data loading utility that takes an input JDBC URL or file reference (from which the schema and test data are to be taken), an output JDBC URL and connection parameters (for the target database in which the schema must be created and data loaded), and one or more flags to indicate the schema objects that must be created (tables, data, etc.). This utility is packaged in "%BIN_LOCATION%/lib/mondrian.jar".
- %BIN_LOCATION%/demo/access/MondrianFoodmart.mdb: MS Access database containing the complete foodmart database. This will be accessed through the DSN created by you in Sec. 3.
- %BIN_LOCATION%/demo/access/FoodMartCreateData.sql: Text file containing "INSERT INTO" SQL statements to load test data.

Execute the following steps to load the test database:

1. Create a database and database user: Create a database user called "foodmart" (password: "foodmart"). Then create a database called "foodmartdb" owned by the user "foodmart".
2. Copy the JDBC driver: Copy the Postgres JDBC driver into "%BIN_LOCATION%/lib".
3. Load the database: Open a command prompt window and change your current directory to "%BIN_LOCATION%". At the command prompt, run the command
   java -cp "%BIN_LOCATION%\lib\mondrian.jar;%BIN_LOCATION%\lib\log4j-1.2.9.jar;%BIN_LOCATION%\lib\eigenbase-xom.jar;%BIN_LOCATION%\lib\eigenbase-resgen.jar;%BIN_LOCATION%\lib\postgresql-8.0-312.jdbc3.jar" mondrian.test.loader.MondrianFoodMartLoader -verbose -tables -data -indexes -jdbcDrivers="org.postgresql.Driver,sun.jdbc.odbc.JdbcOdbcDriver" -inputFile=%BIN_LOCATION%\demo\FoodMartCreateData.sql" -outputJdbcURL="jdbc:postgresql://localhost/foodmartdb" -outputJdbcUser=foodmart -outputJdbcPassword=foodmart
   [!] Please note the following:
   - This command must be executed as a single command. When you copy+paste the above command into an editor, whitespaces/carriage returns will be introduced that will cause syntax errors. Be sure to replace these spaces if you copy+paste this command.
   - All items in the above command marked in RED will have to be replaced by the actual value (path, filename, database name, user name, etc.) applicable for your system.

## 5. Install Mondrian (build the "mondrian.war" file)

There are three sets of activities in creating the web archive: modifying some files, copying some files and running the ant script. Each of these is detailed out in this section.

#### Modify files

The source code that we extracted from mondrian-1.1.5-src.zip contains among others, three files that require to be changed before mondrian.war can be built. These are "mondrian.properties", "build.bat" and "build.xml". Changes to each of these files is detailed below.

1. Changes to mondrian.properties: The changes in this file are predominantly changes to connection strings; the path to the Tomcat home directory is also to be specified here.
   In particular, the following changes are to be made:
   - Replace Jdbc=jdbc:odbc:MondrianFoodMart;\
     with Jdbc=jdbc:postgresql://localhost/foodmartdb?user=foodmart&#38;password=foodmart;\
     [!] Please note the use of "&#38;". It is important NOT to directly use an ampersand here.
   - Replace JdbcDrivers=sun.jdbc.odbc.JdbcOdbcDriver;\
     with JdbcDrivers=org.postgresql.Driver;\
   - Replace mondrian.foodmart.jdbcURL=jdbc:odbc:MondrianFoodMart
     with mondrian.foodmart.jdbcURL=jdbc:postgresql://localhost/foodmartdb?user=foodmart&#38;password=foodmart
     [!] Please note the use of "&#38;". It is important NOT to directly use an ampersand here.
   - Uncomment the line "tomcat.home" and set the correct path.
   - Modify the line "@set CLASSPATH" - replace all "/" (forward-slash) with a "\" (backslash).
2. Changes to build.bat: In this file, replace %ANT_HOME%\bin\ant %1 %2 %3 %4 %5 %6 %7 %8 %9
   with "%ANT_HOME%\bin\ant" %1 %2 %3 %4 %5 %6 %7 %8 %9 (add quotation marks around the path).
   This is to address problems that can potentially be caused by spaces in the names of folders (supported in the recent versions of Windows).
3. Changes to build.xml: In this file, references to the JDBC driver and to the XALAN path need to be changed. Specifically, the changes to be made are:
   - Replace <property name="mondrian.jdbcDrivers" value="sun.jdbc.odbc.JdbcOdbcDriver"/>
     with <property name="mondrian.jdbcDrivers" value="org.postgresql.Driver"/>
   - Replace <property name="mondrian.foodmart.jdbcURL" value="${mondrian.foodmart.jdbcURL.access}"/>
     with <property name="mondrian.jdbcDrivers" value="jdbc:postgresql://localhost/foodmartdb?user=foodmart&#38;password=foodmart"/>
     [!] Please note the use of "&#38;". It is important NOT to directly use an ampersand here.
   - Modify the target "jar". This task has a zipfileset tag defined as follows:

     > `<zipfileset
     > dir="."
     > includes="
     > LICENSE.html,
     > README.txt,
     > VERSION.txt"/>`

     This must be modified to include mondrian.properties as follows:

     > `<zipfileset
     > dir="."
     > includes="
     > mondrian.properties,
     > LICENSE.html,
     > README.txt,
     > VERSION.txt"/>`

   - Modify the target "copy-jars". The path to the Xalan JAR files (xalan.jar,xml-apis.jar,xercesImpl.jar) is specified as "{xalan.home}/bin". This must be modified to "{xalan.home}" (remove the "/bin").

#### Copy files

1. Copy the file %DEV_LOCATION%\mondrian.properties to %CATALINA_HOME%\bin
2. Copy the files "xalan.jar", "xercesImpl.jar", "xml-apis.jar" and "serializer.jar" from "%XALAN_HOME%" to %CATALINA_HOME%\common\endorsed.
   [#] These files are not really required for the build per sé, but can create problems at run-time. It is just as well that these are copied at this time. Further, the files "xercesImpl.jar" and "xml-apis.jar" must be overwritten even though they exist since the files distributed with Tomcat appear to be an older version than the ones distributed with the latest version of Xalan.

#### Run the build script

To create and deploy the mondrian.war file, execute the build in serial order with flags as indicated below:

1. build clean
2. build
3. build jar
4. build war
5. build deploy-war

## 6. Deploy the application

There is a final set of changes to be made in 4 JSP files before the application can be used successfully.

First, start Tomcat and allow it to extract "mondrian.war" and create the folder "mondrian". Once it has extracted the archive, shut down Tomcat. Use a HTML/JSP editor and modify the following files under "mondrian/WEB-INF/queries/" as described:

1. colors.jsp
2. fourhier.jsp
3. mondrian.jsp
4. trendarrows.jsp

In each of the above files, replace

> <jp:mondrianQuery id="query01" jdbcDriver="sun.jdbc.odbc.JdbcOdbcDriver" jdbcUrl="jdbc:odbc:MondrianFoodMart" catalogUri="/WEB-INF/queries/FoodMart.xml">

with

> <jp:mondrianQuery id="query01" jdbcDriver="org.postgresql.Driver" jdbcUrl="jdbc:postgresql://localhost/foodmartdb?user=foodmart&#38;password=foodmart" catalogUri="/WEB-INF/queries/FoodMart.xml">

[!] Please note the use of "&#38;". It is important NOT to directly use an ampersand here.

Next, check the "WEB-INF/web.xml". Check the value of the "connectString" parameter under
"<servlet-name>MDXQueryServlet</servlet-name>".

This must have the value "jdbc:postgresql://localhost/foodmartdb?user=foodmart&#38;password=foodmart" catalogUri="/WEB-INF/queries/FoodMart.xml". If it does not have the value, please update this.

After making these modifications, remove the "%CATALINA_HOME%/work/Catalina/localhost/mondrian" folder and restart Tomcat.

## 7. Disclaimer

(To be appropriately modified at a later date).

These instructions are being circulated on a "AS-IS" basis. They are based on the Mondrian 1.1.5 distribution available at the time of producing this document. They have not been extensively reviewed, and the specific settings prescribed here, including instructions to overwrite existing files, may or may not have an impact on existing applications. Even at the time of publishing these document, it is known that not all features of the application work as expected. The contents of this document may also be rendered null and void by a subsequent release of Mondrian (which implicitly addresses some of the issues sought to be addressed here). As such these instructions accept no responsibility or liability towards the accuracy of, or errors of commission or omission in the contents on this page.

For feedback, suggestions, complaints on this document, please write to:
suhasmallya[AT]users[DOT]sourceforge[DOT]net

Author: Suhas Mallya; last modified: 19 October, 2005.
Version: $Id$ (log)
Copyright (C) 2005-2006 Pentaho and others