%META:TOPICPARENT{name="InstallConfigJDBC"}%
= Using UDA with JBoss 4.0.3 (Linux) =

%TOC%

== Required components ==

You will need to download the following components

* JBoss - [[http://www.jboss.com|download]]
* JDK - [[http://java.sun.com|download]]
* opltest.war Web Application - [[http://wiki.usnet.private:8791/twiki/pub/Main/UDATomcatLinux/opltest.war|download]]
* OpenLink jar file - one of these, appropriate to the selected JDK/JRE -
|  <nop>*JDK/JRE/JVM*  |  *OpenLink JDBC Driver*  |
|  1.1  |  [[http://www.openlinksw.com/|opljdbc.jar]]  |
|  1.2 or 1.3  |  [[http://www.openlinksw.com/|opljdbc2.jar]]  |
|  1.4 or 1.5  |  [[http://www.openlinksw.com/|opljdbc3.jar]]  |
|  1.6  |  [[http://www.openlinksw.com/|opljdbc4.jar]]  |
|  1.7  |  [[http://www.openlinksw.com/|opljdbc4_1.jar]]  |
|  1.8  |  [[http://www.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 JBoss ==

Installing JBoss 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 JBoss will be known as; {{{$JBOSS_DIST}}}


== Starting JBoss ==

Start JBoss using the command --
{{{
$JBOSS_DIST/bin/run.sh
}}}

Browse to the following url to verify that JBoss is up and running --
{{{
http://tomcat_server:8080
}}}

NOTE: JBoss may take several minutes to start.


== Install OpenLink jar files ==

Copy the {{{.jar}}} file chosen for your JDK/JVM/JRE 
into the directory --
{{{$JBOSS_DIST/server/default/lib}}}

Stop and restart JBoss with the commands --
{{{Control-C will stop JBoss
$JBOSS_DIST/bin/run.sh}}}


== Create the data sources file ==

JBoss requires a special file to declare the data sources.

Create a new file --
{{{$JBOSS_DIST/server/default/deploy/opltest-ds.xml}}}

to include the following data sources --

{{{
<?xml version="1.0" encoding="UTF-8"?>

<!--  Datasource config for OpenLink -->

<local-tx-datasource>
  <jndi-name>jdbc/o32opljdbc1</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=Odbc/Database=sqlserver/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

<local-tx-datasource>
  <jndi-name>jdbc/m32opljdbc1</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=SQLServer 2000/Database=Northwind/options=-H 192.168.0.150/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

<local-tx-datasource>
  <jndi-name>jdbc/o32opljdbc2</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=Odbc/Database=sqlserver/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc2.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

<local-tx-datasource>
  <jndi-name>jdbc/m32opljdbc2</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=SQLServer 2000/Database=Northwind/options=-H 192.168.0.150/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc2.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

<local-tx-datasource>
  <jndi-name>jdbc/o32opljdbc3</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=Odbc/Database=sqlserver/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc3.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

<local-tx-datasource>
  <jndi-name>jdbc/m32opljdbc3</jndi-name>
  <connection-url>jdbc:openlink://192.168.0.150:5000/SVT=SQLServer 2000/Database=Northwind/options=-H 192.168.0.150/UID=sa/PWD=sa</connection-url>
  <driver-class>openlink.jdbc3.Driver</driver-class>
  <user-name>sa</user-name>
  <password>sa</password>
</local-tx-datasource>

</datasources>
}}}

NOTE: You will need to amend URLs, usernames and passwords as appropriate.


== 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 ==

Deploying on JBoss is simply a case of placing the Web application --
{{{opltest.war}}}

into the following directory --
{{{$JBOSS_DIST/server/default/deploy}}}

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