Oracle® TopLink Examples |
Configuring the Application Server Examples for Oracle Containers for J2EE
10g Release 3 (10.1.3)
January 2006
Oracle TopLink Examples help users explore and learn about how to use TopLink features with different architectures and different technologies. These are designed to be as simple as possible while still effectively demonstrating the target architecture, technology, or feature.
This document provides configuration instructions for the TopLink Application Server Examples with OC4J. Although the examples require little configuration, ensure that you read and verify the configuration details included in this document.
When configuration is complete, each TopLink Example subdirectory contains a Readme with specific information to build and run the example. For a complete list of Application Server Examples, see TopLink Application Server Examples with OC4J.
Configuration instructions in this document include the following sections:
Ant, a Java-based build tool, is used to build and run the examples. Before you build and run the examples, you must download and install Ant.
Download the Ant installer, version 1.6.2.
Install Ant and follow the Ant installation instructions.
To run the examples, you must set the following system environment variables:
PATH — To build and run the examples ensure you classpath includes the Ant bin directory.
Windows example: PATH="...;C:\apache-ant-1.6.2\bin"
UNIX example: PATH="...:/usr/local/packages/ant/bin"
ANT_HOME — Ant home directory, required to build and run the examples. Set ANT_HOME to where you installed Ant.
Windows example: ANT_HOME="...;C:\jakarta-ant-1.6.2"
UNIX example: ANT_HOME="...:/usr/local/packages/ant"
JAVA_HOME — Java 2 SDK home directory, required to access to javac and to run the examples. Set JAVA_HOME to where you installed your JDK.
Windows example: JAVA HOME="...;C:\jdk1.4.x"
UNIX example: JAVA HOME="...:/usr/java/j2sdk1_4_x"
Configure the JAVA_HOME entry in C:\<ORACLE_HOME>\toplink\setenv.cmd or setenv.sh to the same value as the JAVA_HOME environment variable.
To configure the examples, you need to:
Edit the example.properties file.
Execute the configureExamples.cmd (Windows) or the configureExamples.sh (UNIX) file.
To configure the examples for your database, edit the examples.properties file variables as follows:
TOPLINK_HOME — Oracle directory where TopLink resides. For example, TOPLINK_HOME=C:/<ORACLE_HOME>/toplink
OC4J_HOME — The directory where Oracle Containers for J2EE resides. For example, OC4J_HOME=C:/<OC4j_HOME>
USERNAME — Enter the database username required to log in to the database. For example, USERNAME=scott
PASSWORD — Enter the password required to log in to the database. For example, PASSWORD=tiger
CONNECTION URL — Enter the URL required to log in to the database. For example, CONNECTION_URL=jdbc:oracle:thin:@localhost:1521:SID
DATABASE PLATFORM — Enter the database platform required to access the database.
For Oracle databases, set this to oracle.toplink.platform.database.oracle.Oracle10Platform
For IBM DB2 databases, set this to oracle.toplink.platform.database.DB2Platform
For Sybase databases, set this to oracle.toplink.platform.database.SybasePlatform
For MS SQL Server databases, set this to oracle.toplink.platform.database.SQLServerPlatform
DATABASE DRIVER — Enter the class name for your JDBC driver. For example, DATABASE_DRIVER=oracle.jdbc.OracleDriver
DATABASE DRIVER PATH — Enter the path for your JDBC driver. For example, DATABASE_DRIVER_PATH=C:/Oracle/jdbc/lib/ojdbc14.jar
DATASOURCE FACTORY CLASS — Enter the datasource factory class used in the OC4J data-sources.xml file.
For Oracle databases, set this to oracle.jdbc.pool.OracleDataSource
For IBM DB2 databases, set this to COM.ibm.db2.jdbc.net.DB2Driver
For Sybase databases, set this to com.sybase.jdbc2.jdbc.SybDriver
|
Note: The common usage pattern for path-separators by the Ant properties parser is the UNIX '/' (forward slash) path-separator. To avoid compile errors, we recommend the path look like:C:/Program Files/Some Directory/.
|
When the database information is set in the examples.properties file, execute the configureExamples file. For Windows, select the configureExamples.cmd file. For UNIX, select the configureExamples.sh file.
The configureExamples file propagates the database login information to the sessions.xml files associated to each example as well as to configuration files for the application servers.
With the exception of the non-relational examples, examples reset and populate tables. If you do not have permissions to create and drop tables on a database, proceed as follows:
Open the examples.properties file and set the outputSQL=false variable to outputSQL=true.
Select the example you wish to run.
Execute the resetDatabase file. For Windows, select the resetDatabase.cmd file. For UNIX, select the resetDatabase.sh file. The resetdatabase file is used to place the SQL statement required to create tables in an output.sql file at the root of the example folder.
|
Note: When you first execute theresetDatabase file, the initial attempt to populate the tables with the insert statements will fail because they have yet to be created on the database.
|
Forward the output.sql file to your Database Administrator. Request that the Administrator execute the commands from the output.sql file.
When the tables are created, execute the resetDatabase file a second time to populate the tables with sample data.
|
Note: For the EJB 2.0 CMP example, theoutput.sql file does not include information for the sequence table. You can find the create statement for the tables in the first line of the sql.txt file at the root of the example's folder.
|
By default, the examples use an un-encrypted (clear-text) password in the sessions.xml file. Optionally, you can use the TopLink Workbench to encrypt the password:
Start the TopLink Workbench.
Open the example specific sessions.xml file.
In the Navigator pane, select the session.
In the Editor pane, click the Login tab.
Re-enter the password in the Password field.
Save the sessions.xml file.
To run the TopLink Application Server Examples, you must ensure the application server you select is properly configured.
You can find all source and resource files for the examples (including build scripts, J2EE descriptors, and sample configuration files) in the OC4J examples directory.
Before you run the examples against OC4J:
Place a copy of your JDBC driver in the <OC4J_INSTALL>/j2ee/home/applib directory.
|
Note: The OC4J server already includes an Oracle JDBC driver. If you need to use an Oracle driver other than what is provided in the OC4J install, consult the following How-To document to change the version of the Oracle JDBC driver you wish to use: http://www.oracle.com/technology/tech/java/oc4j/1013/howtos/how-to-swapjdbclib/doc/readme.html. |
To run the Enterprise Information System (EIS) examples with JDK 1.3.1, you need to install a different version of the connector.jar file:
Download version 1.0 of the connector.jar file.
Copy the version 1.0 of the connector.jar into your <ORACLE_HOME>/j2ee/home/lib directory and overwrite the existing connector.jar file.
Ensure the database server is running.
Start the OC4J server.
When you run the TopLink Application Server Examples, useful information is written to standard out, including details about what the example is doing and what SQL is generated. You may find it useful to redirect standard out to a file when you run an example.
TopLink includes the following Application Server Examples for OC4J:
Enterprise Information System (EIS)
EJB 2.0 CMP
Oracle TopLink Examples, 10g Release 3 (10.1.3)
The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.
If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software—Restricted Rights (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.
Oracle, JD Edwards and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.
The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.