A
Application Development Tools

Oracle Application Server TopLink includes several tools that help you build and deploy an OracleAS TopLink application. This chapter introduces these tools and includes discussions on:

• OracleAS TopLink -- Web Client

• Configuring OracleAS TopLink for Oracle JDeveloper

• Deploy Tool for WebSphere Server

• Schema Manager

• Session Management Services

• Stored Procedure Generator

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, IBM WebSphere 5.0, and BEA WebLogic 6.1, 7.0 or 8.1 application servers.

Figure A-1 Web Client Home

Text description of the illustration home.gif

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 (see "Steps to Bundle a Single OracleAS 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 OracleAS TopLink project uses a datasource, add the datasource information to the <ORACLE_HOME>\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 class path:

<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

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

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

2. Run the assembleWebClient script located in the <ORACLE_HOME>\toplink\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 OracleAS TopLink Session with the Web Client:

1. 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).

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\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 OracleAS TopLink Web Client, configure your application server.

To use the OracleAS TopLink Web Client with Oracle Application Server Containers for J2EE:

1. Copy the toplinkwc.ear file to the <ORACLE_HOME>\toplink\examples\oc4j\904\server\applications directory.

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

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

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

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

To use the Web Client with IBM WebSphere:

1. 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 OracleAS TopLink Web Client, load 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 BEA WebLogic version 6.1, 70 for BEA WebLogic version 7.0. or 81 for BEA WebLogic version 8.1.

1. 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 OracleAS TopLink Examples, including the OracleAS TopLink Web Client.

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

To Connect to an OracleAS TopLink Session:

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

   Click Refresh to refresh the session list.

   Figure A-2 Web Client Home

   

   Text description of the illustration home.gif

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 .

     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 .

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

Figure A-3 Web Client Search

Text description of the illustration search.gif

To Search for an Object:

1. Click the Search tab.

2. Choose a Descriptor from the Descriptor list.

3. 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-4 Web Client Search Results

   

   Text description of the illustration srchrslt.gif

Figure A-4 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.

     Figure A-5 Web Client View Object

     

     Text description of the illustration result.gif

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

To Create an Object:

1. Choose the Descriptor of the object to create.

2. Click the Create tab.

   Figure A-6 Web Client Create

   

   Text description of the illustration create.gif

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

   Figure A-7 Web Client DB Access

   

   Text description of the illustration dbaccess.gif

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.

   Figure A-8 Web Client DB Access Results

   

   Text description of the illustration dbresult.gif

Using the Performance Profiler

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

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

To Use the Performance Profiler:

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

   Figure A-9 Web Client Profiler

   

   Text description of the illustration profiler.gif

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 OracleAS TopLink queries that the Web Client executes.

Setting Web Client Preferences

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

To Specify Web Client Preferences:

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

   Figure A-10 Web Client Preferences

   

   Text description of the illustration pref.gif

2. Specify the advanced properties for this session by selecting:
   • DB Access check box

   • Profiler check box

3. Click Done.

Configuring OracleAS TopLink for Oracle JDeveloper

This section contains information on how to configure OracleAS TopLink for Oracle JDeveloper.

Oracle JDeveloper is a J2EE development environment with end-to-end support to develop, debug, and deploy e-business applications and Web Services.

When you use OracleAS TopLink with Oracle JDeveloper, use the following procedures to add the OracleAS TopLink JAR files to your JDeveloper projects:

Creating an OracleAS TopLink JDeveloper Library:

1. Select a JDeveloper project in the System Navigator pane.

2. Choose Project > Project Settings.

   The Project Settings pane appears.

3. Choose Configurations > Development > Libraries.

   A list of predefined and user-defined libraries appears.

   Figure A-11 List of Available Libraries

   

   Text description of the illustration devlib.gif

4. Click New to create a new library that will contain the OracleAS TopLink .jar files.

   The New Library dialog box appears.

5. Enter a name for the new Library--for example, OracleAS TopLink.

   Ensure that the default choice for Libraries remains as User Libraries.

   Figure A-12 Creating a New Library

   

   Text description of the illustration newlib.gif

6. To edit the Class Path and add the OracleAS TopLink .jar files, click the Edit button.

   Add the following to the beginning of your Class Path:

   <ORACLE_HOME>\toplink\jlib\toplink.jar
   <ORACLE_HOME>\toplinkjlib\antlr.jar
   <ORACLE_HOME>\lib\xmlparserv2.jar
   
   

7. Click OK. On the Project Settings pane click OK.

Use an existing User-Defined OracleAS TopLink Library:

After a user library is created, it can be re-referenced by any other project. Revisit the Libraries window of the Project Settings, and add the OracleAS TopLink Library to any project with which you want to use OracleAS TopLink.

Deploy Tool for WebSphere Server

OracleAS TopLink integration for IBM WebSphere Server includes a deployment tool that helps you deploy your projects to WebSphere. The Deploy Tool for WebSphere is a graphical tool that makes project deployment to WebSphere easier to configure and execute. The deploy tool also includes a command-line option that enables you to deploy your project while bypassing the graphical interface element of the tool.

Figure A-13 The Deploy Tool set up for use with WSAD

Text description of the illustration deploy2.gif

To Deploy a JAR:

1. Enable the Copy generated source to directory option to save a copy of the generated code in the specified directory. This is a quick and efficient way to copy the files into a WSAD project working directory.

2. Enable the Turn on tracing option if you want to see the details of the process.

3. Click the Deploy EJB Jar button.

Using the Deploy Tool with WebSphere Studio Application Developer (WSAD)

The Deploy tool is compatible with the WebSphere Studio Application Developer (WSAD).

To Deploy from the Deploy Tool to WSAD:

1. Select the EJB Project in WSAD and choose to generate Deploy and RMIC Code.

2. Export the EJB Project to an EJB JAR, making sure that the OracleAS TopLink project and toplink-ejb-jar.xml files are included in the EJB JAR.

3. Start the OracleAS TopLink - Deploy Tool. To start the server, execute the wasDeployTool.cmd/sh script in the <ORACLE_HOME>\toplink\bin directory.

4. Choose the EJB project working directory so that OracleAS TopLink overrides the WSAD deploy code with the OracleAS TopLink deploy code.

5. If the source is copied to a directory other than the WSAD EJB Project directory, manually copy the source files to the WSAD EJB Project under the ejbModule directory of the project.

6. Enter appropriate directories in the fields of the Deploy Tool.

7. Choose Deploy EJB JAR to create the deployed EJB JAR.

8. Choose Rebuild all from the Project menu to compile the deploy code to incorporate CMP.

Troubleshooting

The most common error you might encounter when you use the deploy tool is the NoClassDefFoundError exception. To resolve this error condition, add the required resources to the Classpath. The Turn on tracing option also helps to debug errors during deployment code generation.

When an obscure error appears during the generating stub phase, copy the Java command and run it at the command prompt. This gives a more detailed error message.

Schema Manager

The Schema Manager creates and modifies tables in a database from a Java application. As a a Java code batch facility, the Schema Manager can also create sequence numbers on an existing database and generate stored procedures.

Use the Schema Manager to re-create a production database in a nonproduction environment. Doing this enables you to build models of your existing databases, and modify and test them during development.

Using the Schema Manager to Create Tables

The Schema Manager table creation mechanism uses Java types rather than database types, it is database-independent. However, this mechanism does not account for database specific optimizations, it is best-suited for development purposes rather than production.

The OracleAS TopLink TableDefinition class enables you to create new database table schemas in a generic format. At runtime, OracleAS TopLink determines the database type, and uses the generic schemas to create the appropriate fields for that database.

Creating a Table Definition

The TableDefinition class includes all the information required to create a new table, including the names and properties of a table and all its fields.

The TableDefinition class has the following methods:

setName()
addField()
addPrimaryKeyField()
addIdentityField()
addForeignKeyConstraint()

All table definitions must call the setName() method to set the name of the table that is described by the TableDefinition.

Adding Fields to a Table Definition

Use the addField() method to add fields to the TableDefinition. To add the primary key field to the table, use the addPrimaryKeyField() method rather than the addField() method.

To maintain compatibility among different databases, the type parameter requires a Java class rather than a database field type. OracleAS TopLink translates the Java class to the appropriate database field type at runtime. For example, the String class translates to the CHAR type for dBase databases. However, if you are connecting to Sybase, the String class translates to VARCHAR.

The addField() method can also be called with the fieldSize or fieldSubSize parameters for column types that require size and subsize to be specified.

Some databases require a subsize, but others do not. OracleAS TopLink automatically provides the required information, as necessary.

Defining Sybase and Microsoft SQL Server Native Sequencing

The addIdentityField() methods have the following definitions:

addIdentityField(String fieldName, Class type) 
addIdentityField(String fieldName, Class type, int fieldSize)

These methods enable you to add fields representing a generated sequence number from Sybase or Microsoft SQL Server native sequencing.

The OracleAS TopLink Two-Tier Example illustrates the table creation mechanism in the EmployeeTableCreator.java file located in the <ORACLE_HOME>\toplink\examples\foundation\twotier\src\examples\sessions\twotier\ directory.

Creating Tables on the Database

OracleAS TopLink offers two methods that enable you to pass the initialized TableDefinition object to the DatabaseSession Schema Manager:

• The createObject() method creates a new table in the database, according to the table definition.

  SchemaManager schemaManager = new SchemaManager(session);
  schemaManager.createObject(Tables.employeeTable());
  
  

• The replaceObject() method destroys and re-creates the schema entity in the database.

  SchemaManager schemaManager = new SchemaManager(session);
  schemaManager.replaceObject(Tables.addressTable());
  
  

Creating the Sequence Table

If your application requires a sequence table, invoke the createSequences() method on the Schema Manager:

SchemaManager schemaManager = new SchemaManager(session);
schemaManager.createSequences();

The preceding code:

• Creates the sequence table as defined in the session DatabaseLogin

• Creates or inserts sequences for each sequence name for all registered descriptors in the session

• Creates the Oracle sequence object if you use Oracle native sequencing

Managing Java and Database Type Conversions

Table A-1 lists the field types that match a given class for each database that OracleAS TopLink supports. This list is specific to the Schema Manager and does not apply to mappings. OracleAS TopLink automatically performs conversions between any database types within mappings.

Table A-1 OracleAS TopLink Classes and Database Field Types  

Class	Oracle Type	DB2 Type	dBase Type	Sybase Type	Microsoft Access Type
java.lang.Boolean	NUMBER	SMALLINT	NUMBER	BIT default 0	SHORT
java.lang.Byte	NUMBER	SMALLINT	NUMBER	SMALLINT	SHORT
java.lang.Byte[]	LONG RAW	BLOB	BINARY	IMAGE	LONGBINARY
java.lang.Integer	NUMBER	INTEGER	NUMBER	INTEGER	LONG
java.lang.Long	NUMBER	INTEGER	NUMBER	NUMERIC	DOUBLE
java.lang.Float	NUMBER	FLOAT	NUMBER	FLOAT(16)	DOUBLE
java.lang.Double	NUMBER	FLOAT	NUMBER	FLOAT(32)	DOUBLE
java.lang.Short	NUMBER	SMALLINT	NUMBER	SMALLINT	SHORT
java.lang.String	VARCHAR2	VARCHAR	CHAR	VARCHAR	TEXT
java.lang.Character	CHAR	CHAR	CHAR	CHAR	TEXT
java.lang.Character[]	LONG	CLOB	MEMO	TEXT	LONGTEXT
java.math.BigDecimal	NUMBER	DECIMAL	NUMBER	NUMERIC	DOUBLE
java.math.BigInteger	NUMBER	DECIMAL	NUMBER	NUMERIC	DOUBLE
java.sql.Date	DATE	DATE	DATE	DATETIME	DATETIME
java.sql.Time	DATE	TIME	CHAR	DATETIME	DATETIME
java.sql.Timestamp	DATE	TIMESTAMP	CHAR	DATETIME	DATETIME

Session Management Services

OracleAS TopLink provides statistical reporting and runtime configuration systems through two public APIs: oracle.toplink.service.RuntimeServices and oracle.toplink.services.DevelopmentServices.

Runtime Services

The RuntimeServices API enables you to monitor a running in-production system. It offers statistical functions and reporting, as well as logging functions. Typical uses for RuntimeServices include turning logging on or off and generating real time reports on the number and type of objects in a given cache or subcache.

For more information, see the RuntimeServices class in the Oracle Application Server TopLink API Reference.

Development Services

The DevelopmentServices API enables you to make changes to a running nonproduction application that can destabilize or even crash the application. For example, use the DevelopmentServices API to change the states of selected objects and modify and reinitialize identity maps. This feature is useful for stress and performance testing of preproduction applications and also enables you to build prototypes quickly and easily.

For more information, see the RuntimeServices class in the Oracle Application Server TopLink API Reference.

Using Session Management Services

To instantiate a session management service, you pass a session to the constructor. After instantiating the service, you can attach a graphical interface or other applications to the object to provide statistical feedback and runtime option settings.

Example A-1 Accessing Session Management Services

import oracle.toplink.services.RuntimeServices;
import oracle.toplink.publicinterface.Session;
...
...
RuntimeServices service = newRuntimeServices ((session) session);
java.util.List classNames = service.getClassesInSession();

Session Management Services and BEA WebLogic Server

OracleAS TopLink support for BEA WebLogic Server automatically deploys the session management services to the JMX server. You can retrieve the JMX Mbeans with the following object names:

WebLogicObjectName("TopLink_Domain:Name=Development <Session><Name> Type=Configuration");
WebLogicObjectName("TopLink_Domain:Name=Runtime <Session><Name> Type=Reporting");

Session Name represents the session type and name under which you store the required session configuration in the toplink-ejb-jar.xml file.

For more information about the WebLogicObjectName API, see

http://e-docs.bea.com/wls/docs70/javadocs/weblogic/management/WebLogicObjectName
.html

Stored Procedure Generator

You can generate stored procedures based on the dynamic SQL that is associated with descriptors and mappings. After you generate the stored procedures, attach them to the mappings and descriptors of the domain object. At that point, access to the database is accomplished through stored procedures, rather than through SQL.

Note: Implement this feature only if your database requires access by stored procedures. Doing this does not enhance performance and has the same limitations that are associated with stored procedures.

Generating Stored Procedures

You can generate stored procedures for all descriptors and most relationship mappings with the exception of many-to-many mappings, which are not supported by the stored procedure generator and stored procedures for Read operations for the Oracle platform.

Sequencing and Stored Procedures

You can generate stored procedures for sequence number updates and selects. To enable these stored procedures in OracleAS TopLink, create an amendment class that contains a method attaching the stored procedures to each descriptor.

Example A-2 Stored Procedures Generated Directly on the Database

OracleAS TopLink creates an amendment class called com.demo.Tester in the file C:/temp/Tester.java.

SchemaManager manager = new SchemaManager(session);
manager.outputDDLToDatabase();
manager.generateStoredProceduresAndAmendmentClass("C:/temp/","com.demo.Tester");

Example A-3 Generating Stored Procedures to a File

SchemaManager manager = new SchemaManager(session);
manager.outputDDLToFile("C:\Temp\test.sql");
manager.generateStoredProceduresAndAmendmentClass("C:/temp/","com.demo.Tester");

For more information about creating an amendment class, see "Customizing OracleAS TopLink Descriptors with Amendment Methods".

Attaching the Stored Procedures to the Descriptors

After you create the stored procedures on the database, and after you create the amendment file, enable them on the descriptors:

• Before logging in, call a method on the generated amendment class:

  Session session = project.createDatabaseSesssion();
  com.demo.Tester.amendDescriptors(project);
  
  

For more information about creating an amendment class, see "Customizing OracleAS TopLink Descriptors with Amendment Methods".