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$
    (log)
    Copyright (C) 2005-2006 Pentaho and others