TOMCAT Integration Guide for Altibase#
Overview#
This technical document describes how to integrate Altibase and TOMCAT. This document is written for Altibase version 6.3 and TOMCAT version 7.0.
Info
For errors and improvements related to this document, please contact the technical support portal or technical support center.
- Technical support portal: http://support.altibase.com/en
- Technical support center: +82-2-2082-1114
Info
This document is provided for informational purposes only and is subject to change without prior notice. It may contain errors, and Altibase makes no express or implied warranties of any kind, including but not limited to warranties of merchantability or fitness for a particular purpose.
The development, release, and timing of any features or functionality described for Altibase products in this document are at the sole discretion of Altibase.
Altibase may hold patents, trademarks, copyrights, or other intellectual property rights related to the contents of this document.
TOMCAT Installation#
Let's take a brief look at how to install TOMCAT. Let's install the TOMCAT 7 product.
Before installing the TOMCAT, Java Development Kit (JDK) or Java Runtime Environment (JRE) must be installed.
Downloading TOMCAT#
Go to http://tomcat.apache.org/download-70.cgi site and download the recently released TOMCAT binary file (apache-tomcat-7.0.46.tar.gz).

Installing TOMCAT#
Move the downloaded compressed file to FTP. (tomcat installation account)
Extract the uploaded compressed file to the appropriate directory. (tar xvzf apache-tomcat-7.0.56.tar.gz).
Because it is a binary, the installation is finished by extracting it.
[tomcat@dev ~]$ tar xvzf apache-tomcat-7.0.56.tar.gz
apache-tomcat-7.0.56/bin/catalina.sh
apache-tomcat-7.0.56/bin/configtest.sh
apache-tomcat-7.0.56/bin/daemon.sh
apache-tomcat-7.0.56/bin/digest.sh
apache-tomcat-7.0.56/bin/setclasspath.sh
apache-tomcat-7.0.56/bin/shutdown.sh
apache-tomcat-7.0.56/bin/startup.sh
apache-tomcat-7.0.56/bin/tool-wrapper.sh
apache-tomcat-7.0.56/bin/version.sh
apache-tomcat-7.0.56/conf/
.
.
.
apache-tomcat-7.0.56/webapps/manager/images/tomcat.gif
apache-tomcat-7.0.56/webapps/manager/images/update.gif
apache-tomcat-7.0.56/webapps/manager/images/void.gif
apache-tomcat-7.0.56/webapps/manager/index.jsp
apache-tomcat-7.0.56/webapps/manager/status.xsd
apache-tomcat-7.0.56/webapps/manager/xform.xsl
[tomcat@dev ~]$ mv apache-tomcat-7.0.56 /app/was/tomcat7
<Example of tomcat installation>
Setting environment variables#
Set the following environment variables.
-
CATALINA_HOME: Specify the directory where TOMCAT is installed.
-
JAVA_HOME or JRE_HOME: Specify the directory where JDK or JRE is installed.
-
PATH: Add the $CATALINA_HOME/bin directory (the path of the bin directory under the TOMCAT installation directory set in step 1) to the PATH.
[tomcat@dev ~]$ vi .bash_profile
export CATALINA_HOME=/app/was/tomcat7
export JAVA_HOME=/app/java/jdk1.6
export PATH=$CATALINA_HOME/bin:$JAVA_HOME/bin:$PATH
[tomcat@dev ~]$ . .bash_profile
<Example of Linux configuration>
Running TOMCAT#
Execute the following command to start the TOMCAT.
$ catalina.sh start (windows : catalina start)
[tomcat@dev ~]$ catalina.sh start
Using CATALINA_BASE: /app/was/tomcat7
Using CATALINA_HOME: /app/was/tomcat7
Using CATALINA_TMPDIR: /app/was/tomcat7/temp
Using JRE_HOME: /app/java/jdk1.6
Using CLASSPATH: /app/was/tomcat7/bin/bootstrap.jar:/app/was/tomcat7/bin/tomcat-juli.jar
Tomcat started.
[tomcat@dev ~]$
Shutting TOMCAT down#
Execute the following command to shutdown TOMCAT.
$ catalina.sh stop (windows : catalina stop)
[tomcat@dev ~]$ catalina.sh stop
Using CATALINA_BASE: /app/was/tomcat7
Using CATALINA_HOME: /app/was/tomcat7
Using CATALINA_TMPDIR: /app/was/tomcat7/temp
Using JRE_HOME: /app/java/jdk1.6
Using CLASSPATH: /app/was/tomcat7/bin/bootstrap.jar:/app/was/tomcat7/bin/tomcat-juli.jar
[tomcat@dev ~]$
JDBC Driver Configuration#
In the TOMCAT, the Altibase JDBC driver must be placed in an appropriate location to integrate with Altibase.
How to get the Altibase JDBC driver file#
The JDBC driver provided by Altibase is Altibase.jar. This file is located in the $ALTIBASE_HOME/lib directory of the server where Altibase is installed.
Starting from Altibase 5 or later, Altibase.jar and Altibase5.jar files exist in the $ALTIBASE_HOME/lib directory. Altibase.jar is a JDBC driver file, and Altibase5.jar is used when integrating Altibase 5 and lower. Therefore, in order to integrate with one Altibase DB or multiple Altibase DBs of the same version, $ALTIBASE_HOME/lib/Altibase.jar file can be used.
How to check the Altibase JDBC driver version#
To check the Altibase JDBC driver version, execute the following command.
[altibase@dev lib]$ java -jar Altibase.jar
JDBC Driver Info : Altibase Ver = 6.3.1.2.1 for JavaVM v1.4, CMP:7.1.1, Aug 18 2014 15:36:32
In order to check whether the Altibase DB server and the Altibase JDBC Driver that are to be integrated are compatible, checking the Altibase DB server version is required. In this case, if the cm protocol version of the Altibase DB server and the CMP of the Altibase JDBC Driver is the same, they are compatible.
[altibase@dev lib]$ altibase -v
version 6.3.1.2.1 X86_64_LINUX_redhat_Enterprise_ES4-64bit-6.3.1.2.1-release-GCC3.4.6
(x86_64-unknown-linux-gnu) Aug 18 2014 15:45:00, binary db version 6.2.1,
meta version 6.3.1, cm protocol version 7.1.1, replication protocol version 7.4.1
As the version is upgraded, there is a possibility that a bug related to JDBC has been fixed. Generally, it is recommended to match the Altibase DB server version with the Altibase JDBC driver version or use the latest Altibase JDBC driver file.
Location of JDBC driver file in TOMCAT#
In order to integrate Altibase and TOMCAT, the Altibase JDBC driver (Altibase.jar) should be located in an appropriate place so that it can be recognized automatically by TOMCAT.
-
Add Altibase.jar to CLASSPATH.
[tomcat@dev ~]$ cd $CATALINA_HOME/bin [tomcat@dev bin]$ vi catalina.sh CLASSPATH=/app/db/ALTIBASE/lib/Altibase.jar [tomcat@dev bin]$ catalina.sh stop Using CATALINA_BASE: /app/was/tomcat7 Using CATALINA_HOME: /app/was/tomcat7 Using CATALINA_TMPDIR: /app/was/tomcat7/temp Using JRE_HOME: /app/java/jdk1.6 Using CLASSPATH: /app/db/ALTIBASE/lib/Altibase.jar: /app/was/tomcat7/bin/bootstrap.jar:/app/was/tomcat7/bin/tomcat-juli.jar [tomcat@dev bin]$ catalina.sh start Using CATALINA_BASE: /app/was/tomcat7 Using CATALINA_HOME: /app/was/tomcat7 Using CATALINA_TMPDIR: /app/was/tomcat7/temp Using JRE_HOME: /app/java/jdk1.6 Using CLASSPATH: /app/db/ALTIBASE/lib/Altibase.jar: /app/was/tomcat7/bin/bootstrap.jar:/app/was/tomcat7/bin/tomcat-juli.jar Tomcat started. -
Altibase.jar is located in the $CATALINA_HOME/lib directory.
[tomcat@dev ~]$cd $CATALINA_HOME/lib [tomcat@dev lib]$ cp /app/db/ALTIBASE/lib/Altibase.jar ./ [tomcat@dev lib]$
Integrating Altibase and TOMCAT#
This chapter describes how to integrate Altibase and TOMCAT.
There are two methods to integrate: using DBCP (regular JDBC) or using Altibase ConnectionPool.
JNDI DataSource Integration#
To configure JNDI DataSource, write the following in $CATALINA_HOME/conf/context.xml.
$CATALINA_HOME/conf/context.xml
<context>
<Resource name="jdbc/Altibase" auth="Container"
type="javax.sql.DataSource"
driverClassName="Altibase.jdbc.driver.AltibaseDriver"
url="jdbc:Altibase://127.0.0.1:20300/mydb"
username="sys" password="manager"
maxActive="3" maxIdle="2" initialSize="1"
defaultAutoCommit="false"
removeAbandoned="true" logAbandoned="true"
removeAbandonedTimeout="60"
validationQuery="select 1 from dual"/>
</context>
It can be used on the web by adding the following contents to the web application home/WEB-INF/web.xml.
Web application home/WEB-INF/web.xml
<resource-ref>
<description>DB Connection</description>
<res-ref-name>jdbc/Altibase</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
<Resource>
The properties defined in the tag are as follows.
| driverClassName | Altibase JDBC driver class Name |
|---|---|
| url | The connection string information for connecting with Altibase. Enters jdbc:Altibase://IP:port_no/db_name" |
| Username | The database account |
| Password | The database password |
| maxActive | The maximum number of connections, 0 is unlimited. The default is 8. |
| initialSize | The initial size of connections. The default is 0. |
| maxIdle | The maximum number of connections that wait in the pool. The default is 8. |
| minIdle | The minimum number of connections that wait in the pool. The default is 0. |
| maxWait | The maximum connection attempt time (unit: millisec) -1 waits indefinitely. The default: infinite waiting. |
| validationQuery |
The SQL statement used to check the validation of connection Must be specified as a select statement that returns at least one row ex) select 1 from dual |
| defaultAutoCommit | Sets autocommit mode. The default: true. |
| defaultTransactionIsolation |
Sets Transaction Isolation level. The values of REPEATABLE_READ, SERIALIZABLE, and the default can be set, and the default follows the default value of the DB server. The isolation level of Altibase is READ COMMITTED by default. |
| removeAbandoned |
Determines the removal function for the abandoned connection. The default is false. When the connection is removed, the number of connections exceeds the value set for maxActive and is requested for connection. The connection can be assigned when maxActive is not reached, abandoned connection removal does not occur. |
| removeAbandonedTimeout | Sets the time for removal of abandoned timeout. The default is 300. |
| logAbandoned | Determines whether to abandon stack information in the log when removing abandoned connections. The default is false. |
In the program, the connection obtained with JNDI Datasource as follows.
In this case, java:/comp/env is a prefix used when looking up JNDI.
Context envContext = (Context)new InitialContext().lookup("java:/comp/env");
DataSource ds = (DataSource)envContext.lookup("jdbc/Altibase");
Connection conn = ds.getConnection();
Or
Context initCtx = new InitialContext();
DataSource ds = (DataSource)initCtx.lookup("java:comp/env/jdbc/Altibase");
Connection conn = ds.getConnection();
The following is a jsp example program that integrates with Altibase using the JNDI Datasource set above.
<%@ page import="java.sql.*, javax.naming.*, javax.sql.*"%>
<%
Context initCtx = new InitialContext();
DataSource ds = (DataSource)initCtx.lookup("java:comp/env/jdbc/Altibase");
Connection conn = ds.getConnection();
Statement stmt = conn.createStatement();
String query = "select to_char(sysdate,'yyyy/mm/dd hh24:mi:ss') from dual";
ResultSet rs = stmt.executeQuery(query);
if(rs.next()) {
out.println(rs.getString(1));
}
rs.close();
stmt.close();
conn.close();
%>
Integration with general JDBC method#
- Load the JDBC driver.
- Get the Connection object.
- Get the Statement object.
- Execute the SQL statement and place it in the ResultSet.
- Close all related objects after the operation is completed.
The following is a jsp example program that integrates with Altibase using the general JDBC method.
<%@page import="java.sql.ResultSet"%>
<%@page import="java.sql.Statement"%>
<%@page import="java.sql.DriverManager"%>
<%@page import="java.sql.Connection"%>
<%@page import="java.util.Properties"%>
<%
Class.forName("Altibase.jdbc.driver.AltibaseDriver");
Properties prop = new Properties();
prop.put("user", "sys");
prop.put("password", "manager");
String url = "jdbc:Altibase://192.168.56.110:20300/mydb";
String sql = "SELECT TO_CHAR(SYSDATE,'YYYY-MM-DD HH24:MI:SS') FROM DUAL";
Connection conn = null;
Statement stmt= null;
ResultSet rs = null;
try {
conn = DriverManager.getConnection(url, prop);
stmt = conn.createStatement();
rs = stmt.executeQuery(sql);
while(rs.next()) {
out.println(rs.getString(1));
}
}catch(Exception se) {
out.println(se.getMessage());
} finally {
rs.close();
stmt.close();
conn.close();
}
%>
Fail-Over Configuration#
This chapter describes how to integrate with TOMCAT using the FailOver function provided by Altibase.
FailOver Configuration#
TOMCAT does provide a FailOver function. However, because the FailOver function is provided starting from Altibase 5.3.3, FailOver can be implemented by using the Altibase FailOver function. How to use is as follows.
1. When specifying a JNDI DataSource in the context.xml file, specify the FailOver related properties in the Connection URL part.
<context>
<Resource name="jdbc/Altibase" auth="Container" type="javax.sql.DataSource"
driverClassName="Altibase.jdbc.driver.AltibaseDriver"
maxActive="100" maxIdle="-1" maxWait="-1"
username="sys" password="manager"
url="jdbc:Altibase://192.168.6.224:21129/mydb?
AlternateServers=(192.168.1.35:21129)&
ConnectionRetryCount=3&
ConnectionRetryDelay=3&
SessionFailOver=on&
LoadBalance=off"
validationQuery="SELECT 1 FROM DUAL" testOnBorrow="true"
removeAbandoned="true" removeAbandonedTimeout="60"
logAbandoned="true" />
</context>
- Refer to the FailOver/server.xml file
FailOver related properties are as follows. For more detailed information, please refer to the Replication Manual.
| Item | Description |
|---|---|
| AlternateServer | Indicates the alternate servers to be connected when a failure occurs (IP Address1:Port1, IP Address2:Port2,...). |
| ConnectionRetryCount | The number of tries of connection attempts when an alternative server connection fails. |
| ConnectionRetryDelay | Time to wait before attempting to connect when the alternative server connection fails (in seconds) |
| LoadBalance |
When set to on, random selection is made including default server and alternate servers when the first connection is attempted. If set to off, it connects to the default server when it tries to connect for the first time, and if it fails, it connects to the server described by AlternateServer. |
| SessionFailOver |
Indicates whether to perform STF (Service Time Fail-Over). on: STF, off: CTF The CTF (Connection Time Fail-Over) recognizes a failure at the time of DBMS connection and connects to the DBMS of another available node instead of the DBMS where the failure occurred and proceeds with the service. STF (Service Time Fail-Over) means that a failure occurs during service by successfully connecting to the DBMS, accessing the DBMS of another available node to restore the properties of the session, and then performing the task logic of the user application again. That is, it is the case that it is necessary to perform the operation performed in the DBMS where the failure occurred once again. |
● For the implementation method of CTF and STF, please refer to the FailOver technical document.
Considerations when integrating TOMCAT#
This chapter describes considerations when integrating TOMCAT.
JDK environment when using TOMCAT#
When processing the preparestatement using DBCP, it is recommended to use in JDK (JRE) 1.6 or later environment to change testOnBorrow (default: true) poolPrepareStatements (default: false) setting to improve performance.
Symptoms of the problem
Tomcat log (version 6)
--- Check the statement (query failed).
--- Cause: java.sql.SQLException: [0]:Failure to find statement; nested exception is com.ibatis.common.jdbc.exception.NestedSQLException:
--- The error occurred in maps/CommonSqlMap.xml.
--- The error occurred while applying a parameter map.
--- Check the Common.getIservSp-InlineParameterMap.
--- Check the statement (query failed).
--- Cause: java.sql.SQLException: [0]:Failure to find statement
If it is normal,
Tomcat log (version 6)
[0001][14:14:31 386][ 2][ 0] GET-CONNECTION[org.apache.tomcat.dbcp.dbcp.BasicDataSource.getConnection] [1 ms]
How to check
After removing the comment at the bottom of the contents of the $CATALINA_HOME/conf/server.xml file, restart Tomcat and check $CATALINA_HOME/logs/tomcat.log.
Before the change>
<!--
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="common" resolveHosts="false"/>
-->
After the change>
<Valve className="org.apache.catalina.valves.AccessLogValve"
directory="logs" prefix="localhost_access_log." suffix=".txt"
pattern="%a %b %t %s %D %r " resolveHosts="false"/>
Reference: http://tomcat.apache.org/tomcat-5.5-doc/config/valve.html
Recommended Tomcat settings
| Item | Environment 1 | Environment 2 | Environment 3 |
|---|---|---|---|
| JDK Ver | 1.5 | 1.6 | 1.6 |
| Tomcat Ver | 6 (dbcp ver 1.3) | 6 (dbcp ver 1.3) | 7 (dbcp ver 1.4) |
| testOnBorrow | Only TRUE recommended (Default) | TRUE/FALSE | TRUE/FALSE |
| poolPrepareStatements | Only FALSE recommended (Default) | TRUE/FALSE | TRUE/FALSE |
| Result |
testOnBorrow=False, poolpreparestatement=true Not recommended for use. Upgrade to JRE or JDK1.6 recommended |
Recommended | Recommended |
- testOnBorrow
+ When getting a connection from the connection pool, the connection is validated
+ The default value is false, and the default value is generally used. If set to true, validationQuery is executed every time, so a slight performance decrease is expected. - poolpreparestatement
+ Statement pooling is maintained for each connection in DBCP, so the application server (App) keeps the information compiled for the query. After that, it is possible to improve performance by repeating only the execute step without preparing the same query
Return of used resource#
Connection, Statement, and ResultSet allocated by the program must be explicitly closed after use. If it is not closed, resources are continuously allocated during the life cycle of the variable that declared the above resource, which results in unnecessary resource consumption.
If the connection is not closed, the connection will not be returned to the pool, so it will be unable to use it elsewhere.
Statement information is allocated and remained in memory not only on the application but also on the DB server while the session is maintained. Therefore, if the statement and the connection are not closed, this could be a problem for unnecessary resources are continuously allocated in the application, but the Query_Prepare memory area of the DB server also increases.
If the above resources are not explicitly closed, they are allocated in memory during the life cycle of the variable that declares the resource. If the life cycle ends, the resource is no longer referenced, so the JVM (Java Virtual Machine) and GC (Garbage Collector) will later release the resource. However, GC is generally the lowest priority thread. Therefore, it is difficult to predict when the GC releases the resource. In other words, it can not be released immediately because the life cycle of the variable is no longer referenced in the application, and the DB server keeps the information about the resource unless the GC releases it.
Therefore, it is recommended to close the used resource explicitly.
Remove abandoned connection#
There is one problem when processing a connection using DBCP, which means close ResultSet, Statement, and Connection must be explicitly closed in the web application. If the web application fails to close these resources, the resources cannot be reused later. This situation is called a connection pool leak, and if the connection pool leak persists, all available connections will eventually disappear. To prevent this problem, DBCP provides a method for recovering and logging a connection that has been abandoned due to a problem. The following property can be set.
removeAbandoned="true"
Errors when integrating TOMCAT#
This chapter describes the contents of errors when integrating Altibase and TOMCAT.
No suitable driver#
java.sql.SQLException: No suitable driver error occurs when the part corresponding to the Altibase of connection URL information is incorrectly entered.
url="jdbc:mysql://127.0.0.1:20300/mydb"
An error occurs because the jdbc:Altibase part is incorrectly set as the jdbc:mysql part.
Communication link failure#
java.sql.SQLException: Communication link failure error occurs in the following situations:
-
When the Altibase DB server is not running
-
When the Altibase JDBC driver file is different from the version of the Altibase DB server.
ex) The version of the Altibase DB server is 5.3.1, but when using the 5.1.1 version of the Altibase JDBC driver file -
When the connection URL information is set incorrectly
3-1. When the IP is set incorrectly
3-2. When the PORT_NO is set incorrectlyex) When the IP address of the Altibase DB server is 10.10.10.10 and PORT_NO is 20300, but the IP address is set to 10.10.10.1 or PORT_NO is set to 20301.
url="jdbc:Altibase://10.10.10.1:20301/mydb"
Others#
Occasionally, when a DataSource is specified in the context.xml file of a web application, it may be possible to encounter a client unable to establish a connection error or an error that the driver class is null even though the connection URL part is correct. In this case, delete the web application name.xml file in the $CATALINA_HOME/conf/catalina directory. Occasionally, even though the context.xml file of a web application has been changed, an error occurs because the file is not reloading.