JBoss Integration Guide for Altibase#
Overview#
This guide describes how to install JBoss, configure its environment variables, and integrate it with Altibase. It is based on Altibase 6.5.1 and JBoss 6.1.0.Final.
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.
JBoss Installation#
This chapter describes how to install and start JBoss, how to set environment variables, how to bind IP addresses, and the JBoss directory structure.
Prerequisites#
JBoss is an application certified to the Java EE 6 standard, so JDK 1.6 or later must be installed to use JBoss.
JDK 1.7 was used in the test environment.
Basic Installation#
To install JBoss, download the package for the desired version from the JBoss website. (http://www.jboss.org/jbossas/downloads)
After downloading the package, extract it with a compression tool on Windows, or with the unzip command on Unix.
unzip jboss-6.1.0.GA.zip
… omitted …
inflating: jboss-6.1.0.GA/server/web/deployers/jboss-jca.deployer/jboss-jca-deployer.jar
inflating: jboss-6.1.0.GA/server/web/deployers/jbossweb.deployer/web.xml
inflating: jboss-6.1.0.GA/server/web/deployers/metadata-deployer-jboss-beans.xml
inflating: jboss-6.1.0.GA/server/web/deployers/security-deployer-jboss-beans.xml
#
In this document, the jboss-6.1.0.Final directory created by extracting the package is referred to as JBOSS_HOME. Extracting the package completes the JBoss installation; JBoss can be started once the JDK is configured.
Extracting the package creates a directory with the same name as the package, which contains all the files and directories for starting, stopping, and testing JBoss.
Setting the JDK on Windows#
On Windows, set the JDK using one of the following two methods.
- Add the JAVA_HOME variable to the system environment variables.

-
Add it to the JBoss startup script, JBOSS_HOME/bin/run.bat.
@echo off rem ------------------------------------------------------------------------- rem JBoss Bootstrap Script for Windows rem ------------------------------------------------------------------------- rem $Id: run.bat 111395 2011-05-18 07:45:07Z beve $ set JAVA_HOME=C:\Program Files\java\jdk1.7.0 ← Add the JDK path @if not "%ECHO%" == "" echo %ECHO% @if "%OS%" == "Windows_NT" setlocal if "%OS%" == "Windows_NT" ( set "DIRNAME=%~dp0%" ) else ( set DIRNAME=.\ ) … omitted …
Setting the JDK on Unix#
On Unix, set the JDK using one of the following methods.
- Add the JAVA_HOME variable to the system environment variables.
-
Add it to the JBoss startup script, JBOSS_HOME/bin/run.sh.
#!/bin/sh ### ====================================================================== ### ## ## ## JBoss Bootstrap Script ## ## ## ### ====================================================================== ### ### $Id: run.sh 111395 2011-05-18 07:45:07Z beve $ ### $ Extract the directory and the program name JAVA_HOME=/usr/jdk/jdk1.7.0 ← Add the JDK path … omitted …
JBoss Directory Structure#
Installing JBoss creates the following directories.

Starting JBoss#
After installing JBoss and configuring the JDK, you can start JBoss.
On Unix, start JBoss by running the JBOSS_HOME/bin/run.sh script; on Windows, run the JBOSS_HOME/bin/run.bat batch file.
## sh run.sh
… omitted …
16:44:55,672 INFO [xnio] XNIO Version 2.1.0.CR2
16:44:55,678 INFO [nio] XNIO NIO Implementation Version 2.1.0.CR2
16:44:55,858 INFO [remoting] JBoss Remoting version 3.1.0.Beta2
16:44:55,907 INFO [TomcatDeployment] deploy, ctxPath=/
16:44:55,960 INFO [HornetQServerImpl] trying to deploy queue jms.queue.ExpiryQueue
16:44:56,026 INFO [HornetQServerImpl] trying to deploy queue jms.queue.DLQ
16:44:56,039 INFO [service] Removing bootstrap log handlers
16:44:56,078 INFO [org.apache.coyote.http11.Http11Protocol] Starting Coyote HTTP/1.1 on http-127.0.0.1-8080
16:44:56,080 INFO [org.apache.coyote.ajp.AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
16:44:56,081 INFO [org.jboss.bootstrap.impl.base.server.AbstractServer] JBossAS [6.1.0.Final "Neo"] Started in 19s:637ms
When JBoss starts successfully, the last log message contains the word "Started". You can also verify that JBoss is running by accessing the web console (http://server_ip:port_number).
Log in to the Administration Console with the admin account (password: admin) to manage the running JBoss instance.

Stopping JBoss#
To stop JBoss, run the JBOSS_HOME/bin/shutdown.sh or shutdown.bat script.
## sh shutdown.sh –S ← When started on localhost
Shutdown message has been posted to the server.
Server shutdown may take a while - check logfiles for completion
#
Notes on Starting and Stopping JBoss#
Note the following when starting and stopping JBoss.
Error Caused by a Port Conflict at Startup#
The default port of JBoss is "8080".
If this port is already in use by another program, the following error occurs when JBoss starts, so the port must be changed.
DEPLOYMENTS IN ERROR:
Deployment "WebServer" is in error due to the following reason(s): LifecycleException: Protocol handler initialization failed: java.net.BindException: Address already in use /127.0.0.1:8080
To change the default JBoss port, modify the Connector port in the JBOSS_HOME/server/default/deploy/jbossweb.sar/server.xml file.
<Connector protocol="HTTP/1.1" port="8088" address="${jboss.bind.address}" redirectPort="${jboss.web.https.port}" />
Integrating Altibase with JBoss#
This chapter describes how to configure Altibase and JBoss to work together.
JDBC Driver#
JDBC is a standard interface that allows Java applications to connect to a database and execute SQL statements.
JDBC drivers are provided by each database vendor; Altibase provides its JDBC driver as the Altibase.jar file.
The JDBC driver is located in the $ALTIBASE_HOME/lib directory.
Configuring the JDBC Driver#
If the application implements its own connection pool, you can simply package the JDBC driver together with the application. However, to access a data source through JBoss JNDI,
the JDBC driver must be placed in a location accessible to all server configurations.
In JBoss, placing the JDBC driver (Altibase.jar) in the JBOSS_HOME/common/lib directory makes it accessible to all server configurations.
Because this directory is not reloaded dynamically, you must restart JBoss after placing the JDBC driver there.
Data Source Parameters#
The following are the data source parameters for integrating Altibase with JBoss, covering almost all settings available for a data source.
Review the definitions of the parameters listed below, then combine the ones you need in the data source file.
You can create the data source file directly with a text editor, name it in the form xx-ds.xml, and place it in the JBOSS_HOME/server/default/deploy directory.
| Parameter | Description |
|---|---|
| <jndi-name> |
|
| <connection-url> | Sets the URL of the DBMS to connect to |
| <driver-class> | Sets the JDBC driver used to connect to the DBMS |
| <user-name> | Sets the user |
| <password> | Sets the password |
| <new-connection-sql> | Specifies the SQL to execute when a connection is created |
| <check-valid-connection-sql> | Specifies the SQL to execute when a connection is obtained from the connection pool |
| <valid-connection-checker-class-name> | Checks whether a connection is valid before it is obtained from the connection pool |
| <exception-sorter-class-name> | Checks the DBMS error code and message when an error occurs |
| <track-statements> | Monitoring option that tracks Statements and ResultSets that are left unclosed |
| <prepared-statement-cache-size> | Number of PreparedStatements cached per connection for reuse in subsequent calls |
| <shared-prepared-statements> | Specifies whether PreparedStatements are cached; if the same statement is called multiple times in the same transaction, the cached Statement is returned. The default value is false. |
| <query-timeout> | Sets the SQL timeout value |
| <background-validation> | Option used to reduce the overhead of validating connections. The default value is false. |
| <idle-timeout-minutes> | Maximum time a connection can remain idle before it is closed. The default value is 15 minutes. |
| <background-validation-minutes> | Interval at which the ConnectionValidator runs. The default value is 10 minutes. |
| <min-pool-size> | Minimum number of connections in the connection pool |
| <max-pool-size> | Maximum number of connections in the connection pool |
| <transaction-isolation> | If the transaction isolation level is not specified, the DBMS default is used |
| <metadata> | The type-mapping defined in the standardjbosscmp-jdbc.xml file |
Data Source Configuration#
This section describes how to configure a data source for integrating Altibase with JBoss.
Local Transactions#
The following is the minimum data source configuration for integrating Altibase with JBoss. If additional settings are required, use the parameters described above as appropriate.
Save the file in the form "xx-ds.xml". JBoss automatically detects and binds the data source file without a restart.
<datasources>
<local-tx-datasource>
<jndi-name>AltiTest</jndi-name>
<connection-url>jdbc:Altibase://127.0.0.1:20300/mydb</connection-url>
<driver-class>Altibase.jdbc.driver.AltibaseDriver</driver-class>
<user-name>sys</user-name>
<password>manager</password>
<min-pool-size>10</min-pool-size>
<max-pool-size>100</max-pool-size>
<blocking-timeout-millis>5000</blocking-timeout-millis>
<idle-timeout-minutes>15</idle-timeout-minutes>
<metadata>
<type-mapping>Altibase</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>
Distributed Transactions#
The following is an example data source file for distributed transactions.
The JBOSS_HOME/docs/jca directory contains sample data source files for local and distributed transactions for each DBMS; refer to them when configuring your data source.
Save the file in the form "xx-xa-ds.xml".
<datasource>
<xa-datasource>
<jndi-name>AltibaseDS</jndi-name>
<track-connection-by-tx />
<isSameRM-override-value>false</isSameRM-override-value>
<xa-datasource-class>Altibase.jdbc.driver.ABXADataSource</xa-datasource-class>
<xa-datasource-property name="ServerName">127.0.0.1</xa-datasource-property>
<xa-datasource-property name="PortNumber">20300</xa-datasource-property>
<xa-datasource-property name="User">sys</xa-datasource-property>
<xa-datasource-property name="Password">manager</xa-datasource-property>
<metadata>
<type-mapping>Altibase</type-mapping>
</metadata>
<!--pooling parameters-->
<min-pool-size>5</min-pool-size>
<max-pool-size>250</max-pool-size>
<blocking-timeout-millis>5000</blocking-timeout-millis>
<idle-timeout-minutes>5</idle-timeout-minutes>
<check-valid-connection-sql>select * from system_.sys_database_</check-valid-connection-sql>
</xa-datasource>
</datasources>
Failover#
Failover is a feature that prevents service interruption caused by a DBMS failure: when the DBMS in use fails, the failure is detected and the connection is switched to another DBMS so that service can continue.
Failover can be configured either with the syntax provided by JBoss or with the syntax provided by Altibase.
The following is the failover syntax provided by JBoss.
Add the connection-url of the DBMS to fail over to, and specify the delimiter that separates the two URLs with <url-delimiter>.
With the JBoss syntax, only CTF (Connection Time Failover) is available.
The test procedure is the same as described above.
<datasources>
<local-tx-datasource>
<jndi-name>AltiTest</jndi-name>
<connection-url> jdbc:Altibase://127.0.0.1:20911/mydb,
jdbc:Altibase://192.168.1.76:20911/mydb</connection-url>
<url-delimiter>,</url-delimiter>
<driver-class>Altibase.jdbc.driver.AltibaseDriver</driver-class>
<user-name>sys</user-name>
<password>manager</password>
<min-pool-size>10</min-pool-size>
<max-pool-size>100</max-pool-size>
<blocking-timeout-millis>5000</blocking-timeout-millis>
<idle-timeout-minutes>15</idle-timeout-minutes>
<metadata>
<type-mapping>Altibase</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>
Because the Altibase failover feature is available only in Altibase 5.3.3 or later, use the JBoss syntax with earlier versions.
The following is failover using the syntax provided by Altibase. After modifying the data source file, shut down the DBMS at the first URL and run the test; you can confirm that the connection fails over to the DBMS at the second URL.
With the Altibase syntax, both CTF (Connection Time Failover) and STF (Session Time Failover) are available.
<datasources>
<local-tx-datasource>
<jndi-name>AltiTest</jndi-name>
<connection-url>jdbc:Altibase://127.0.0.1:20911/mydb?
AlternateServers=(192.168.1.76:20911)&ConnectionRetryCount=3&
ConnectionRetryDelay=3&LoadBalance=off&
SessionFailOver=off </connection-url>
<driver-class>Altibase.jdbc.driver.AltibaseDriver</driver-class>
<user-name>sys</user-name>
<password>manager</password>
<min-pool-size>10</min-pool-size>
<max-pool-size>100</max-pool-size>
<blocking-timeout-millis>5000</blocking-timeout-millis>
<idle-timeout-minutes>15</idle-timeout-minutes>
<metadata>
<type-mapping>Altibase</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>
Examples#
The previous chapter described how to integrate Altibase with JBoss. This chapter verifies the integration by connecting to Altibase and executing a query using the configuration above.
JSP Sample#
<%@ page import="javax.naming.*" %>
<%@ page import="java.sql.*" %>
<%@ page import="javax.sql.*" %>
<%
Connection con=null;
Statement st=null;
ResultSet rs=null;
try
{
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource)ctx.lookup("java:/AltiTest");
con=ds.getConnection();
st=con.createStatement();
rs=st.executeQuery("select * from dual");
while(rs.next())
{
out.println("Result :" + rs.getString(1)+"<br>");
}
}
catch(Exception e)
{
out.println("Error:" + e.getMessage());
e.printStackTrace();
}
finally
{
if(rs!=null)rs.close();
if(st!=null)st.close();
if(con!=null)con.close();
}
%>
How to Run#
There are two ways to test the integration of Altibase and JBoss:
create the JSP file to test inside an already deployed WAR, or create a WAR yourself, deploy it to JBoss, and then test it.
Using an Existing WAR#
The JBOSS_HOME/server/default/deploy directory contains WARs provided by JBoss by default. Create the sample JSP file in one of these WARs and test it.
In this document, the JSP file was created in the default ROOT.war for testing. (JBOSS_HOME\server\default\deploy\ROOT.war)
After creating the JSP file, enter the IP address and port number of the server running JBoss, followed by the JSP file name, in the browser address bar.
http://server_ip:port_number/jsp file name
e.g.) http://localhost/test.jsp

Creating a WAR#
This section describes how to test with a JSP file using the JBoss web console.
Deployment refers to all the operations of uploading and controlling module files on JBoss to start application services.
In this sample test, a WAR file is created from the sample above, then deployed to and run on the JBoss server.
The WAR file used in this sample test was created with Eclipse.
-
Launch Eclipse, select [File] → [New] → [Project], then select [Web] → "Dynamic Web Project" in the wizard and set the project name.

-
Once the project is created as shown below, create the sample above as a JSP file and add it under the "WebContent" directory, and add Altibase.jar under the "lib" directory.

-
After adding the JSP file and Altibase.jar, select [File] → [Export], select [Web] → "War file", and specify the output path to create the WAR.

-
Once the WAR file is created, click "Web Application" → "Add a new resource" in the JBoss web console and upload the WAR file.

-
When the WAR file is uploaded, it is deployed automatically and a message indicating a successful deployment is displayed. The deployed WAR file can also be found in the list.

-
After deployment is complete, open a web browser and enter the following URL to run it.
http://server_ip:port_number/WAR name/jsp file name
e.g.) http://localhost:8080/AltiTest/test.jsp
