Oracle9iAS TopLink Foundation Library Guide Release 2 (9.0.3) Part Number B10064-01 |
|
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 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.
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.
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.
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.
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.
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)
The following example shows the table creation mechanism taken from the TopLink Employee Demo.
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;}
Tables are created by passing the initialized TableDefinition object to the DatabaseSession's schema manager.
TopLink provides two separate methods for creating tables.
SchemaManager schemaManager = new SchemaManager(session);
schemaManager.createObject(Tables.employeeTable());
schemaManager.replaceObject(Tables.addressTable());
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.
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).
TopLink provides statistics reporting and runtime configuration systems. There are two publicly-available APIs, oracle.toplink.service.RuntimeServices and oracle.toplink.services.DevelopmentServices.
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.
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.
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.
import oracle.toplink.services.RuntimeServices; import oracle.toplink.publicinterface.Session; ... ... RuntimeServices service = newRuntimeServices ((session) session); java.util.List classNames = service.getClassesInSession();
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.
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.
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.
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.
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");
SchemaManager manager = new SchemaManager(session); manager.outputDDLToFile("C:\Temp\test.sql"); manager.generateStoredProceduresAndAmendmentClass("C:/temp/", "com.demo.Tester");
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.
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 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.
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.
OR
OR
<INSTALL_DIR>
\core
directory.
OR
The session console executes the ReadAllQuery and displays the results in the Results pane.
For example, an SQL clause to select all fields from Employee:
SELECT * FROM EMPLOYEE
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.
SessionConsole.browse(toplinkSession);
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:
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:
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
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.
ProfileBrowser.browseProfiler(session.getProfiler());
|
Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|