Oracle® TopLink Web Client

Installation and Configuration Instructions

10g Release 3 (10.1.3)

January 2006

The Oracle TopLink Web Client provides a Web-based interface that allows you to work with any TopLink server session that is deployed on Oracle Containers for J2EE (OC4J), IBM WebSphere 5.0, 5.1 and BEA WebLogic 6.1, 7.0 or 8.1 application servers.

The Web Client leverages Java objects, database and TopLink metadata to automatically create a browser based user interface to display and allow the manipulation of persistent objects obtained through server sessions. In addition, the Web Client offers utilities to profile the performance of your server session, as well as interactively execute SQL on the database connected to your server session.

This document contains information on:

System Requirements and Certifications

The complete product requirements list and the latest certification information for 10g Release 3 (10.1.3) is available at:

http://www.oracle.com/technology/software/products/ias/files/as_certification_r3_1013.html

Conventions

The following conventions are used in this document:

Installing the Web Client

Use the following procedures to install the Web Client.

  1. Download the Web Client Zip file (toplink_webclient.zip).

  2. Unzip the toplink_webclient.zip file into an existing <ORACLE_HOME> directory.

    This is the <ORACLE_HOME> directory where the Web Client will reside. Although recommended, the Web Client need not be installed in the same <ORACLE_HOME> directory as the TopLink installation.

Configuring the Web Client

Before you build the Web Client, edit the following properties in the <ORACLE_HOME>\toplink\webclient\config\build.properties file.

When you enter the following properties, you must use forward ( / ) slashes to specify the directory paths. This applies to both Windows and non-Windows operating systems.

Property Description
deployment.dir Directory into which the EAR file is copied after you build the Web Client.

Normally, this is your application server deployment directory.

domain.jar.path The full path to your .jar file, when you deploy your own domain classes with the Web Client (see "Steps to Bundle a Single TopLink Session with the Web Client").

To deploy the Web Client without any domain classes, leave this property blank.

use.weblogic When you deploy to WebLogic, set to true.
defaultwebapp.dir The location of the DefaultWebApp directory on the WebLogic server to which you are deploying.

When running on WebLogic, the Web Client needs to extract resources here so that they are available to the web application.


If your TopLink project uses a data source, add the data source information to the <ORACLE_HOME>\toplink\webclient\config\web.xml file, as follows: 

<resource-ref>
    <description>DataSource</description>
    <res-ref-name>jdbc/DataSourceName</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>SERVLET</res-auth>
</resource-ref>

If you wish to configure the data source for either a JTS on a non-JTS data source, use the following examples: 

<resource-ref>
    <description>JTSDataSource</description>
    <res-ref-name>jdbc/JTSTopLinkDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>SERVLET</res-auth>
</resource-ref>

<resource-ref>
    <description>NonJTSDataSource</description>
    <res-ref-name>jdbc/TopLinkDS</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>SERVLET</res-auth>
</resource-ref>

Ensure that any data source information you enter is stored between the <web-app> delimiters.

Using BEA WebLogic and bundling a single TopLink session with the Web Client

In addition to adding information to the web.xml file if your TopLink project uses a data source, using the BEA WebLogic application server also requires you add the data source information to the <ORACLE_HOME>\toplink\webclient\config\weblogic.xml file, as follows: 

<reference-descriptor>
   <reference-description>
    <res-ref-name>jdbc/DataSourceName</res-ref-name>
    <res-type>jdbc/DataSourceName</jndi-name>
   </reference-description>
</resource-descriptor>

If you wish to configure the data source for either a JTS on a non-JTS data source, use the following examples: 

<resource-descriptor>
   <resource-description>
    <res-ref-name>jdbc/JTSTopLinkDS</res-ref-name>
    <res-type>jdbc/JTSTopLinkDS</jndi-name>
   </reference-description>
</resource-descriptor>

<resource-descriptor>
   <resource-description>
    <res-ref-name>jdbc/TopLinkDS</res-ref-name>
    <res-type>jdbc/TopLinkDS</jndi-name>
   </reference-description>
</resource-descriptor>

Building the Web Client EAR File

Use the Web Client in either of the following ways to build and deploy the Web Client  .ear file:

Steps to Connect TopLink Server Sessions Already Loaded into the Session Manager

  1. In the <ORACLE_HOME>\toplink\webclient\config\build.properties file, leave the domain.jar.path setting blank.

  2. Ensure that JAVA_HOME and ANT_HOME are set correctly. By default, the assembleWebClient script uses the system settings for these variables

  3. Run the assembleWebClient script located in the <ORACLE_HOME>\toplink\webclient\bin directory.

    The system assembles and deploys toplinkwc.ear file, as specified in the build.properties file.

For more information, see "Configuring the Web Client".

Steps to Bundle a Single TopLink Session with the Web Client

  1. Package your domain classes, TopLink project.xml file, the sessions.xml file and any other necessary artifacts into a .jar file (called the domain jar).

  2. Specify the path to your domain.jar file in the Web Client build.properties file (as specified in "Configuring the Web Client").

  3. Run the assembleWebClient script located in the <ORACLE_HOME>\toplink\webclient\bin directory.

The system assembles and deploys toplinkwc.ear as specified in the build.properties file.

For more information, see "Configuring the Web Client".

Configuring the Application Server

Before using the Web Client, configure your application server.

To use the Web Client with Oracle Containers for J2EE

  1. If the deployment directory was not specified in the Web Client build.properties file, copy the toplinkwc.ear file to the <OC4J_INSTALL_DIR>\j2ee\home\applications directory.

  2. If the OC4J server is not set to Auto-Deploy, you must add the following in the <OC4J_INSTALL_DIR>\j2ee\home\config\default-web-site.xml and the <OC4J_INSTALL_DIR>\j2ee\home\config\server.xml files:

    <web-app application="toplinkwc" name="toplinkwc" load-on-startup="true" root="/toplinkwc"/>

    <application name="toplinkwc" path="../applications/toplinkwc.ear" start="true"/>

  3. If you deploy Web Client bundled with a TopLink server session, add following to the <OC4J_INSTALL_DIR>\j2ee\home\config\data-sources.xml file: 

    <connection-pool name="TopLink Examples Connection Pool">
   <connection-factory factoryclass="oracle.jdbc.pool.OracleDataSource"
      user="scott
      password="tiger
      url="jdbc:oracle:thin:@localhost:1521:ORCL">
   </connection-factory>
</connection-pool>

<managed-data-source connection-pool-name="TopLink Examples Connection Pool"
      jndi-name="jdbc/JTSTopLinkDS"
      name="JTSTopLinkDS"/>
      tx-level="local"/>

  4. To start the application server, go to the <OC4J_INSTALL_DIR>\j2ee\home\ directory and type: java -jar oc4j.jar.

  5. To start the Web Client, enter http://localhost:8888/toplinkwc into a Web browser.

To use the Web Client with IBM WebSphere

  1. If the deployment directory was not specified in the Web Client build.properties file, copy the toplinkwc.ear file into the <WEBSPHERE_INSTALL_DIR>\installableApps directory.

  2. Use the WebSphere Administration Console to install the .ear file and start the Web module.

    For more information about the WebSphere Administration Console, see the IBM WebSphere documentation.

  3. To start the Web Client, enter http://localhost:9080/toplinkwc into a Web browser.

To use the Web Client with BEA WebLogic

In the following steps, the wlsXX refers to your version of BEA WebLogic. Use 61 for version 6.1, 70 for version 7.0. or 81 for version 8.1.

  1. If the deployment directory was not specified in the Web Client build.properties file, copy the toplinkwc.ear file into the <ORACLE_HOME>\toplink\examples\weblogic\wlsXX\server\config\TopLink_Domain\applications directory.

  2. To start the server, run the startWebLogic script located in the <ORACLE_HOME>\toplink\examples\weblogic\wlsXX\server\config\TopLink_Domain\ directory.

    This step deploys all the TopLink Examples, including the Web Client.

  3. To start the Web Client, enter http://localhost:7001/toplinkwc into a Web browser.

Using the Web Client

The following section contains information about:

Connecting to TopLink Sessions

Use the Web Client Home tab to display and access the available TopLink sessions.

  1. Click the Home tab. The Web Client displays the available (registered) TopLink sessions and their status.

    Click Refresh to refresh the session list.

    Web Client Home

    Description of this figure follows
    Description of "Web Client Home"

  2. Choose one of the following options:

    • To connect to a session, select the session and click the Connect button.

      The session Status changes to a green check mark.

      To select a session, click the appropriate radio button under the Select column.

    • To disconnect from a session, select the session and click the Disconnect button.

      The session Status changes to a downward-pointing red arrow.

    • To clear a session cache, select the session and click the Clear Cache button.

    • To work with a specific session, click the session name. If the session is not already connected, the Web Client connects to the session.

Searching for Objects

Use the Search tab to display objects within a specific descriptor.

Web Client Search

Description of this figure follows
Description of "Web Client Search"

  1. Click the Search tab.

  2. Choose a Descriptor from the Descriptor list.

  3. Choose one of the following search options:


    Note:

    The Named Queries area appears only for objects with defined named queries.

    The Web Client displays all the objects that match the search criteria.

    Web Client Search Results

    Description of this figure follows
    Description of "Web Client Search Results"

    Figure: Web Client Search Results identifies the following user-interface elements:

    1. List of available descriptors.

    2. Search results.

    3. Select object column.

    4. Note for privately owned classes.

  4. Choose one of the following options to delete or view an object:

    • Click Delete to delete an object.


      Note:

      You cannot delete objects for privately owned classes. Instead, edit its master class.

    • Click View for the object to display. The Web Client displays the object's data.

    Web Client View Object

    Description of this figure follows
    Description of "Web Client View Object"

  5. Select further options for the viewed object:

    • Click Previous Object to display the previous record.

    • Click Next Object to display the next record.

    • Click Cached Object List to display all elements of the current type that exist in the TopLink cache.

    • Click Edit Object to change or edit the record.

      For more information about creating and editing objects, see "Creating and Editing Objects".

Creating and Editing Objects

Use the Create tab to create a new object. The information you enter on this tab is validated by the database—not the Web Client.

  1. Choose the Descriptor of the object to create.

  2. Click the Create tab.

    Web Client Create

    Description of this figure follows
    Description of "Web Client Create"

  3. Enter the necessary information and click Create.


    Note:

    You cannot create objects for privately owned classes. Instead, edit its master class.

Performing SQL Queries

Use the DB Access tab to enter specific SQL queries to execute on the database.

To Perform a SQL Query:

  1. Click the DB Access tab. If the DB Access tab is not visible, use the Web Client Preferences to enable the tab.

    For more information about setting Web Client preferences, see "Setting Web Client Preferences".

    Web Client DB Access

    Description of this figure follows
    Description of "Web Client DB Access"

  2. Enter the SQL query.


    Note:

    The Web Client does not validate the SQL query.

  3. Specify whether the Web Client limits the number of rows returned from the query.

  4. Choose the type of query:

    • Execute Select: results return the number of matches as well as the actual records.

    • Execute Non-Selecting: results return only the number of rows affected by the SQL statement.

    The Web Client displays the SQL results.

    Web Client DB Access Results

    Description of this figure follows
    Description of "Web Client DB Access Results"

Using the Performance Profiler

Use the Profiler tab to specify the TopLink Performance Profiler settings that appear in Figure: Web Client Profiler and to display performance information.

  1. Click the Profiler tab. If the Profiler tab is not visible, use the Web Client Preferences to enable the tab.

    For more information about setting Web Client preferences, see "Setting Web Client Preferences".

    Web Client Profiler

    Description of this figure follows
    Description of "Web Client Profiler"

  2. Specify the profiler settings by selecting:

    • Enable Server Session Performance Profiling check box

    • Fully Qualify Class Name check box

  3. After you specify the profiler settings, the Profiler tab displays performance information for TopLink queries that the Web Client executes.

Setting Web Client Preferences

Use the Web Client Preferences to specify which advanced properties are available.

  1. Click the Preferences link (at the bottom of each Web Client page).

    The Preferences tab appears.

    Web Client Preferences

    Description of this figure follows
    Description of "Web Client Preferences"

  2. Specify the advanced properties for this session by selecting:

    • DB Access check box

    • Profiler check box

  3. Click Done.

Oracle Toplink Web Client, 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.

Alpha and Beta Draft documentation are considered to be in prerelease status. This documentation is intended for demonstration and preliminary use only. We expect that you may encounter some errors, ranging from typographical errors to data inaccuracies. This documentation is subject to change without notice, and it may not be specific to the hardware on which you are using the software. Please be advised that prerelease documentation in not warranted in any manner, for any purpose, and we will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.