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

• Session management services

• The stored procedure generator

• The Session Console

• The Performance Profiler

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.

• The createObject() method creates a new table on the database based on the table definition.

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

• The replaceObject() method destroys and recreates the schema entity on the database.

  schemaManager.replaceObject(Tables.addressTable());
  

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:

• Many to many mappings are not supported by the stored procedure generator.

• Stored procedures for Read operations are not generated for the Oracle platform.

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.

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

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

  This method sets up all the descriptors to use the procedures that were generated previously.

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.

• If you are using JDK 1.1, you must install Swing and ensure that it is on your CLASSPATH correctly.

• The JDK 1.2 (Java 2) version of TopLink provides a version of the session console that is compatible with the JDK 1.2 version of Swing. Make sure you are using the JDK 1.2 version of TopLink when using JDK 1.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 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 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 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:

• The query type and arguments

• The total execution time of the query (in milliseconds)

• The total number of objects affected

• The number of objects handled per second

• The number of milliseconds per object

• The total time spent in the object cache

• The total time spent on preparing the SQL

• The total time spent on executing the SQL

• The total time spent on fetching rows

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:

• logProfile(): sets whether, after each query execution, the profile result should be logged; by default this is true

• dontLogProfile(): sets log profile to false

• setShouldLogProfile(boolean value): sets log profile to `passed' in boolean value

• logProfileSummaryByClass(): logs the profile summary by class

• logProfileSummaryByQuery(): logs the profile summary by query

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());