2
Installing and Testing TopLink

This chapter includes the following information on installing TopLink:

• System Requirements

• Installing TopLink

• Third-party License Information

• Configuring TopLink for Your Development Environment

• Testing Your TopLink Installation

• General Troubleshooting

System Requirements

Your system must meet certain minimum requirements to ensure that TopLink runs smoothly.

Operating Systems Requirements

TopLink will run under any of the following operating systems:

• Windows 2000

• Windows NT 4.0 (service pack 6) or newer

• Any fully Java-compatible Unix operating system

Hardware Requirements

TopLink hardware requirements are quite low, and in fact, the hardware required to run both Java and most database applications far exceeds TopLink's requirements.

However, as a guideline, your system should include at least the following to ensure the proper operation of TopLink:

• Pentium®-class processor running at a minimum of 300 MHz

• 192 MB of random access memory (RAM)

• 128 MB free on your hard drive

• Monitor resolution of 1024x768

Software Requirements

TopLink requires the following supporting software:

• a JDBC driver configured to connect with your local database system (see your database administrator for details)

• a Java development environment compatible with the JDBC API, such as:
  • Oracle JDeveloper

  • Sun JDK 1.2 or JDK 1.3

  • IBM VisualAge for Java

  • Borland JBuilder

  • Microsoft Visual J++

  Or any other Java environment compatible with the Sun JDK 1.2 (or higher).

Installing TopLink

Use this procedure to install Oracle9iAS TopLink (including the Foundation Library and Mapping Workbench).

Note: If you are installing under Windows NT/2000, you must have administrator privileges. Also, ensure you modify the System Variables, not the User Variables. Java package names are case-sensitive. If you are installing under a 32-bit Windows environment, make sure the case sensitivity is turned on.

Before installing TopLink, you should back up all existing project data.

To Install TopLink on Windows:

1. Download the software or insert the CD-ROM.

   If you downloaded the software, you must un-compress the installer.

2. Follow the instructions in the installer.

3. Refer to <INSTALL_DIR>\doc\index.html for the latest release notes.

   If you installed to the default directory, <INSTALL_DIR> is C:\<ORACLE_HOME>\toplink.

4. Check and if necessary, modify the CLASSPATH environment variable. See "Modifying the PATH and CLASSPATH Environment Variables" for more information.

   Caution: In this release, the package structure has been changed to conform with Oracle9i standards and conventions for packages. The base package for the entire structure is now oracle.toplink. To facilitate the migration to the new package names, Toplink provides a tool to help you migrate to the new names, if you are upgrading from 2.x, 3.x or 4.6 to Oracle9iAS TopLink Release 2 (9.0.3). Consult the Package Renamer for more information.

To Install TopLink on Unix or other non-Windows Operating System:

1. Download the software or insert the CD-ROM.

2. Un-compress the files to a directory on your local file system. This directory is <INSTALL_DIR>.

3. Refer to <INSTALL_DIR>/docs/index.html for the latest release notes.

   If you installed to the default directory, <INSTALL_DIR> is /<ORACLE_HOME>/toplink.

4. Check and if necessary, modify the CLASSPATH environment variable. See "Modifying the PATH and CLASSPATH Environment Variables" for more information.

   Caution: In this release, the package structure has been changed to conform with Oracle9i standards and conventions for packages. The base package for the entire structure is now oracle.toplink. To facilitate the migration to the new package names, Toplink provides a tool to help you migrate to the new names, if you are upgrading from 2.x, 3.x or 4.6 to Oracle9iAS TopLink Release 2 (9.0.3). Consult the Package Renamer for more information.

Modifying the PATH and CLASSPATH Environment Variables

You must properly configure your PATH and CLASSPATH environment variables before using TopLink. If the Mapping Workbench is open, close the Mapping Workbench and re-open it after modifying these settings.

Note: Your individual user variables may override the system variables. Contact your system administrator for more information on setting user and system environment variables.

Use these procedures to configure your PATH and CLASSPATH environment variables for Windows Environment or a Non-Windows Environment.

Windows Environment

Add the following to the beginning of your PATH:

<JAVADIR>\bin\

where <JAVADIR> is the directory of your Java run-time.

Add the following to the beginning of your CLASSPATH:

<INSTALL_DIR>\core\lib\toplink.jar

<INSTALL_DIR>\core\lib\xerces.jar

<INSTALL_DIR>\core\lib\antlr.jar

where <INSTALL_DIR> is the directory which contains TopLink (for example, C:\<ORACLE_HOME>\toplink).

Non-Windows Environment

Add the following to the beginning of your PATH:

<JAVADIR>\bin\

where <JAVADIR> is the directory of your Java run-time.

Add the following to the beginning of your CLASSPATH:

<INSTALL_DIR>/core/lib/toplink.jar

<INSTALL_DIR>/core/lib/xerces.jar

<INSTALL_DIR>/core/lib/antlr.jar

where <INSTALL_DIR> is the directory which contains TopLink (for example, /<ORACLE_HOME>/toplink).

Third-party License Information

TopLink uses the following software:

ANT

jakarta.apache.org/ant/index.html

Antlr

www.antlr.org/rights.html

TopLink uses Antlr for EJBQL parsing. Antlr (ANother Tool for Language Recognition), is a language tool that provides a framework for constructing recognizers, compilers, and translators from grammatical descriptions containing C++ or Java actions. The ANTLR parser and translator generator is fully in the public domain.

DOM

www.w3.org/Consortium/Legal/copyright-software.html

The Document Object Model (DOM) is a specification that defines some programming language-neutral interfaces that can be used to manipulate XML and HTML documents. W3C maintains this specification. W3C also provides a Java "binding" for these interfaces. TopLink uses this "binding" to parse and manipulate XML documents.

Copyright © 1994 - 2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

Hypersonic SQL

hsqldb.sourceforge.net/2/General/license.html

This product includes Hypersonic SQL. The HSQL database shipped with the TopLink examples and demos is for development purposes only. Redistributions of source code must retain the copyright notice set forth below, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the copyright notice set forth below, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes Hypersonic SQL."

• Products derived from this software may not be called "Hypersonic SQL" nor may "Hypersonic SQL" appear in their names without prior written permission of the Hypersonic SQL Group.

• Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes Hypersonic SQL."

The HSQL software is provided "as is" and any expressed or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the Hypersonic SQL Group or its contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption). However caused any on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage. Copyright © 1995-2000 by the Hypersonic SQL Group. All rights reserved.

Java Runtime Environment v 1.3.1

java.sun.com/j2se/1.3

The Java Runtime Environment is maintained by Sun Microsystems, Inc. The TopLink Mapping Workbench runs in a Windows JDK 1.3.1_03 VM by default, and may also be configured to run using other compliant Java 2 VMs. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and other countries.

SAX

sax.sourceforge.net

The Simple API for XML (SAX) is an interface for event-based XML parsing, developed collaboratively by the members of the XML-DEV mailing list. TopLink uses this API to interact with the Apache Xerces parser.

xerces.jar

www.apache.org

This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Copyright © 2000 The Apache Software Foundation. All rights reserved.

1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.

2. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

3. The names "Apache" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission.

4. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Configuring TopLink for Your Development Environment

This section contains detailed information on configuring TopLink for your specific development environment.

Sun JDK and JRE

By default, TopLink includes Java Runtime Environment 1.3.1_03 from Sun Microsystems for use by the TopLink Mapping Workbench.

To configure TopLink for a different version of the JRE or a JDK installation, change the setenv.cmd, at the root of <INSTALL_DIR> to point JAVA_HOME to the new install directory.

For development purposes with the TopLink Foundation Library or to run the TopLink Examples, you must have either JDK 1.2 or 1.3 installed. Ensure the setenv.cmd, at the root of <INSTALL_DIR> points JAVA_HOME to the JDK installation.

IBM VisualAge for Java

When using TopLink with VisualAge, you can speed the development of an application by:

• Importing TopLink Classes

• Importing TopLink Source Files

Importing TopLink Classes

To use TopLink inside the VisualAge environment you must import the TopLink classes.

To Import TopLink Classes:

1. Choose File > Import.

2. Select the toplink.jar file in the <INSTALL_DIR>\core\lib\ .

3. Select a target project. For a new project, type the name in the Project field.

4. Click Finish.

Repeat for any other .jars that you want to import into VisualAge.

Importing TopLink Source Files

You can import TopLink source files into the VisualAge environment to provide partial source for a project.

Note: You must import the TopLink  .jar files that contain the class files before importing the related TopLink source files. See "Importing TopLink Classes" for more information.

To import the TopLink source.jar

1. Choose File > Import.

2. Select the source.jar file.

3. Specify <INSTALL_DIR>\core\lib\source.jar as the file name.

4. Select the Java Source check box to indicate that you are importing java source files rather than class files.

5. Select the target project into which you imported the related TopLink classes.

6. Click Finish.

Make sure your runnable classes using TopLink include the TopLink projects on their CLASSPATH.

Note: If you are using an earlier version of IBM VisualAge for Java, import the TopLink .jar files into a new TopLink project.

Testing Your TopLink Installation

Compile and execute the ConnectTest class in the oracle.toplink.tutorials.gettingstarted package.

To Test the Installation:

Run the ConnectTest class from the command line, passing appropriate database login information as parameters as follows:

java oracle.toplink.tutorials.gettingstarted.ConnectTest <username> <password> 
<database url> <jdbc driver class> 

or

Modify the main() method to contain appropriate database login information as parameters, as in the following example, then recompile and execute the class.

public static void main(String[] args)

{
  ConnectTest test = new ConnectTest();
  if (args.length > 0) {
    test.connect(args[0], args[1], args[2], args[3], args[4]);
  }

  // Add your login information below
  else {
    test.connect("<user>","<password>", "oracle.jdbc.driver.OracleDriver", 
    "jdbc:oracle:thin:@oraserver:1521:orcl";
  }
}

If the code does not run successfully, check the error message and ensure that all of your settings are correct. If necessary, refer to "General Troubleshooting" for more information.

After installing and testing TopLink, refer to the Oracle9iAS TopLink Tutorial Guide for information on the tutorials that will help you learn about TopLink.

General Troubleshooting

After installing TopLink, if you encounter problems either starting the application or connecting to a database, try the following solutions:

• Check the jdbc.log file located in the installation folder for the SQL exception being generated.

• Ensure that the driver class name is correct. Many vendors have several different driver classes to choose from.

• Check your login information.

• Ensure that your PATH includes all .dll files required by your driver.

• Ensure that your CLASSPATH includes all classes or .zip/.jar files required by your JDBC driver.

• Check with your database administrator that:
  • Any drivers that require special set-up in the database server (such as Sybase JConnect) have been set up correctly.

  • Any drivers that require special permissions in the database server have been set up correctly.

  • You are not exceeding the number of available concurrent connections to your database. This may occur during development time, when many people are testing connections.

• If you are using a database servers that requires an extra Windows NT service to be running for JDBC connections, ensure that one is running

• Check with your vendor to ensure that you are using the latest version of both your JDBC driver and the database to which it is connecting.

Refer to the Oracle9iAS TopLink Troubleshooting Guide for more information.