%META:TOPICPARENT{name="InstallConfigJDBC"}%
= Using UDA with Apache Tomcat 5.5 (Linux) =

%TOC%

== Required components ==

You will need to download the following components

*Tomcat - [[http://tomcat.apache.org|download]]
* Tomcat Administrator - [[http://tomcat.apache.org|download]]
* opltest.war Web Application - [[./JDBCAppServerTomcatLinux?att=opltest.war|download]]
* JDK - [[http://java.sun.com|download]]
* OpenLink jar file - one of these, appropriate to the selected JDK/JRE -

|  *JDK/JRE/JVM*  |  *OpenLink JDBC Driver*  |
|  1.1  |  [[http://download.openlinksw.com|opljdbc.jar]]  |
|  1.2 or 1.3  |  [[http://download.openlinksw.com|opljdbc2.jar]]  |
|  1.4 or 1.5  |  [[http://download.openlinksw.com|opljdbc3.jar]]  |
|  1.6  |  [[http://download.openlinksw.com|opljdbc4.jar]]  |
|  1.7  |  [[http://download.openlinksw.com|opljdbc4_1.jar]]  |
|  1.8  |  [[http://download.openlinksw.com|opljdbc4_2.jar]]  |



== Install JDK ==

Install the JDK by running the *.bin, which automatically extracts the JDK.

NOTE: You may need to set the execute permission on the bin file before it can be executed.


== Set Environment Variables ==

The following environment variables must be set -- 
{{{
  export JAVA_HOME=/usr/java/jre1.5.0_05
  export PATH=$PATH:/usr/java/jdk1.5.0_05/bin
}}}

The simplest way is to add these to your -- {{{~/.bash_profile=}}} (or similar, depending on **//$SHELL//**) to ensure they are set every time you log in.

NOTE: Paths to your Java installation will most likely differ!


== Install Tomcat ==

Install Tomcat by running gunzip and tar against the downloaded {{{*.tar.gz}}} file, which will extract the archive into the current working directory.
{{{
gunzip *.tar.gz
tar -xvf *.tar
}}}

The root install directory of Tomcat will be known as; {{{CATALINA_HOME}}}


== Enable Tomcat Manager Web Application ==

Edit the file --
{{{$CATALINA_HOME/conf/tomcat-users.xml}}}
to read --
{{{
<?xml version='1.0' encoding='utf-8'?>
	<tomcat-users>
		<role rolename="tomcat"/>
		<role rolename="role1"/>
		<role rolename="manager"/>
		<role rolename="admin"/>
		<user username="tomcat" password="tomcat" roles="tomcat,manager,admin"/>
		<user username="both" password="tomcat" roles="tomcat,role1"/>
		<user username="role1" password="tomcat" roles="role1"/>
	 </tomcat-users>
}}}

This will add the **//manager//** and **//admin//** roles, and allocate these roles to the **//tomcat//** user.

NOTE: Ensure the following is the first line of the file otherwise Tomcat will not start -
{{{
<?xml version='1.0' encoding='utf-8'?>
}}}

Start Tomcat using the command --
{{{$CATALINA_HOME/bin/startup.sh}}}

Browse to the following url to verify the Web Manager application is running --
{{{http://tomcat_server:8080/manager/http}}}

This Web application will allow quick deployment of future Web applications.

== Install OpenLink jar files ==

Copy the {{{.jar}}} file chosen for your JDK/JVM/JRE into the directory --
{{{$CATALINA_HOME/common/lib}}}


Stop and restart Tomcat with the commands -- 
{{{
$CATALINA_HOME/bin/shutdown.sh
$CATALINA_HOME/bin/startup.sh
}}}


== Prepare the Web Application ==

Demonstrating how to build and deploy a Web application from the beginning is beyond the scope of this short tutorial so what follows is a quick method of altering the JDBC URLs and SQL statements in an existing Web application.

NOTE: Be careful when moving .war files about using Internet Explorer. Sometimes they will be renamed to .zip by Internet Explorer.

=== Rename the .war file to .zip ===

Rename - {{{opltest.war}}} -to- {{{opltest.zip}}}

You will then be able to unzip the archive to get at the files inside it.  (Some utilities can unzip the .war archive without renaming.)
{{{unzip opltest.zip}}}

=== Edit JDBC URLs ===

Edit the driver class and the JDBC connection URL in the file --
{{{/META-INF/context.xml}}}

NOTE: Ensure that the edited file is placed back into the archive.
{{{zip -r ../opltest *}}}


=== Edit the SQL statement(s) ===

You will need to edit the SQL statement(s) in <i>the following JSP files</i> based on the chosen database determined by the JDBC URL in the file --
{{{/META-INF/context.xml}}}

Edit the JSP files --
{{{
opljdbc.jsp
opljdbc2.jsp 
opljdbc3.jsp
}}} 

There are two main areas of interest --

#The &lt;sql:query&gt; tag which select the datasource as defined in - {{{/META-INF/context.xml}}}%BR% 
which contains the SQL query itself -- %BR% 
{{{<sql:query var="resultset" dataSource="jdbc/opljdbc2">
		select SupplierID, CompanyName, ContactName, ContactTitle from Suppliers
	</sql:query>}}}
		%BR% 
#The one or more ${row.column_name} constructs that output data as per the SQL query %BR% 
{{{${row.SupplierID}
${row.CompanyName} }}}


NOTE: Ensure that the edited file is placed back into the archive.
{{{zip -r ../opltest *}}}

=== Rename the .zip file back to .war ===

Rename the file {{{opltest.zip}}} back to {{{opltest.war}}}

== Deploy opltest Web Application ==

Open the Tomcat Manager --
{{{http://tomcat_server:8080/manager/http}}}

Scroll down to the "War file to deploy" section.

Use the "Browse..." button to browse to the file --
{{{opltest.war}}}

Finally, click the "Deploy" button.

The screen will refresh and you should see the new application in the list with its "Running" property set to true.

The newly deployed application is now available at the following URL --
{{{http://tomcat_server:8080/opltest}}}