Installing Mondrian 1.1.5 on Windows with PostgreSQL (8.x)
Contents
- About
these installation notes
- Download and extract the
distribution files
- Set up your environment
- Load the test database
- Install Mondrian (build the
"mondrian.war" file)
- Deploy the application
- 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:
Once you have downloaded the distribution files, extract them as
follows:
- 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%.
- Create a folder called "mondrian-1.1.5-src"
at the same level as "%BIN_LOCATION%".
- 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%.
- 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:
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.
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:
- 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".
- Copy the JDBC driver: Copy the Postgres
JDBC driver into "%BIN_LOCATION%/lib".
- 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.
- 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&password=foodmart;\
[!] Please note the
use of "&". 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&password=foodmart
[!] Please note the
use of "&". 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).
- 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).
- 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&password=foodmart"/>
[!] Please note the
use of "&". 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
- Copy the file %DEV_LOCATION%\mondrian.properties
to %CATALINA_HOME%\bin
- 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:
- build clean
- build
- build jar
- build war
- 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:
- colors.jsp
- fourhier.jsp
- mondrian.jsp
- 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&password=foodmart"
catalogUri="/WEB-INF/queries/FoodMart.xml">
[!] Please note the use of "&".
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&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: //open/mondrian/doc/install_postgresql.html#7 $
(log)
Copyright (C) 2005-2006 Julian Hyde and others