| Oracle® TopLink Getting Started Guide 10g (10.1.3.1.0) Part Number B28217-02 |
|
|
View PDF |
| Oracle® TopLink Getting Started Guide 10g (10.1.3.1.0) Part Number B28217-02 |
|
|
View PDF |
This chapter includes the following information to install and configure Oracle TopLink on your computer:
Use the following procedures to install TopLink (including TopLink Foundation Library and TopLink Workbench). Before you install TopLink, back up all existing project data.
Warning:
If you are upgrading from a pre-Release 1 (9.0.3), you must convert the package names before you open your TopLink project(s) in 10g (10.1.3.1.0). Refer to "Package Rename" for more information after installing TopLink.
This section includes information on:
Use this procedure to start the Oracle Universal Installer and install TopLink 10g (10.1.3.1.0).
For Windows operating systems:
Ensure that you are logged in to the computer as a member of the Windows Administrators group.
When configuring TopLink for use with J2EE containers, you must modify the System Variables—not the User Variables.
For Unix or other non-Windows operating systems:
Insert the TopLink installation disk into the CD-ROM drive to launch Oracle Universal Installer, or download the installer from:
http://www.oracle.com/technology/products/ias/toplink/index.html
For Windows operating systems:
If your computer supports the auto run feature, the installer will automatically launch on your computer.
If your computer does not support the auto run feature, execute the G:\setup.exe program (where G is the letter for your CD-ROM drive) to start the installer.
For UNIX or other non-Windows operating systems:
If your computer supports the auto run feature, the installer will automatically launch on your computer.
If your computer does not support the auto run feature, enter: prompt> mount_point/as_10131disk/runInstaller to launch the installer.
Caution:
Do not start the installation inside the
mount_point directory. If you do, then you may not be able to eject the installation disk.Complete each screen of the installer.
When the installation is complete, you must configure the TopLink Workbench environment.
For more information, see "Configuring the TopLink Workbench Environment" in the Oracle TopLink Developer's Guide.
Refer to <ORACLE_HOME>\toplink\doc\index.html.html for the latest Oracle TopLink Release Notes.
By default, the TopLink installation allows access for only the user who performed the installation. If your TopLink installation is in a shared environment you must manually change the file permissions for all files in the <ORACLE_HOME> directory. Executable files require read and execute access; non-executable files require read access. Refer to your operating system documentation for information on setting file permissions.
Silent installation mode is available for all installation types. You can use the silent installation when you wish to make multiple installations simultaneously or when you perform installations from a remote location. Silent installation eliminates the need to monitor the installation because there is no graphical output and no input by the user.
Insert the TopLink installation disk into the CD-ROM drive.
Open the \Stage\Response directory and select the oracle.toplink.install_type_1.rsp file.
Copy the oracle.toplink.install_type_1.rsp file to a temporary (tmp) location.
Edit the following parameters in the oracle.toplink.install_type_1.rsp file:
Start the installer.
For Windows operating systems, open a command prompt window and enter:
setup.exe -responseFile c:/oracle.toplink.install_type_1.rsp -silent
For UNIX and other non-Windows operating systems, open a command prompt window and enter:
./runInstaller -responseFile /tmp/oracle.toplink.install_type_1.rsp -silent
If your installation was successful, the silentInstall.log file contains the line:
"The installation of TopLink was successful."
The following table describes the TopLink JAR files installed in the <ORACLE_HOME>/toplink/jlib directory.
Table 2-1 TopLink JAR Files
| JAR File | Contents |
|---|---|
|
|
This JAR contains the Antlr (ANother Tool for Language Recognition) tool. |
|
|
This JAR contains the TopLink migration tool for migrating an existing J2EE application to use TopLink as the persistence manager. See "Persistence Manager Migration" in the Oracle TopLink Developer's Guide for more information. |
|
|
This JAR contains the TopLink Package Rename tool for migrating Release 1 (9.0.3) projects to 10g (10.1.3.1.0). See "Package Rename" for more information. |
|
|
This JAR contains the preview version of the TopLink JPA functionality for EJB 3.0. Initially available with Release 3 (10.1.3.0.0), this JAR has been superseded by the JPA 1.0 implementation provided by TopLink Essentials ( |
|
|
This JAR contains the TopLink JAXB compiler necessary to create a JAXB project. For more information, see "Creating an XML Project From an XML Schema" in the Oracle TopLink Developer's Guide. |
|
|
This JAR contains the TopLink Workbench classes used by the TopLink Workbench application classes in Use this library when generating TopLink Workbench projects (MWP) or creating deployment XML from TopLink Workbench or from within code. This library is also used by the migration utilities and ANT tasks that automate these development tasks. |
|
|
This JAR contains the TopLink Workbench online help used by the TopLink Workbench application classes in |
|
|
This JAR contains the classes that TopLink uses to perform byte-code weaving on EJB 2.1 entity bean classes to enable transparent 1:1 and M:1 indirection without requiring the use of a For more information, see "Indirection, Serialization, and Detachment" in the Oracle TopLink Developer's Guide. |
|
|
This JAR contains all classes that have been deprecated. Oracle recommends that you avoid using all deprecated classes because support for them may be removed in a future release. Include this JAR on your application classpath only if necessary. See the API Modifications for more information. |
|
|
This JAR contains TopLink Essentials, the open source JPA edition of TopLink. See "TopLink JPA" for more information, including how to obtain the source ( |
|
|
This JAR contains the classes that TopLink uses to perform byte-code weaving on JPA entities to automatically enable features such as This JAR is optional and should never be placed on the classpath – only as part of |
|
|
This JAR contains the classes that TopLink uses to integrate with Oracle Containers for J2EE. This JAR is only used in OC4J; the container is preconfigured to use |
|
|
This JAR contains all the classes that comprise the TopLink API. |
|
|
This JAR contains the TopLink Workbench application classes. It depends on |
For information on packaging and deploying TopLink with an application server, refer to "Deploying a TopLink Application" in the Oracle TopLink Developer's Guide.
At runtime, the TopLink Foundation Library requires the Java Runtime Environment 1.3 (or higher). By default, the TopLink installation includes the JRE 1.5.
To configure TopLink for a different version of the JRE, change the <ORACLE_HOME>/toplink/bin/setenv file to point JAVA_HOME to the alternate directory.
After installing TopLink Workbench, you must configure the following:
TopLink Workbench requires the Java Runtime Environment 1.4.2_06 (or higher). By default, the TopLink installation includes the JRE 1.5.
To configure TopLink for a different version of the JRE, change the <ORACLE_HOME>/toplink/bin/setenv file to point JAVA_HOME to the alternate directory.
By default, TopLink installs only a portion of TopLink Workbench online help system on your PC. To access the complete documentation from Oracle, ensure that your PC is connected to the internet and the your proxy information (if necessary) is correct.
For more information on how to specify the help mode, refer to "Help Preferences" in the Oracle TopLink Developer's Guide.
From the TopLink Workbench menu, select Tools > Preferences. On the Preferences dialog, select General to configure your proxy information.
Depending on the TopLink Workbench project, you are required to update the DRIVER_CLASSPATH environment variable to add the location of the following (if necessary):
J2EE Connector Architecture (J2C/JCA) adapters – If you are using TopLink Workbench Enterprise Information System (EIS) projects.
Oracle Database <ORACLE_HOME>/rdbms/jlib/xdb.jar file – If you are using direct to XML type mappings with an Oracle9i or higher database.
Custom Collection class that you use to override the default Collection class that TopLink uses with a mapping container policy.
For more information on how to update the DRIVER_CLASSPATH environment variable, see "Configuring the TopLink Workbench Environment" in the Oracle TopLink Developer's Guide.
If you plan to use additional, third-party libraries (such as XMLType Mappings or EIS with Attunity), when deploying your Oracle TopLink project, you must copy the appropriate JAR file to <ORACLE_HOME>/toplink/jlib. Additionally, you must include the libraries on you server's classpath.
The Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) Enterprise Java Beans (EJB) 3.0 specification, greatly simplifies Java persistence and provides an object-relational mapping approach that allows you to declaratively define how to map Java objects to relational database tables in a standard, portable way that works both inside a Java EE 5 application server and outside an EJB container in a Java Standard Edition (Java SE) 5 application.
TopLink Essentials is the JPA provider for the EJB 3.0 Reference Implementation. In addition to being JPA compliant, it also provides additional extensions beyond what is defined in the JPA specification.
Note:
TopLink Essentials is the default JPA persistence provider for EJB 3.0 JPA applications when used with Oracle Containers for J2EE.When using TopLink JPA you can leverage additional functionality beyond the JPA 1.0 specification. These extensions are provided through the use of query hints, persistence unit properties, and additional API. For more information on TopLink JPA extensions, see http://www.oracle.com/technology/products/ias/toplink/jpa/resources/toplink-jpa-extensions.html.
To obtain more information and to download the source (toplink-essentials-src.zip), see the following:
http://www.oracle.com/technology/products/ias/toplink/jpa/index.html
"Understanding the EJB 3.0 JPA Entity Architecture" in the Oracle TopLink Developer's Guide
To start TopLink Workbench, simply execute the workbench.cmd or .sh file in the <INSTALL_DIR>/toplink/bin directory. The TopLink Welcome Screen appears.
If you receive a "Cannot Find Main Class" error, ensure that you have configured JAVA_HOME correctly. See "JRE Version".
Note:
On Microsoft Windows XP platforms with mapped network drives, the TopLink Workbench File Chooser dialogs (such as Save File or Open File) may experience slow responses for opening and traversing directory trees. Unmapping the network drives eliminates this behavior.To use TopLink Workbench in a language different than your default, add the -Duser.language and -Duser.country options to the JVM_ARGS variable in the workbench.cmd or .sh file. For example, the following arguments will start TopLink Workbench in US English; regardless of default language of your operating system.
JVM_ARGS="-Duser.language=en -Duser.country=en_US"
After you install TopLink, if you encounter problems either starting the application or connecting to a database, try the following solutions:
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 your driver requires.
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 use 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.
If it takes an extremely long time to start TopLink Workbench after the splash screen appears (for example, more than 30 seconds), ensure that your proxy help mode and proxy information is correct. See "Online Help and Documentation" for details.
On Unix, TopLink Workbench requires a "home" directory to store your user preferences. Use one of the following methods to specify a home directory:
Create a new /home/<USERNAME> directory to store your user preferences.
Add the -D option to the JVM_ARGS variable in the workbench.sh file to specify an existing directory to use as your home directory. For example:
JVM_ARGS="-Duser.home=/someDirectory"
where someDirectory is an existing directory to use as your home directory.
If you do not create or specify a home directory, TopLink Workbench will fail to start.
