Installing pocOLAP is fairly simple.  The hardest part of the process is preparing your data and writing the configuration file.  To make installation as painless as possible, pocOLAP is distributed with a sample database which can be used to verify the installation was successful.

Assume that everything is case-sensitive when setting up pocOLAP (or any project for that matter).  Generally, if changes can be made to folder or files names, it is indicated in the documentation - changing other folder or file names may cause problems.

To run pocOLAP, you need the following:
	A web server (Tomcat is used as an example, though the application has been tested with JBoss as well).
	
If you plan on building pocOLAP, you'll also need:
	Ant
	JUnit 
	JDom, Log4j, Derby.jar, hsqldb.jar and possibly others (the easiest way to get these is to "borrow" them from the WEB-INF/lib directory of the pocolap.war file that comes with the download from sourceforge).
	Cactus (though this requirement will be going away soon!)
	Eclipse (okay, so you don't need this, but you may want it just cuz it's so darn cool)
	
Setting up Tomcat:
	The jakarta site has information on obtaining and setting up Tomcat.  Once you can see the "you've setup Tomcat successfully" page, consider this step done.

	If you are using another web server, you may need to make adjustments to the rest of the instructions.  We'd love to hear about any problems or successes you've had with other servers!
	
Unpacking the zip file:
	Assuming you retrieved pocOLAP as a zip file, you'll need to "unzip" it before running the application.  After unzipping the file, you'll find a new directory with, among other things, the following:
		pocolap.war
		pocolapDB/
		
	Move pocolap.war to the webapps directory of Tomcat.  Make sure to set the permissions so that the process running Tomcat has full access to the file.  On winxp systems, you'll need to right click on the pocolapDB directory, select properties, uncheck the read-only attribute, and apply this to "this folder, subfolders and files".  If you're installing this on a *nix system, you can run "chown tomcat pocolap.war" (assuming Tomcat is the account running your server).
	
	Copy the pocolapDB directory to either "/tmp" or "C:/", depending on your operating system.  Make sure to set the permissions on these files so that the process running Tomcat has read and write access to them.  If you're installing this on a *nix system, you can run "chown -R tomcat pocolapDB" (assuming Tomcat is the account running your server).  If you're on a windows system, make sure that the read-only attribute is not set (especially on xp systems, this attribute seems to get "stuck").
	
Taking it out for a test drive:
	Make sure Tomcat is running.  Then, open a browser and navigate to http://localhost:8080/pocolap/ReptPage.jsp.  If Tomcat is running on a port other than 8080, please adjust the url accordingly.
		
Moving things around:
	The “pocolapDB” directory is referred to as the applications “internal database”.  You can move this directory and/or rename it, though the contents should not be modified (at least until you understand what those changes will affect).  To do move or rename the internal database, you will need to modify the web.xml file within pocolap.war.  The “war” file can be “unzipped” with most compression utilities.  Inside the WEB-INF/web.xml file, look for the following entry:
	<init-param>
		<param-name>pocolap.DB.location</param-name>
		<param-value></param-value>
	</init-param>

Add the path to the new location in between the “<param-value>” and “</param-value>” tags.  If you've renamed the name of the directory, be sure to include this name in your path entry.  If you retain the name “pocolapDB”, including the name is optional.  

Setting up logging:
 	The internal database contains a file named “log4j.properties”.  If you don't make any changes to this file, a log file named pocolaplog.txt will be placed in the internal database directory.  	If you'd like to change the logging settings, modify the log4j.properties file.  Changes made while the application is running will be reflected usually within a minute.

	For additional information on how to configure logging for the pocolap application, check out the “How to setup logging.txt” file in CVS.  Or better yet, help us out and write this section for us!

Removing the sample reports and adding reports of your own:
	The crosstab viewer is generated from information found in xml files inside the “crosstabdefs” directory within the internal database.  The defaul installation places two files in this directory, both of which point to databases in the sampleDB directory.  The “derbyconfig.xml” points to a Derby based database, while the “hsqldbconfig.xml” file points to an HSQLDB based database.  Removing one of these files from the “crosstabdefs” directory and restarting the application will cause that report to disappear.  Replacing the file and restarting restores the report.

	In order to use pocOLAP with your own data, you need to create an xml file describing your table schema.  There is a pdf file distributed with the application that explains how to build this file.  You can use the sample files in crosstabdefs as templates.  Also, feel free to contact the pocOLAP development team for help.
		
Troubleshooting:
	Most of the problems associated with installing pocOLAP stem from the internal database directory not having the proper permissions set.  There is a pocolaplog.txt file that will explain what is happening when the aplication starts up.  If this file is missing, your web server does not have permission to write to the directory, a guaranteed recipe for disaster.  Change the permissions of the internal database directory, restart Tomcat and see if the problem disappears (along with future frustration).

	Q: "I get this, or a similar error:
		javax.servlet.ServletException: Table not found: SALES in statement [select "SALABLEITEMS"."VENDOR" "Vendor Name", "CUSTOMERS"."LASTNAME" ..."
	A: The nss.properties and nss.script file are either not in "/tmp/pocolapDB/sampleDB" or "C:\pocolapDB\sampleDB" or the permissions are not set correctly.  Ensure these files are in the proper directory for your OS and that the permissions allow the user account that runs Tomcat to read and write these files.
	
	If you encounter this error and find that the files are indeed in the correct location, but the permissions are set improperly, follow these steps:
	1)  Remove nss.properties, nss.script and nss.data (if it exists) from the "/tmp" or "C:/" directory.
	2)  Copy the nss.properties and nss.script files to either "/tmp" or "C:/"
	3)  Make sure the permissions are correct!
	4)  Restart Tomcat (or reload the pocolap application) 

	Q: "I've got permissions set properly, but I get an error that says that my database doesn't have a table that I know is there"
	A: Some databases (like Derby), automatically convert identifiers if they are not delimited on creation.  For example, if you set up your database using "create table mytable (....", the database may have it stored as "MYTABLE".  Because pocOLAP attempts to run everything with delimiters, "mytable" won't be found.  Change the table and field names in your configuration file to all caps and see if that cures the problem.
	
	Q: "I get this error:
		java.lang.IllegalStateException: SQLException: Can't connect: File input/output error: /tmp/nss.properties java.io.FileNotFoundException: /tmp/nss.properties (Permission denied)
	A: The nss.properties and nss.script files do not have the proper permissions.  The process running your web server must have read and write permissions on these files.
	
	Q: "I get this error:
		org.apache.jasper.JasperException: Couldn't set database identifierQuoteString"
	A: There's something wrong with the <source> tag in your config.xml file.  Check for correct driver, dbString, user, pass, catalog and classname.
	
	Q: "I get this error:
		javax.servlet.ServletException: No WareHouse Schema files found on servlet startup."
	A: Check the value of the <param-value> in the <init-param> section of the web.xml file.  There must be a <param-name> tag that starts with "whs_", and a corresponding <param-value> tag that points to a configuration file.
	
	Q: "I get a warning or exception after redeploying the war file in Tomcat"
	A: Tomcat doesn't seem to handle redeployment as well as it once did.  While the Tomcat team may disagree with that statement, we have encountered may problems trying to redeploy war files.  We recommend not redeploying the pocolap war file.  If you are developing and run across this issue, you can try coping classes that you change and recompile directly to the explode directory in webapps and then copy in web.xml again (the new copy of web.xml should trigger Tomcat to restart the application).
	
	Q: "I got an error not listed here"
	A: PLEASE let me know what error you got.  Not only will I try to help you troubleshoot it, I'll add it here in future distributions (or try to avoid it from occurring at all).
	
	 

Please help!
	If you recognize ways to make the installation easier, or the documentation clearer, please let us know!  There are only so many hours in the day and only so many items our brains can process at a time - any assistance you can provide will be welcomed!