ZK/How-Tos/HowToSetupEclipseWtpAndXAMPPForZK

Introduction

To use Eclipse as IDE to develop web applications using the framework ZK, often database access is needed too. This HowTo shows the basic steps in creating an environment in which Eclipse runs together with ZK, XAMPP, MySQL, Tomcat and JDBC. Often occurring errors are described. The installation as described runs on Windows 2000 machine.

Downloads

The following software packages should be downloaded:

ZK: The ZK libraries (Homepage ZK);
Eclipse & WTP: The Eclipse IDE combined with the Web Tools Platform (WTP is also separately available as part of the Callisto Project) (Homepage Web Tools Platform);
XAMPP: An Apache distribution with MySQL, phpMyAdmin (Homepage XAMPP);
Tomcat: The Tomcat server/container (XAMPP Add-ons);
JDBC Connector: A converter of JDBC (Java Database Connectivity) calls to MySQL protocols (MySQL Connector/J 3.1.14, NOT 5.0.4).

Installation

How to setup Eclipse with ZK is discussed in How To Setup Eclipse Wtp For ZK.

Locations

The Apache distribution is installed in the ${XAMPP} folder. The Tomcat server in the ${XAMPP}/tomcat folder: ${TOMCAT}. The MySQL connector is placed in the ${TOMCAT}/common/lib folder. Eclipse automatically finds all the jars in this folder, so it is not necessary to add it manually as an External Jar to a project. The project in Eclipse runs in the ${APPL} folder (can be outside Tomcat container).

Binding together

Opposed to [1] the information about the connection to the database will be stored in the files: ${APPL}/META-INF/context.xml and ${APPL}/WEB-INF/web.xml. Eclipse adds option "Update root context for Web module MyProject" that uses this information when Run on Server [Alt+Shift eXecute, Run].

File content

In the ${APPL}/WEB-INF/web.xml should be added under the <web-app> key the following reference:

<!-- JDBC -->
  <resource-ref>
    <description>
      Resource reference to a factory for java.sql.Connection
      instances that may be used for talking to a particular
      database that is configured in the server.xml file.
    </description>
    <res-ref-name>jdbc/nicedatabasename</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>

And the ${APPL}/META-INF/context.xml should have the following content:

<Context path="/MyProject" docBase="MyProject" 
      debug="5" reloadable="true" crossContext="true">
    <Resource name="jdbc/nicedatabasename" 
      username="youknow" password="secretexceptifcalledsecret"
      url="jdbc:mysql://localhost:3306/actualdatabasename"
      auth="Container" defaultAutoCommit="false"
      driverClassName="com.mysql.jdbc.Driver" maxActive="20"
      timeBetweenEvictionRunsMillis="60000"
      type="javax.sql.DataSource"/>

Errors

It is possible that error after error pops up. These are often encountered errors. The errors are in a certain order. If an error about an empty JDBC driver pops up, it means that the reference to the resource is correctly found in the web.xml file. If the error about the character set pops up, the JDBC driver is found.

Not Bound in Context

An error about a wrong name:

javax.naming.NameNotFoundException: Name **** is not bound in this Context

This error occurs when <resource-ref> in web.xml is not equal to the resource name in context.xml.

Empty JDBC Driver

An error about an empty JDBC driver:

org.apache.tomcat.dbcp.dbcp.SQLNestedException: Cannot create JDBC driver of class '' 
for connect URL 'null'

This error has probably to do with the version of the Tomcat server that is used. The 5.5 version uses the syntax like described above. The 5.0 version likes the syntax with the ResourceParams elements:

  <Resource name="jdbc/nicedatabasename" auth="container" type="javax.sql.DataSource"/>
  <ResourceParams name="jdbc/nicedatabasename">
    <parameter>
      <name>driverClassName</name>
      <value>com.mysql.jdbc.Driver</value>
    </parameter>

    <parameter>
      <name>url</name>
      <value>jdbc:mysql://localhost:3306/actualdatabasename?autoReconnect=true</value>
    </parameter>
  </ResourceParams>

It can be the case that the Tomcat server has to be restarted.

Character Set

An error about the character set used:

java.sql.SQLException: Unknown initial character set index ’48’ received from server.
Initial client character set can be forced via the ‘characterEncoding’ property.

Probably, the error is in the MySQL Connector/J JDBC software version 5.0.4, downloaded from www.mysql.org. It is not an Eclipse or QuantumDB issue. If you downgrade to MySQL Connector/J JDBC software version 3.1.14, the issue is resolved.

Windows Hints

Start the MySQL server (as a service) - not with [Win+X] & "services.msc" but - with a shortcut that has as target:

%windir%\system32\net.exe start "MySQL Server"

"MySQL Server" is the name that the service has in "services.msc". The attributes "start" and "stop" are recognized. The Tomcat Server can be started from Eclipse itself, and does not need a shortcut.

Information regarding startup of the MySQL server incorporated in XAMPP is stored in ${XAMPP}/mysql/bin/my.cnf. In Windows can a *.cnf not be edited by default. Open a Command Shell box and edit by "edit my.cnf". The character set can be added or altered beneath the elements [mysqld] (the server), [mysql], [client]. The phpMyAdmin tool can be used to do such things with editboxes for the GUI-minded.

References

[1]. "Creating Web Applications with the Eclipse Web Tools Project", Eclipse Developer's Journal, by Boris Minkin.

[2]. "MySQL 5.0 Reference Manual".

[3]. "Develop ZK Applications with Eclipse", ZK Small Talks, by Andrew Ho