Skip Headers

Oracle9iAS TopLink Foundation Library Guide
Release 2 (9.0.3)

Part Number B10064-01
Go To Documentation Library
Home
Go To Solution Area
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

B
TopLink Development Tools

TopLink provides development tools that make the development, testing and debugging of TopLink applications easier. This section introduces these tools and discusses

The Schema Manager

The schema manager creates and modifies tables in a database from a Java application. The schema manager can also create sequence numbers on an existing database and generate stored procedures.

The session console inspects descriptors of a project file. The session console can connect to the database through TopLink, run custom SQL clauses, and view a log of query performance. It is a good practice to test your TopLink Mapping Workbench project with the session console before doing further development.

The Profiler generates a log of query performance against a TopLink session. This helps to pinpoint performance bottlenecks and makes debugging easier.

Using the Schema Manager to create tables

TopLink provides a high-level mechanism for the creation of database tables. This mechanism is database-independent and uses Java types rather than database types.

TopLink provides the TableDefinition class for the creation of new database table schema in an independent format. TopLink can then take this generic table definition and create the appropriate table and fields on the database. TopLink determines at runtime which database is being used and creates the appropriate fields for that database.

The schema manager's purpose is to allow for the database to be easily recreated and modified during development and testing. It also makes it possible for the schema to be ported, with 100% accuracy, to any other database.

TopLink's table creation mechanism does not take into account any optimization features provided on the given database and therefore should be used for prototyping purposes only.

Creating a table definition

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

TableDefinition 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 being described by the TableDefinition.

Adding fields to a table definition

Fields are added to the TableDefinition using the addField() method. The primary key of the table is added to the table definition using the addPrimaryKeyField() method instead of the addField() method. These methods have the definitions shown in the following example.

Example B-1 Adding fields to a table definition

addField(String fieldName, Class type);
addField(String fieldName, Class type, int fieldSize)
addField(String fieldName, Class type, int fieldSize, 

   intfieldSubsize);

addPrimaryKeyField(String fieldName, Class type);
addPrimaryKeyField(String fieldName, Class type, 

   int fieldSize);

addForeignKeyConstraint(String name, String sourceField, 

   String targetField, String targetTable) 

When declaring a field, the first parameter, fieldName, is the name of the field to be added to the table. The second parameter, type, is the type of field to be added. To maintain compatibility among different databases, a Java class is specified for the second parameter instead of a database field type. TopLink translates the Java class to the appropriate database field type based on the database upon which it is created. For example, the String class translates to the CHAR type when connecting to dBase. However, if connecting to Sybase the String class translates to VARCHAR.

If the field must specify a size, then the second method would be used and the size would be specified as the fieldSize parameter. If the field specifies a sub-size, the third method would be used to specify the fieldSubSize parameter.

Some databases require that a sub-size be specified for a given field type whereas another database vendor does not. TopLink automatically checks for this and removes or adds the sub-size if necessary. This allows the table creation mechanism to remain generic across multiple database vendors.

Defining Sybase and SQL Server sequence numbers

If the field being added to the database is a generated sequence number that uses Sybase's or SQL Server's native sequencing, use one of the addIdentityField() methods instead of the addField() method. The addIdentityField() methods have the following definitions:

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

Example of table definition

The following example shows the table creation mechanism taken from the TopLink Employee Demo.

Example B-2 Creating a TableDefinition for the EMPLOYEE table

public static TableDefinition employeeTable()
{
TableDefinition definition;
definition = new TableDefinition();
definition.setName("EMPLOYEE");
definition.addIdentityField("EMP_ID", BigDecimal.class, 15);
definition.addField("VERSION", Integer.class);
definition.addField("F_NAME", String.class, 40);
definition.addField("L_NAME", String.class, 40);
definition.addField("START_DATE", java.sql.Date.class);
definition.addField("END_DATE", java.sql.Date.class);
definition.addField("START_TIME", java.sql.Time.class);
definition.addField("END_TIME", java.sql.Time.class);
definition.addField("GENDER",String.class,10); 
definition.addField("ADDRESS_ID", BigDecimal.class, 15);
definition.addField("MANAGER_ID", BigDecimal.class, 15);
definition.addForeignKeyConstraint("employee_manager", "MANAGER_ID", "EMP_ID", 
"EMPLOYEE");
definition.addForeignKeyConstraint("employee_address","ADDRESS_ID", "ADDRESS_
ID", "ADDRESS");
return definition;}

Creating tables on the database

Tables are created by passing the initialized TableDefinition object to the DatabaseSession's schema manager.

TopLink provides two separate methods for creating tables.

Creating the sequence table

TopLink can automatically create a sequence table if required by the application. This can be done by calling the createSequences() method of the schema manager:

schemaManager.createSequences();

This configures the sequence table as defined in the session's DatabaseLogin and creates/inserts sequences for each sequence name of all registered descriptors in the session. If Oracle native sequencing is used, Oracle sequence objects are created.

Using the Schema Manager to manage Java and database type conversions

Table B-1 through Table B-5 list the field types that match a given class for each database supported by TopLink. This list is specific to the Schema Manager and does not apply to mappings (TopLink automatically performs conversion between any database types within mappings).

Table B-1 DB2 field types  
Class Data Type

java.lang.Boolean

SMALLINT

java.lang.Byte

SMALLINT

java.lang.Byte[]

BLOB

java.lang.Integer

INTEGER

java.lang.Float

FLOAT

java.lang.Long

INTEGER

java.lang.Double

FLOAT

java.lang.Short

SMALLINT

java.lang.String

VARCHAR

java.lang.Character

CHAR

java.lang.Character[]

CLOB

java.math.BigDecimal

DECIMAL

java.math.BigInteger

DECIMAL

java.sql.Date

DATE

java.sql.Time

TIME

java.sql.Timestamp

TIMESTAMP

Table B-2 dBASE field types  
Class Data Type

java.lang.Boolean

NUMBER

java.lang.Byte

NUMBER

java.lang.Byte[]

BINARY

java.lang.Long

NUMBER

java.lang.Integer

NUMBER

java.lang.Float

NUMBER

java.lang.Double

NUMBER

java.lang.Short

NUMBER

java.lang.String

CHAR

java.lang.Character

CHAR

java.lang.Character[]

MEMO

java.math.BigDecimal

NUMBER

java.math.BigInteger

NUMBER

java.sql.Date

DATE

java.sql.Time

CHAR

java.sql.Timestamp

CHAR

Table B-3 Oracle field types  
Class Data Type

java.lang.Boolean

NUMBER

java.lang.Byte

NUMBER

java.lang.Byte[]

LONG RAW

java.lang.Integer

NUMBER

java.lang.Long

NUMBER

java.lang.Float

NUMBER

java.lang.Double

NUMBER

java.lang.Short

NUMBER

java.lang.String

VARCHAR2

java.lang.Character

CHAR

java.lang.Character[]

LONG

java.math.BigDecimal

NUMBER

java.math.BigInteger

NUMBER

java.sql.Date

DATE

java.sql.Time

DATE

java.sql.Timestamp

DATE

Table B-4 Sybase field types  
Class Data Type

java.lang.Boolean

BIT default 0

java.lang.Byte

SMALLINT

java.lang.Byte[]

IMAGE

java.lang.Integer

INTEGER

java.lang.Long

NUMERIC

java.lang.Float

FLOAT(16)

java.lang.Double

FLOAT(32)

java.lang.Short

SMALLINT

java.lang.String

VARCHAR

java.lang.Character

CHAR

java.lang.Character[]

TEXT

java.math.BigDecimal

NUMERIC

java.math.BigInteger

NUMERIC

java.sql.Date

DATETIME

java.sql.Time

DATETIME

java.sql.Timestamp

DATETIME

Table B-5 Microsoft Access field types  
Class Data Type

java.lang.Boolean

SHORT

java.lang.Byte

SHORT

java.lang.Byte[]

LONGBINARY

java.lang.Integer

LONG

java.lang.Long

DOUBLE

java.lang.Float

DOUBLE

java.lang.Double

DOUBLE

java.lang.Short

SHORT

java.lang.String

TEXT

java.lang.Character

TEXT

java.lang.Character[]

LONGTEXT

java.math.BigDecimal

DOUBLE

java.math.BigInteger

DOUBLE

java.sql.Date

DATETIME

java.sql.Time

DATETIME

java.sql.Timestamp

DATETIME

Session management services

TopLink provides statistics reporting and runtime configuration systems. There are two publicly-available APIs, oracle.toplink.service.RuntimeServices and oracle.toplink.services.DevelopmentServices.

RuntimeServices

The RuntimeServices API facilitates the monitoring of a running in-production system. It gives access to a number of 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 sub-cache.

For more information, see the topic on the RuntimeServices class in the JavaDoc for the TopLink Foundation Library API.

DevelopmentServices

The DevelopmentServices API enables developers to make potentially dangerous changes to a running non-production application. For example, DevelopmentServices API can be used to change the states of selected objects and modify and reinitialize identity maps.

This can be particularly useful for stress and performance testing pre-production applications, as well as offering the opportunity fast and easy prototyping.

For more information, see the topic on the RuntimeServices class in the JavaDoc for the TopLink Foundation Library API.

Using session management services

The session management service classes can be instantiated by passing a session to the constructor. After the service is instantiated, a graphical interface or an application can be attached to the object to provide statistical feedback and runtime option settings.

TopLink also ships with the session management services implemented as MBeans that can be deployed in applications and interfaced according to the MBean specification. TopLink does not currently provide any GUI interfaces into this API.

Example B-3 Implementing session management services as MBeans

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

TopLink support for BEA WebLogic Server automatically deploys the session management services to the JMX server. The JMX Mbeans can be retrieved with the following object names:

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

The <Session><Name> is the session and name under which the required session configuration stored in the toplink-ejb-jar.xml file.

The stored procedure generator

It is now possible to generate stored procedures based on the dynamic SQL generated for descriptors and mappings. After the stored procedures are generated, they can be attached to the mappings and descriptors of the domain object. In other words, the access to the database is through stored procedures and no longer through SQL.


Note:

Because of the nature of this feature, it has a number of limitations. It should be used only where database access is restricted to stored procedures, and not to enhance performance.


The stored procedure generator is split into two sections that are performed at development time. The first is the generation of the stored procedures, and the second is the attachment of the procedures to the descriptors and mappings.

Generation of stored procedures

Stored procedures can be generated for all descriptors and most relationship mappings.

There are two exceptions to this rule:

As well as descriptors and mappings, stored procedures are also generated for updates and selects of sequence numbers.

To tell TopLink to use these stored procedures whenever actions are performed on this class, an amendment class is created. This class contains a method that attaches the stored procedures to each descriptor.

Example B-4 Stored procedures generated directly on the database

An amendment class called com.demo.Tester is created in the file
C:/temp/Tester.java.

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

Example B-5 Generating stored procedures to a file

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

Attaching the stored procedures to the descriptors

After the stored procedures are created successfully on the database and the amendment file is created, the descriptors can be told to use these descriptors.

The Session Console

The session console is a tool to test descriptors, test logging in to the database, and view the performance of reading objects described by the descriptors from the database. Ideally, you should create a project using TopLink Mapping Workbench and use the session console to test the project file before doing further development.

Requirements

Make sure toplink.jar, toplinksdk.jar, toplinksdkxerces.jar, xerces.jar, and tools.jar are in your CLASSPATH (see Oracle9iAS TopLink Getting Started).

The session console is compatible with Swing (JFC) 1.02, Swing 1.03, and Java 2.

Using session console features

  1. Start the session console.

    • If you are using IBM VisualAge for Java, run oracle.toplink.tools.sessionconsole
      .SessionConsole in the "TopLink Development Tools" project.

    OR

    • If you are using Windows or Windows NT, run Session Console in the "TopLink for Java Foundation Library" application group.

    OR

    • If you are using Windows or Windows NT, run the "SessionConsole.cmd" file from the <INSTALL_DIR>\core directory.

    OR

    • Enter the following text at the command line:

      <INSTALL_DIR>\core\SessionConsole
      
      
  2. Select File > Load Project, then select the deployed XML project file you want to load (for example, Employee.xml).

  3. Click the Login tab, fill in the Login information, and click the Login button.

    Figure B-1 TopLink Session Inspector--Login

    Text description of sesscons.gif follows.

    Text description of the illustration sesscons.gif

  4. To test reading all of the objects described by a descriptor from the database, select a descriptor and click the "Execute Query" button from the "Query" tab.

    The session console executes the ReadAllQuery and displays the results in the Results pane.

    Figure B-2 TopLink Session Inspector--Query

    Text description of sessconr.gif follows.

    Text description of the illustration sessconr.gif

  5. To view the performance of executing queries, check the Profile checkbox in the Log pane, and then repeat Step 4 for one or more descriptors.

  6. Click the Browse Profile button in the Log pane to see the results. The total time is measured in milliseconds.

    Figure B-3 TopLink Profile Browser

    Text description of probrows.gif follows.

    Text description of the illustration probrows.gif

  7. If you are using IBM VisualAge for Java, inspect the object that was read.

    1. Click the Cache tab.

    2. Select a descriptor that has objects displayed in the Cache pane.

    3. Select the object to be inspected and click the Inspect (VA) button.

  8. If desired, execute SQL clauses in the SQL pane and view the result in the Result pane. Type the SQL clause, highlight this clause, and click either the Select button or the Update button.

    For example, an SQL clause to select all fields from Employee:

    SELECT * FROM EMPLOYEE 
    


Note:

If your database contains important information, do not execute any SQL clause that modifies the database.


Launching the session console from code

The session console can also be launched from code. When debugging, you can launch the session console in your application. The session console can browse any of the TopLink sessions.

Example B-6 Launching the session console

SessionConsole.browse(toplinkSession);

The Performance Profiler

The performance profiler detects performance bottlenecks in a TopLink application. When it is enabled, the profiler logs a summary of the performance statistics for every query executed. The profiler also allows for a summary of all executed queries to be logged for a profile session.

The profiler currently logs the following information:

Using the profiler

To invoke the profiler from the database session, use the setProfiler(new PerformanceProfiler()) method. To end a profiling session, use the clearProfiler() method.

The profiler is an instance of the PerformanceProfiler class, found in oracle.toplink.tools.profiler It can be accessed by calling the session's getProfiler() function.

The profiler supports the following public API:

Example B-7 The execution of a read query

session.setProfiler(new PerformanceProfiler());
Vector employees = session.readAllObjects(Employee.class);

The output generated by the profiler for the code is:

Begin Profile of{
ReadAllQuery(oracle.toplink.demos.employee.domain.Employee)Profile(ReadAllQuery,
,# of obj=12,time=1399,sql execute=217,prepare=495,row 
fetch=390,time/obj=116,obj/sec=8)
} End Profile

Browsing the profiler results

The profiler results can be browsed graphically using the profile browser. The profile browser can be launched from code from your application. The profile browser is found in the
oracle.toplink.tools.sessionconsoleConsole package.

Example B-8 Launching the profile browser

ProfileBrowser.browseProfiler(session.getProfiler());

Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Solution Area
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index