Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

Data Admin System Documentation - Tomcat Notes

This document contains special IBIS-PH Data Admin System notes and some items to consider if using Tomcat as the Java web application server. See the IBIS-PH View System Tomcat Setup Notes page for general Tomcat setup notes. This page mainly deals with JDBC driver setup as the View System's Tomcat notes discusses all other IBIS-PH related topics.

Installation Steps:

  1. Download and install J2SE JDK 1.5+
  2. Download and install the Tomcat web application server
  3. Setup/configure the Tomcat Java JVM
  4. Edit/configure the Tomcat's default Deployment Descriptor (web.xml)
  5. Edit/configure Tomcat's control file to configure the JNDI and JDBC (server.xml)
  6. Physically delete/remove the standard Tomcat webapp(s)
  7. Download and install the JDBC driver jar file(s) to the [CATALINA_HOME]/common/lib directory.
  8. Deploy the IBIS-PH Admin webapp

NOTES



Configure Tomcat's server.xml

This is the main configuration file that controls the host engine and application contexts.
IMPORTANT: Make a backup copy of this file before editing.

<Server port="8007" shutdown="remoteshutdown" debug="0">

REMOVE ALL OTHER WEBAPP CONTEXTS

For a production environment, comment out or remove all the defined "Context" elements which includes examples, ROOT, etc. These elements are contained within the Host element and look like: 
<Context path="/examples" docBase="examples" debug="0"
	. . .

ADD IBISPH Data Administration System CONTEXT

For OIT where the Data Administration System is to be the default/root app add the following: 
<Context path="" docBase="ibisph-view" debug="0" 
	reloadable="false" crossContext="false"
/>
<Context path="/ibisph-view" docBase="" debug="0" 
	reloadable="false" crossContext="false"
/>
NOTES: For development, leave the reloadable="true" so that the app will auto reload whenever any of the class files change (e.g. if re-compiled). For those that do NOT want cookie support, add the cookies="false" attribute to the Context element. Session objects will then use URL re-writing.

TWO CONTEXTS FOR A GIVEN APP: Tomcat requires a default/root app. Tomcat also auto creates contexts within applications it finds within it's default appBase folder. So if the Data Administration System is setup as the default app, Tomcat will auto create a context with the path of "/ibisph-view/". The problem/issue is if there are 2 contexts both pointing to the same docbase then you'll get 2 instances of the same app within the webapp server container/JVM which run separately but use/share the same files. So for something like artifacting, you'll have files which have navigation built for potentially two different contexts. In the old way of artifacting a hash was used which really could get things messed up pretty quick - concerning. To get around this create a blank or a dummy docBase which matches the /ibisph-view path. This forces Tomcat to not auto create a working "ibisph-view" app. Note that Tomcat 559 will complain if a base of "dummy" or any other invalid/non existent directory name is specified. It doesn't complain about "" being used. There are other ways around this also like not having a "base" webapps directory and simply having a single app under a single virtual host. Also can put directory outside of the base directory then the path looks funny etc.

ANOTHER WAY NOTES: Specify the Host appBase attribute to be: webapps/ibisph-view then set the docBase of the context to / and the admin's docBase to ../ibisph-admin. The blank dummy context can then be removed. The Data Administration System as of Oct, 2005 handles both contexts being used. However, with artifacting, the first time the page is artifacted is how the menuing system will be saved. So if the ibisph-view/home/Welcome.html is hit first then all of it's navigation will be ibisph-view/... (which works) but then if someone else comes and hits a page as the root/default app then some pages will have the ibish-view context while others will have navigation links that have a blank context.

WARS, AUTODEPLOY, CONTEXTS: if a context is specified, the war won't auto redeploy (even if enabled). To get around this you need to delete the app's files and then the system will auto deploy the war (assuming enabled and the war is in the webapps directory).

DEVELOPMENT DIRECTORY NOTE: If you have your webapp located outside the normal directory specified with the Host element then you'll need to explicitly point to that directory in the "docBase" attribute.



NOTE ABOUT APP SERVLET MAPPING (web.xml): You can have a blank servlet alias but then everything will be funneled through that servlet. So all requests for jsps javascripts, css, etc. would all hit that servlet and not be served up as web content.

ADD IBISPH ADMIN SYSTEM CONTEXT

The data admin system needs a context due to it's JNDI/JDBC db connection. The opening of this context element is: 
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true">
	*** JNDI/JDBC RESOURCE ELEMENTS GO HERE - SEE NEXT SECTIONS ***
</Context>
If you're wanting the ability to auto reload JSPs without having to clear the Tomcat's work/build directory then set reloadable="true"

See the sections below on how to configure the JNDI JDBC data source resource elements needed. Note that while similar, these elements differ and can be quite picky about what elements and attribute settings will allow the system to work with the version of that database's jdbc build/jar. If there are problems then you'll need to read that vendors jdbc docs on how to setup for tomcat or googlize it. Also note that the configurations are set for local development. For production systems the username, password, and URL type information will all need to be set as needed.

IBISPH-ADMIN CONTEXT MATCHING DEPLOYMENT PATH: The "ibisph-admin" context must be defined and must match the deployment path. This is because for jndi data sources to be found for servlets that auto load the context path MUST match the actual deployment path. So for admin you can set the path to be admin but because autoload is set in the ibisph-admin deployment descriptor, the app will try to autoload based on that ibisph-admin context path and thus will throw because the context isn't defined. However, the admin context will work - you just won't be able to connect to a db!!!

MYSQL JNDI / JDBC RESOURCE

FOR TOMCAT 4.x: mysql-connector-java-3.0.9-stable-bin.jar. Also tested the mysql-connector-java-3.1.6-bin.jar with the configuration below and it worked!!! However, for TOMCAT 5, this does NOT work (at least with 3.0.x or the 3.1.x driver). 
<Context path="/ibisph-admin" docBase="ibisph-admin" 
	debug="0" reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="javax.sql.DataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>driverClassName</name>
			<value>com.mysql.jdbc.Driver</value>
		</parameter>
		-or (both work)-
		<parameter>
			<name>driverClassName</name>
			<value>org.gjt.mm.mysql.Driver</value>
		</parameter>

		<parameter>
			<name>url</name>
			<value>
				jdbc:mysql://localhost:3306/ibisph
					?autoReconnect=true
			</value>
		</parameter>
		<parameter>
			<name>username</name>
			<value>the_ibisph_owner_username</value>
		</parameter>
		<parameter>
			<name>the_ibisph_owner_password</name>
			<value>ibisph</value>
		</parameter>
		<parameter>
			<name>maxWait</name>
			<value>100</value>
		</parameter>
		<parameter>
			<name>maxIdle</name>
			<value>1</value>
		</parameter>
		<parameter>
			<name>maxActive</name>
			<value>10</value>
		</parameter>
		<parameter>
			<name>removeAbandoned</name>
			<value>true</value>
		</parameter>
		<parameter>
			<name>removeAbandonedTimeout</name>
			<value>60</value>
		</parameter>
	</ResourceParams>
</Context>
Note About the JDBC Factory: Some sites show a factory parameter which according to the Apache Tomcat book is not needed. The factory is only needed for older tomcats that use Tyrex data source factory by default (Tomcat 4.0.04 up to 4.1.3). So don't include a Resource/ResourceParams/parameter element like this: 
<parameter>
	<name>factory</name>
	<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>

FOR TOMCAT 5.5.x: jars tried: mysql-connector-java-3.0.16-ga-bin.jar and mysql-connector-java-3.1.6-bin.jar. Tried different configs and different jars but couldn't get anything to work except and this resource setup: 
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="javax.sql.DataSource" maxActive="100" 
		maxIdle="30" maxWait="10000" 
		username="the_ibisph_owner_username" 
		password="the_ibisph_owner_password"
		driverClassName="com.mysql.jdbc.Driver"
		url="jdbc:mysql://localhost:3306/ibisph
			?autoReconnect=true"
	/>
</Context>

ORACLE JNDI/JDBC RESOURCE

This configuration has been tested and works for associated Oracle JDBC versions 8.x and 9.x (all named classes12.zip). 
<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" auth="Container" 
		type="oracle.jdbc.pool.OracleConnectionPoolDataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>factory</name>
			<value>oracle.jdbc.pool.
				OracleDataSourceFactory
			</value>
		</parameter>
		<parameter>
			<name>url</name>
			<value>
				jdbc:oracle:thin:[USERNAME]/
					[PASSWORD]@[CONNECT]
			</value>
		</parameter>
	</ResourceParams>
</Context>

MS SQL SERVER JNDI/JDBC RESOURCE

<Context path="/ibisph-admin" docBase="ibisph-admin" debug="0" 
	reloadable="false" crossContext="true"
>
	<Resource name="jdbc/hl_ibisph_admin" 
		scope="Shareable" type="javax.sql.DataSource"
	/>
	<ResourceParams name="jdbc/hl_ibisph_admin">
		<parameter>
			<name>url</name>
			<value>
			  jdbc:microsoft:sqlserver://10.228.0.98:1433;
			  DatabaseName=ibisph;user=ibisph_admin_owner;
			  password=ibisph
			</value> 
		</parameter>
		<parameter>
			<name>driverClassName</name>
			<value>
			  com.microsoft.jdbc.sqlserver.SQLServerDriver
			</value>
		</parameter>
	</ResourceParams>
</Context>

COPY SYSTEM WIDE COMMON JARS TO [CATALINA_HOME]/common/libs

Copy the common, system wide, JDBC libs/zips/jars (e.g. Oracle/MySQL/SQL Server jdbc drivers) into the [CATALINA_HOME]/common/lib folder. Note that for the ibisph applications the JDBC drivers are the only drivers that qualify to be placed in this folder. All other jars are packaged within the application. The exception to this are the XML packages which are discussed later. If there are any common application jars these would be placed in Tomcat's "shared" folder. Since the IBISPH applications are designed for minimum system administration on other non-dedicated app servers, each application contains all of it's needed java packages (other than core packages like JDBC drivers, the servlet extensions etc.).

ORACLE NOTES:
MY SQL NOTES:
Have experienced issues with different vernons of Tomcat, MySQL JDBC drivers, and Context/Resource connection configurations. See ibisph-admin MySQL Context section for more info.

SQL SERVER NOTES:
Not much experience but the jdbc version that was tested used/needed the following 3 jar files:


TEST URLS

Note: favorite bookmarks are stored in the user's area under my favorites (for IE) and typically in C:\Documents and Settings\username\Application Data\Mozilla\Firefox\Profiles\default.7pi\bookmarks.html for NS/FF.

LOCAL / DEVELOPMENT MACHINE:
General Tomcat
Admin System (assuming the app is using the "ibisph-admin" context path)
Local Data Administration System (assuming the app is the default app, if not add the appropriate app context path)


ORACLE INFO / CONNECTION CACHE NOTE FROM CASTER FAQ

<database name="..." engine="oracle" >
	<driver class-name="oracle.jdbc.driver.OracleDriver"
		url="jdbc:oracle:thin:@localhost:1521:TEST" >
			<param name="user" value="SYSTEM"/>
			<param name="password" value="manager"/>
	</driver>
	...
</database>

ORACLE CACHE VERSION: 
<database name="..." engine="oracle" >
	<data-source 
		class-name="oracle.jdbc.pool.OracleConnectionCacheImpl"
	>
		<params URL="jdbc:oracle:thin:@localhost:1521:TEST" 
			user="SYSTEM" password="manager"
		/>
	</data-source>
	...
</database>



JNDI ENTRIES - HOW TO (server.xml)

Added JNDI entries for system urls as a way around using property files. Then could put all properties into the web.xml as parameters thus not needing property files. These are put into the conf/server.xml file. Need to be in the form of: 
<env-entry>
	<env-entry-name>ibisph/homeURL</env-entry-name>
	<env-entry-value>http://localhost:8080/ibisph-view/Transform
		?xslt=home.xslt
		&xml=home/home.xml
	</env-entry-value>
	<env-entry-type>java.lang.String</env-entry-type>
</env-entry>

URLS / LINKS