Configuring an
Application Server
w/ Ingres
Bruce Lunsford
Developer, Ingres Connectivity
11
What is an Application Server?
• A server computer or software dedicated to
running certain software applications.
• As software, it provides common services to the
applications
• Benefits: reliability, performance, security
• Now often synonymous with Sun J2EE platform
• (Red Hat) JBoss, BEA Weblogic, IBM WebSphere, Oracle
Application Server 10g, Sun Java System Application
Server, JOnAS, Apache Tomcat, etc
2
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
What is an Application Server?
• Non J2EE App Servers
• OpenROAD Application Server
• Zope – Python
• IIS - .Net
• CICS - mainframe
• Scope of this presentation is J2EE App Server
configuration for Ingres
• NOTE that Ingres does not have its own J2EE App Server
• Use whichever one you want
3
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Why use Ingres with an App Server?
• Access relational data in Ingres from
applications running in App Server
• Most common usage
• Focus of this presentation
• Use Ingres as underlying data store for App
Server itself
4
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ingres JDBC Driver
• JDBC driver is what all J2EE App Servers interface with
• Hence…JDBC Driver is what must be configured
• Documented in Ingres 2006 Connectivity Guide
• See “Chapter 10: Understanding JDBC Connectivity”
• Ingres Documentation
• No longer installed with Ingres
• Ingres 2006 doc downloadable from: http://
www.ingres.com/products/Prod_Download_Documents.html
• See “Getting Started Guide” prior to Ingres 2006
5
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
NOTE: Ingres 2006 = Ingres r3 = 9.0.4??!!
• All references in presentation to Ingres 2006
apply to Ingres r3 as well
• The internal release id for Ingres 2006 is 9.0.4.
• Will not refer to r3 or 9.0.4…only 2006
• Ingres 2006 was the Ingres Corporation
rebranded version of CA’s Ingres r3
• Essentially service pack 1
• Ingres r3 not considered a separate, ongoing release
6
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Common Configuration Items
• Ingres JDBC Driver file
• Ingres JDBC Driver class name
• URL (connection string)
• User id and password
• Only 4 items, the first 2 are “constant” and the
last one may not be needed … Simple, right!
7
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Common Configuration Items
App Server
Java App
File=iijdbc.jar
Class=com.ingres.jdbc
.IngresDriver
URL
JDBC Driver
User/pwd
Ingres
Database
8
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ingres JDBC Driver File
•
iijdbc.jar for Ingres 2006
•
edbc.jar for Ingres 2.5 + 2.6 and EDBC 1.1
•
•
Also included in Ingres 2006 for backward compatibility
Distributed with Ingres, not separate
•
Additional “standalone” distribution in future (possibly)
•
Always installed during Ingres installation
•
Installed into Ingres lib directory
•
See %II_SYSTEM%\ingres\lib (Windows) or $II_SYSTEM/ingres/lib
(Linux/Unix)
• May be copied anywhere…not dependent on Ingres libs
9
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ingres JDBC Driver Class Name
•
•
•
“com.ingres.jdbc.IngresInterface” for Ingres 2006
•
iijdbc.jar driver file
•
ca.ingres.jdbc.IngresInterface left in (for now) for backward compatibility
to Ingres r3
“ca.edbc.jdbc[x].EdbcInterface” for Ingres 2.5+2.6 and EDBC 1.1
•
edbc.jar driver file
•
“edbc/Edbc” versus “ingres/Ingres” in name
•
An “x” represents JDBC extensions API interfaces (javax.sql.*) for J2EE
compliance
Constant depending on Ingres driver file being used
•
10
(variable “Interface” portion depends on usage)
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ingres JDBC Driver Class Name
• Interface values:
• Driver – JDBC driver
• Used in Java applications not using a datasource
• Typically used in standalone Java applications
• DataSource – JDBC DataSource
• CPDataSource – JDBC ConnectionPoolDataSource
• XADataSource – JDBC XADataSource
• Examples for Ingres 2006 (iijdbc.jar):
• “com.ingres.jdbc.IngresDriver”
• “com.ingres.jdbc.IngresDataSource”
11
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL (Connection String)
• Format is:
• “jdbc:ingres://” + variable portion for Ingres 2006
• “jdbc:edbc://” + variable portion for pre-Ingres 2006 +
EDBC
• Actually dependent on the jar file (iijdbc.jar or
edbc.jar), not the Ingres release
• Variable portion format:
• host:port/db[;attr=value…]
12
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL (Connection String)
• jdbc:ingres://host:port/db[;attr=value…]
• Host
• Network name or IP address of machine running Ingres DAS
• If local (same machine), use “localhost” or “127.0.0.1”
13
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL (Connection String)
•
jdbc:ingres://host:port/db[;attr=value…]
•
Port
Network port used by DAS
• Default is Ingres installation id (default II) followed by “7”
•
•
•
For example, II7
Mnemonic port converted internally by Ingres to numeric port
•
Can specify numeric port (II7 => 21071)
• Ingres startup displays the values in the errlog.log:
•
•
DAS port configurable in Ingres Configuration Manager (CBF or VCBF)
•
•
14
host::[UU\DASVR\d74 …] date time E_GC4803_NTWK_OPEN Network open
complete for protocol TCP_IP, port UU7 (27311).
Data Access Server -> Protocols -> tcp_ip
Port must be unique on that machine
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL (Connection String)
•
jdbc:ingres://host:port/db[;attr=value…]
•
Db
•
Target Database Specification
• Any valid Ingres database designation
• including vnode and server class
• [vnode::]dbname[/server_class]
• vnode = virtual node defined in Ingres Networking utility or dynamic
• dbname = database name
• server_class = default is “ingres”, but can be any valid Ingres server type
• “d” or “star” for Distributed Ingres (Star), “oracle” for EA to Oracle, etc
• Examples: “mydb”, “bigsvr::mydb”, “bigsvr::mystar/d”,
“@hostA,tcp_ip,JJ[myid,mypasswd]::mydb”
15
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL
hostA
App Server
Java App
jdbc:ingres:
//hostA:II7
/TradeDB
File=iijdbc.jar
Class=com.ingres.jdbc
.IngresDriver
JDBC Driver
URL
User/pwd
Ingres
Installation II
iigcd
DAS
TradeDB
Database
16
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
URL (Connection String)
• jdbc:ingres://host:port/db[;attr=value…]
• Attr=value
• Optional
• Attribute name and value pair
• Multiple pairs separated by semicolons
• Attributes represent Ingres driver properties
• See Ingres Connectivity Guide for list of properties and
attributes
• Example: “;cursor=readonly;auto=multi”
• These 2 are frequently recommended
17
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Attributes/Properties
• May also specify as properties
• Default properties file is iijdbc.properties
• Must reside in location loadable by class loader for driver
• Properties supersede attributes
• Property for each attribute, but differently named
• Attributes (in URL) may use attribute or property name
18
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Data Source (DS) properties
• Data Source is collection of information specifying
target database
• Redundant with info in URL
• Associated with getter/setter datasource methods
• Uppercase the first character of property name
• Required DS properties:
• serverName, portName or portNumber, databaseName
19
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Attributes / properties – frequently used
• cursor=readonly
• Equivalent property is cursor_mode
• Generally improves performance
• More block-fetching of data
• Less database locking
• Default in Ingres 2006 after build 105 (Ingres driver version 2.6)
• Suggest specifying it whether default or not
• DBMS default is “updateable” cursors, but JDBC seems to
expect “readonly”
• No real downside – does not restrict or prevent updates
20
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Attributes / properties – frequently used
• auto=multi
• Equivalent property is autocommit_mode
• Ingres DBMS only allows one cursor (select) to be open when
autocommit is on
• Some other databases allow multiple, which apps may expect
• Setting this option causes Ingres driver to simulate autocommit
and allow multiple open cursors during autocommit
• Needed if app gets error such as: “No MST in progress, trying to
open additional cursor”
21
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Attributes / properties – frequently used
• TZ=timezone;DATE_FMT=dateformat
• Equivalent properties are timezone and date_format, respectively
• Equivalent to Ingres environment variables:
• II_TIMEZONE_NAME
• II_DATE_FORMAT
• Not used directly by the driver but passed to the DBMS
• Not available in edbc.jar
• A number of other familiar Ingres variable settings are also now
available in iijdbc.jar
22
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Debugging
• Connection errors … what now!
• What’s the error message? Does it provide a clue?
• Ensure that Ingres is running, including the DAS
• Verify URL settings
• Check error logs in Ingres (client and server, if
applicable)
• Trace the driver or DAS
23
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Tracing the JDBC Driver
•
Helpful to diagnose problems, verify settings and/or application
JDBC calls
•
Set the following properties:
•
•
•
•
•
•
24
ingres.jdbc.trace.log=c:\\Temp\\logfilename (Windows) or
/Temp/logfilename (Unix/Linux)
ingres.jdbc.trace.drv=5
ingres.jdbc.trace.msg=5
ingres.jdbc.trace.timestamp=TRUE
The trace level goes from 0-5 generally with 5 the highest
Other trace options also available: ds, msg.nl, msg.tl
•
Recycle app and/or app server to pick up trace settings
•
Can also be set programmatically: setTraceLog() &
setTraceLevel()
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Ingres JDBC Driver History
Ingres
Release
JDBC
Driver
Driver
Version
JDBC
API Level
Ingres
Server
2.0
2.5
2.6
2006
none
edbc.jar
edbc.jar
iijdbc.jar
N/A
0.x
1.x
2.x
N/A
1.0
2.0
3.0
N/A
JDBC/iijdbc
JDBC/iijdbc
DAS/iigcd
NOTE 1: Need Ingres 2.6 or later for J2EE app servers
NOTE 2: edbc.jar + JDBC server/iijdbc included with Ingres 2006
for backward compatibility … not to confuse you!
NOTE 3: May use edbc.jar with DAS/iigcd
25
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Application Server Example Configs
• Demonstrate some popular App Servers
• Will not cover installation
• Add Ingres driver to App Server CLASSPATH
• Set up a DSN (in JNDI).
• Deploy the application
• Usually multiple ways to accomplish same task –
will only cover one.
26
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server
• Very popular open source J2EE Application Server
• Recently acquired by Red Hat
• Latest GA release is 4.0.4
• Download and install JBoss AS
• Copy Ingres driver (iijdbc.jar or edbc.jar) to JBoss
server\default\lib directory.
• Create ingres-ds.xml in JBoss
server\default\deploy to set up DSNs
27
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Add DSNs
ingres-ds.xml in JBoss server\default\deploy
<?xml version="1.0" encoding="UTF-8" ?>
<datasources>
<xa-datasource>
<jndi-name>IngresDS</jndi-name>
<xa-datasource-class>com.ingres.jdbc.IngresXADataSource</xa-datasource-class>
<xa-datasource-property name="DataSourceName">Ingres</xa-datasource-property>
<xa-datasource-property name="ServerName">lunbr01-m1</xa-datasource-property>
<xa-datasource-property name="PortName">UU7</xa-datasource-property>
<xa-datasource-property name="DatabaseName">testdb</xa-datasource-property>
<xa-datasource-property name="User">myuser</xa-datasource-property>
<xa-datasource-property name="Password">mypwd</xa-datasource-property>
<transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
28
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Add DSNs
(continued)
<!-- <isSameRM-override-value>false</isSameRM-override-value> <check-validconnection-sql>select count(*) from test1</check-valid-connection-sql> <new-connectionsql>set lockmode where level=row</new-connection-sql> <trackstatements>true</track-statements> -->
<track-connection-by-tx>true</track-connection-by-tx>
<min-pool-size>5</min-pool-size>
<max-pool-size>10</max-pool-size>
<blocking-timeout-millis>5000</blocking-timeout-millis>
<idle-timeout-minutes>15</idle-timeout-minutes>
</xa-datasource>
</datasources>
29
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server
• Edit run.bat in JBoss bin
• set INGRES_JAR=c:\jboss-4.0.x\server\default\lib\iijdbc.jar
• Add INGRES_JAR to
JBOSS_CLASSPATH
• set JBOSS_CLASSPATH=%JAVAC_JAR%;%RUNJAR%;%INGRES_JAR%
• Create directory called testIngresDS.war in
JBoss server\default\deploy directory
• Copy application (JSP for example) to
testIngresDS.war
30
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Run
•
To start JBoss
• cd JBoss bin directory
• Execute run.bat
• Should see message in JBoss console similar to:
• … INFO [WrapperDataSourceService] Bound connection factory
for resource adapter for ConnectionManager
'jboss.jca:name=IngresDS,service=DataSourceBinding to JNDI
name 'java:IngresDS‘
• … INFO [TomcatDeployer] deploy, ctxPath=/testIngresDS,
warUrl=file:/C:/jboss-.0.0/server/default/deploy/testIngresDS.war/
• And No errors!
31
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Run
• See info about IngresDS on the JBOSS MBean
view:
• URL:http://localhost:8080/jmx-console/
• Navigate to jboss.jca section.
• To view the JSP application, navigate to
jboss.web section.
• To run a simple JSP application (xa.jsp), use the
following URL:
• http://localhost:8080/testIngresDS/xa.jsp.
32
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Sample App
Extract of xa.jsp sample application
<%@ page language="java" contentType="text/html" import="java.sql.*"
import="javax.naming.*" import="javax.sql.*"%>
<%
Connection conn = null;
Statement stmt = null;
ResultSet rs = null;
javax.sql.DataSource ds = null;
...
try {
Context initCtx = new InitialContext();
if( initCtx != null )
ds = (javax.sql.DataSource) initCtx.lookup("java:/IngresDS");
}
33
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
JBoss Application Server – Sample App
Extract of xa.jsp sample application (continued)
catch(Exception e) {
System.out.println("DataSource Context not found:" + e.toString());
throw new UnavailableException(this, "DataSource Context not found");
}
try {
if( ds != null )
{
conn = ds.getConnection();
if( conn != null )
...
34
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
•
Popular commercial J2EE Application Server
•
Ingres partner
•
Latest GA release is 9.1
•
•
Release 8.1 still common
Download and install BEA WebLogic Server (WLS)
• Set up Weblogic Server’s classpath
WEBLOGIC_CLASSPATH to point to Ingres JDBC driver’s
jar file
• Edit commEnv.cmd file in %WL_HOME%/common/bin directory
of WLS installation
35
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Bring up WLS
• Start -> Programs -> BEA WebLogic Platform 8.1 -> WebLogic
Workshop 8.1
• Workshop Tools -> WebLogic Server -> Start WebLogic Server
• BEA WebLogic Workshop – not BEA Workshop
Studio!
• Example is for WLS 8.1…caveats for 9.1 afterwards
36
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
Start WLS
NOTE: Server Stopped
37
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Administer via WLS Console
• Workshop Tools -> WebLogic Server -> WebLogic Console
• Default user/password = weblogic/weblogic
• Define connection pool
• Define data source
38
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
Start WLS Console
39
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
WLS Console
40
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Configure an Ingres 2006 connection pool
• Expand workshop -> Services -> JDBC
• Right click on Connection Pools
• Choose “Configure a new JDBCConnectionPool”
• Database Type & Driver = Other
41
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
Create an Ingres 2006 Connection Pool
42
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
43
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Configure various connection pool options
• Initial Capacity: 1
• Maximum Capacity: 15
• Capacity Increment: 1
• Etc
• Defaults mostly OK
• May define Test Connection options w/ test query
• Select XA`options:
• Keep XA Connection Till Transaction Complete
• Need Transaction Context On Close
• XA End Only Once
44
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Configure various connection pool options (contd)
• Select XA options:
• Keep XA Connection Till Transaction Complete
• Need Transaction Context On Close
• XA End Only Once
• Keep Connection Open On Release
• Supports Local Transaction
45
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server
• Create an Ingres datasource
• Give it an internal name
• Specify JNDI name
• Link / set connection pool name
• Various options OK with default values
46
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
BEA WebLogic Server 9.1 NOTE
• WLS 9.1 has no “other” for database type
• BEA has patch available
• Will be fixed in 9.2
• Can manually add some JDBC tags to config.xml
• Will provide FAQ for specifics
47
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Connection Pooling Tips
• Use connection pooling in App Server
• Better performance (higher level)
• Many options
• Ingres DAS provides optional connection pooling
• Good for non-App Server environments
• Don’t specify both App Server + Ingres DAS
connection pooling
48
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.
Summary
• Ingres works with the various J2EE App Servers
• Key to configuration is JDBC configuration
• Ingres driver file
• Ingres driver class
• URL
• Ingres 2006 recommended
• Introduced support for JDBC 3.0 compliance
49
© 2005 Ingres Corporation (Ingres). All trademarks, trade names, services marks and logos referenced herein belong to their respective companies.