OracleAS TopLink—Web Client

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

The Web Client leverages Java objects, database, and OracleAS 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.

The Web Client can access the following types of server sessions:

Server sessions that any OracleAS TopLink application on the same application server have loaded into the session manager
Server sessions that are created by the Web Client by supplying a sessions.xml file

Before you access server sessions, all the XML files and classes used by the server session must be accessible to the Web Client. This includes:

The sessions.xml file
The project.xml file (or the class files specified in the sessions.xml file)
All the persistent classes mapped in the project
All the required drivers

Configuring the Web Client

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

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. 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 OracleAS TopLink project uses a datasource, add the datasource information to the <ORACLE_HOME>\toplink\config\toplinkwc\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>

In addition to the standard OracleAS TopLink .jar files, add the following to your application server classpath:

<ORACLE_HOME>\jlib\uix2.jar 
<ORACLE_HOME>\jlib\share.jar

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:

To connect OracleAS TopLink server sessions already loaded into the session manager
To bundle a single OracleAS TopLink session with the OracleAS TopLink Web Client

Follow these steps to connect OracleAS TopLink server sessions already loaded into the Session Manager:

In the <ORACLE_HOME>\toplink\config\toplinkwc\build.properties file, leave the domain.jar.path setting blank.
Run the assembleWebClient script located in the <ORACLE_HOME>\toplink\bin directory.

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

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

Follow these steps to bundle a single OracleAS TopLink session with the Web Client:

Package your domain classes, OracleAS TopLink project.xml file, the sessions.xml file, and any other necessary artifacts into a .jar file (called the domain jar).
Specify the path to your domain.jar file in the Web Client build.properties file (as specified in "Configuring the Web Client").
Run the assembleWebClient script located in the <ORACLE_HOME>\toplink\bin directory.

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

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

Configuring the Application Server

Before using the OracleAS TopLink Web Client, configure your application server.

Follow these steps to use the OracleAS TopLink Web Client with OC4J:

Add the following line to the server.xml file located in the <ORACLE_HOME>\toplink\examples\oc4j\904\server\config directory:
```
<application name="toplinkwc" path="../applications/toplinkwc.ear" auto-start="true" />
```
Add the following line to the http-web-site.xml file located in the <ORACLE_HOME>\toplink\examples\oc4j\904\server\config directory:
```
<web-app application="toplinkwc" name="toplinkwc" root="/toplinkwc" />
```
To start the server, run the startServer script located in the <ORACLE_HOME>\toplink\examples\oc4j\904\server directory.

This step deploys all the OracleAS TopLink Examples, including the OracleAS TopLink Web Client.
To start the OracleAS TopLink Web Client, load http://localhost:8888/toplinkwc into a Web browser.

Follow these steps to use the OracleAS TopLink Web Client with IBM WebSphere:

Copy the toplinkwc.ear file into the <WEBSPHERE_INSTALL_DIR>\installableApps directory.
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.
To start the OracleAS TopLink Web Client, load http://localhost:9080/toplinkwc into a Web browser.

Follow these steps to use the OracleAS TopLink Web Client with BEA WebLogic:

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

Define a reference to this datasource in the <ORACLE_HOME>\toplink\config\toplinkwc\weblogic.xml file, as follows:

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

Copy the toplinkwc.ear file into the <ORACLE_HOME>\toplink\examples\weblogic\wlsXX\server\config\TopLink_Domain\applications directory.
Copy the toplinkwc.ear file into the <ORACLE_HOME>\toplink\examples\weblogic\wlsXX\server\config\TopLink_Domain\applications directory.
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 OracleAS TopLink Examples, including the OracleAS TopLink Web Client.
To start the OracleAS TopLink Web Client, load http://localhost:7001/toplinkwc into a Web browser.

Connecting to OracleAS TopLink Sessions

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

Follow these steps to connect to an OracleAS TopLink session:

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

Click Refresh to refresh the session list.
Description of the illustration refresh.gif

Figure A-1 Web Client Home

Description of the illustration home.gif
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.
  Description of the illustration connect.gif
  
  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.
  Description of the illustration disconet.gif
- 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.

S earching for Objects

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

Figure A-2 Web Client Search

Description of the illustration search.gif

Follow these steps to search for an object:

Click the Search tab.
Choose a Descriptor from the Descriptor list.
Choose one of the following search options:
- To search for an object using its primary key, enter the primary key information in the Find by Primary Key area and click Go.
- To find all available objects, click Go in the Find All area.
- To find all objects in the OracleAS TopLink cache, click Go in the Find All (Check Cache Only) area.
- To search for objects using a named query, enter the named query information in the Named Queries area and click Go.
  
  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.

Figure A-3 Web Client Search Results

Description of the illustration srchrslt.gif

Figure A-3 identifies the following user-interface elements:
List of available descriptors
Search results
Select object column
Note for privately owned classes
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.
Figure A-4 Web Client View Object

Description of the illustration result.gif
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 OracleAS 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 OracleAS TopLink Web Client.

Follow these steps to create an object:

Choose the Descriptor of the object to create.
Click the Create tab.

Figure A-5 Web Client Create

Description of the illustration create.gif
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.

Follow these steps to perform a SQL query:

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".

Figure A-6 Web Client DB Access

Description of the illustration dbaccess.gif
Enter the SQL query.

Note:
The Web Client does not validate the SQL query.
Specify whether the Web Client limits the number of rows returned from the query.
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.

Figure A-7 Web Client DB Access Results

Description of the illustration dbresults.gif

Using the Performance Profiler

Use the Profiler tab to specify the OracleAS TopLink Performance Profiler settings that appear in Figure A-8 and to display performance information.

For more information about the OracleAS TopLink Performance Profiler settings, see "Profiling Performance".

Follow these steps to use the Performance Profiler:

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".

Figure A-8 Web Client Profiler

Description of the illustration profiler.gif
Specify the profiler settings by selecting:
- Enable Server Session Performance Profiling check box
- Fully Qualify Class Name check box
After you specify the profiler settings, the Profiler tab displays performance information for OracleAS TopLink queries that the Web Client executes.

Setting Web Client Preferences

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

Follow these steps to specify the Web Client preferences:

Click the Preferences link (at the bottom of each Web Client page). The Preferences tab appears.

Figure A-9 Web Client Preferences

Description of the illustration pref.gif
Specify the advanced properties for this session by selecting:
- DB Access check box
- Profiler check box
Click Done.