he Java Persistence API (JPA), part of the Java Enterprise Edition 5 (Java EE 5) Enterprise Java Beans (EJB) 3.0 specification, greatly simplifies Java persistence and provides an object-relational mapping approach that allows you to declaratively define how to map Java objects to relational database tables in a standard, portable way that works both inside a Java EE 5 application server and outside an EJB container in a Java Standard Edition (Java SE) 5 application.

TopLink Essentials is the JPA provider for the EJB 3.0 Reference Implementation. In addition to being JPA compliant, it also provides additional extensions beyond what is defined in the JPA specification.

This document summarizes these JPA extensions and explains where and how you use them to customize JPA behavior to meet your application requirements.

For more information, see:

TopLink JPA Persistence Unit Extensions

A persistence unit configures various details that are required when you acquire an entity manager. You specify a persistence unit by name when you acquire an entity manager factory.

You configure persistence units in JPA persistence descriptor file persistence.xml.

In this file, you can specify the vendor extensions that this reference describes by using a <properties> element. Example 1-1 shows how to set a TopLink JPA persistence unit extension in a persistence.xml file for a Java EE application and Example 1-2 shows how to do the same for a Java SE application.

Example 1-1 Configuring a Vendor Extension in the Persistence.xml File (Java EE)

<persistence-unit name="default" transaction-type="JTA">
    <provider>
        oracle.toplink.essentials.PersistenceProvider
    </provider>
    <jta-data-source>
        jdbc/MyDataSource
    </jta-data-source>
    <properties>
        <property name="toplink.logging.level" value="INFO"/>
    </properties>
</persistence-unit>

Example 1-2 Configuring a Vendor Extension in the Persistence.xml File (Java SE)

<persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
    <provider>
        oracle.toplink.essentials.PersistenceProvider
    </provider>
    <exclude-unlisted-classes>false</exclude-unlisted-classes>
    <properties>
        <property name="toplink.logging.level" value="INFO"/>
        <property name="toplink.jdbc.driver" value="oracle.jdbc.OracleDriver"/>
        <property name="toplink.jdbc.url" value="jdbc:oracle:thin:@myhost:1521:MYSID"/>
        <property name="toplink.jdbc.password" value="tiger"/>
        <property name="toplink.jdbc.user" value="scott"/>
    </properties>
</persistence-unit>

Alternatively, you can set a vendor extensions in the Map of properties you pass into a call to javax.persistence.Persistence method createEntityManagerFactory as Example 1-3 shows. You can override extensions set in the persistence.xml file in this way. When you set an extension in a Map of properties, you can set the value using the public static final field in the appropriate configuration class in oracle.toplink.essentials.config, including:

Example 1-3 shows how to set the value of extension toplink.cache.type.default using the CacheType configuration class.

Example 1-3 Configuring a Vendor Extension When Creating an EntityManagerFactory

import oracle.toplink.essentials.config.CacheType;

Map properties = new HashMap();
properties.put(TopLinkProperties.CACHE_TYPE_DEFAULT, CacheType.Full);
EntityManagerFactory emf = Persistence.createEntityManagerFactory("default", properties);

This section describes the TopLink JPA vendor extensions that you can define in a persistence unit, including:

You may specify any TopLink JPA extension in a persistence.xml file and you may pass any TopLink JPA extension into Persistence method createEntityManagerFactory.

Currently, no TopLink JPA extensions are applicable to EntityManagerFactory method createEntityManager.

TopLink JPA Extensions for JDBC (Java SE)

Table 1-1 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure JDBC driver parameters. These extensions apply only when used outside of a EJB container.

Table 1-1 TopLink JPA Extensions for JDBC (Java SE)

Property Usage Default

toplink.jdbc.bind-parameters

Control whether or not the query uses parameter binding.

For more information, see "Parameterized SQL (Binding) and Prepared Statement Caching".

Valid values:

  • true - bind all parameters.

  • false - do not bind parameters.

Example: persistence.xml file

<property name="toplink.jdbc.bind-parameters" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_BIND_PARAMETERS, "true");

true

toplink.jdbc.driver

The class name of the JDBC driver you want to use, fully qualified by its package name. This class must be on your application classpath.

Example: persistence.xml file

<property name="toplink.jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_DRIVER, "oracle.jdbc.driver.OracleDriver");

toplink.jdbc.password

The password for your JDBC user.

Example: persistence.xml file

<property name="toplink.jdbc.password" value="tiger"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_PASSWORD, "tiger");

toplink.jdbc.read-connections.max

The maximum number of connections allowed in the JDBC read connection pool.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Example: persistence.xml file

<property name="toplink.jdbc.read-connections.max" value="3"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_MAX, "3");

2

toplink.jdbc.read-connections.min

The minimum number of connections allowed in the JDBC read connection pool.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Example: persistence.xml file

<property name="toplink.jdbc.read-connections.min" value="1"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_MIN, "1");

2

toplink.jdbc.read-connections.shared

Specify whether or not to allow concurrent use of shared read connections.

Valid values:

  • true - allow concurrent use of shared read connections.

  • false - do not allow the concurrent use of shared read connections; concurrent readers are each allocated their own read connection.

Example: persistence.xml file

<property name="toplink.jdbc.read-connections.shared" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_READ_CONNECTIONS_SHARED, "true");

false

toplink.jdbc.url

The JDBC connection URL required by your JDBC driver.

Example: persistence.xml file

<property name="toplink.jdbc.url" value="jdbc:oracle:thin:@MYHOST:1521:MYSID"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_URL, "jdbc:oracle:thin:@MYHOST:1521:MYSID");

toplink.jdbc.user

The user name for your JDBC user.

Example: persistence.xml file

<property name="toplink.jdbc.url" value="scott"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_USER, "scott");

toplink.jdbc.write-connections.max

The maximum number of connections allowed in the JDBC write connection pool.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Example: persistence.xml file

<property name="toplink.jdbc.write-connections.max" value="5"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_WRITE_CONNECTIONS_MAX, "5");

10

toplink.jdbc.write-connections.min

The maximum number of connections allowed in the JDBC write connection pool.

Valid values: 0 to Integer.MAX_VALUE (depending on your JDBC driver) as a String.

Example: persistence.xml file

<property name="toplink.jdbc.write-connections.min" value="2"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.JDBC_WRITE_CONNECTIONS_MIN, "2");

5


TopLink JPA Extensions for Caching

Table 1-2 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure the TopLink cache.

For more information, see "Understanding the TopLink Cache".

Table 1-2 TopLink JPA Extensions for Caching

Property Usage Default

toplink.cache.type.default

The default type of session cache.

A session cache is a shared cache that services clients attached to a given session. When you read objects from or write objects to the data source using a client session, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to child client sessions.

Valid values: oracle.toplink.essentials.config.CacheType

  •  

    Full - This option provides full caching and guaranteed identity: objects are never flushed from memory unless they are deleted.

     

    For more information, see Full Identity Map

  •  

    HardWeak - This option is similar to Weak except that it maintains a most frequently used subcache that uses hard references.

     

    For more information, see Hard Cache Weak Identity Maps

  •  

    NONE - This option does not preserve object identity and does not cache objects. Oracle does not recommend using this option.

     

    For more information, see No Identity Map.

  •  

    SoftWeak - This option is similar to Weak except that it maintains a most frequently used subcache that uses soft references. Oracle recommends using this identity map in most circumstances as a means to control memory used by the cache.

     

    For more information, see Soft Cache Weak Identity Maps.

  •  

    Weak - This option is similar to Full, except that objects are referenced using weak references. This option uses less memory than Full, but does not provide a durable caching strategy across client/server transactions. Oracle recommends using this identity map for transactions that, once started, stay on the server side.

     

    For more information, see Weak Identity Map.

Example: persistence.xml file

<property name="toplink.cache.type.default" value="Full"/>

Example: property Map

import oracle.toplink.essentials.config.CacheType;
import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.CACHE_TYPE_DEFAULT, CacheType.Full);

SoftWeak

toplink.cache.size.default

The default maximum number of objects allowed in a TopLink cache.

Valid values: 0 to Integer.MAX_VALUE as a String.

Example:

<property name="toplink.cache.size.default" value="5000"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.CACHE_SIZE_DEFAULT, 1000);

1000

toplink.cache.shared.default

The default for whether or not the TopLink session cache is shared by multiple client sessions.

Valid values:

  • true - The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.

  • false - The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.

Example:

<property name="toplink.cache.shared.default" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.CACHE_SHARED_DEFAULT, "true");

true

toplink.cache.type.<ENTITY>

The type of session cache for the JPA entity named <ENTITY>.

For more information on entity names, see @Entity.

Valid values: oracle.toplink.essentials.config.CacheType

Example: persistence.xml file

<property name="toplink.cache.type.Order" value="Full"/>

Example: property Map

import oracle.toplink.essentials.config.CacheType
import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.CACHE_TYPE+".Order", CacheType.Full);

SoftWeak

toplink.cache.size.<ENTITY>

The maximum number of JPA entities of the type denoted by JPA entity name <ENTITY> allowed in a TopLink cache.

For more information on entity names, see @Entity.

Valid values: 0 to Integer.MAX_VALUE as a String.

Example:

<property name="toplink.cache.size.Order" value="5000"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.CACHE_SIZE+".Order", 1000);

1000

toplink.cache.shared.<ENTITY>

Whether or not the TopLink session cache is shared by multiple client sessions for JPA entities of the type denoted by JPA entity name <ENTITY>.

For more information on entity names, see @Entity.

Valid values:

  • true - The session cache services all clients attached to the session. When you read objects from or write objects to the data source using a client session, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to all other processes in the session.

  • false - The session cache services a single, isolated client exclusively. The isolated client can reference objects in a shared session cache but no client can reference objects in the isolated client's exclusive cache.

Example:

<property name="toplink.cache.shared.Order" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(ToplinkProperties.CACHE_SHARED+".Order", "true");

true


TopLink JPA Extensions for Logging

Table 1-3 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure TopLink logging.

For more information, see "Logging".

Table 1-3 TopLink JPA Extensions for Logging

Property Usage Default

toplink.logging.logger

Select the type of logger to use:

Valid values:

  • DefaultLogger - the TopLink Essentials native logger oracle.toplink.essentials.logging.DefaultSessionLog.

  • JavaLogger - the java.util.logging logger oracle.toplink.essentials.logging.JavaLog.

  • Fully qualified class name of a custom logger. The custom logger must implement the oracle.toplink.essentials.logging.SessionLog interface.

Example: persistence.xml file

<property name="toplink.logging.logger" value="JavaLogger"/>
<property name="toplink.logging.logger" value="acme.loggers.MyCustomLogger" />

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
import oracle.toplink.essentials.config.LoggerType;
propertiesMap.put(TopLinkProperties.LOGGING_LOGGER, LoggerType.JavaLogger);
propertiesMap.put(TopLinkProperties.LOGGING_LOGGER, "acme.loggers.MyCustomLogger");

DefaultLogger

toplink.logging.level

Control the amount and detail of log output by configuring the log level (in ascending order of information):

Valid values: java.util.logging.Level

  • OFF - disable logging

  • SEVERE - Logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.

  • WARNING - Logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.

  • INFO - Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.

  • CONFIG - Logs only login, JDBC connection, and database information.

  • FINE - Logs SQL.

  • FINER - Similar to warning. Includes stack trace.

  • FINEST - Includes additional low level information.

Example: persistence.xml file

<property name="toplink.logging.level" value="WARNING"/>

Example: property Map

import java.util.logging.Level;
import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.LOGGING_LEVEL, Level.INFO);

INFO

toplink.logging.level.<CATEGORY>

Control the log level for a specific log category.

Valid <CATEGORY> values are defined in oracle.toplink.essentials.logging.SessionLog:

  • SQL - SQL logs
  • TRANSACTION - transaction related logs
  • EVENT - event related logs
  • CONNECTION - Session related logs
  • QUERY - DatabaseQuery related logs
  • CACHE - shared cache logs
  • SEQUENCING - sequencing generator logs
  • EJB - EJB logs
  • DMS - Oracle Dynamic Monitoring System related logs
  • EJB_OR_METADATA - metadata processing logs
  • WEAVER - class weaver logs
  • PROPERTIES - deployment-time properties handler logs

Valid values are defined in java.util.logging.Level.

If there is no category-specific level, the level set with toplink.logging.level (default: INFO) is used.

Example: persistence.xml file

<property name="toplink.logging.level.sql" value="WARNING"/>

Example: property Map

import java.util.logging.Level;
import oracle.toplink.essentials.config.TopLinkProperties;
import oracle.toplink.essentials.logging.SessionLog;
propertiesMap.put(TopLinkProperties.LOGGING_LEVEL+"."+SessionLog.SQL, Level.WARNING);
toplink.logging.level

toplink.logging.timestamp

Control whether the timestamp is logged in each log entry.

Valid values:

  • true - log a timestamp.

  • false - do not log a timestamp.

Example: persistence.xml file

<property name="toplink.logging.timestamp" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.LOGGING_TIMESTAMP, "true");

true

toplink.logging.thread

Control whether a thread identifier is logged in each log entry.

Valid values:

  • true - log a thread identifier.

  • false - do not log a thread identifier.

Example: persistence.xml file

<property name="toplink.logging.thread" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.LOGGING_THREAD, "true");

true

toplink.logging.session

Control whether a TopLink session identifier is logged in each log entry.

Valid values:

  • true - log a TopLink session identifier.

  • false - do not log a TopLink session identifier.

Example: persistence.xml file

<property name="toplink.logging.session" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.LOGGING_SESSION, "true");

true

toplink.logging.exceptions

Control whether the exceptions thrown from within the TopLink code are logged prior to returning the exception to the calling application. Ensures that all exceptions are logged and not masked by the application code.

Valid values:

  • true - log all exceptions.

  • false - do not log exceptions.

Example: persistence.xml file

<property name="toplink.logging.exceptions" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.LOGGING_EXCEPTIONS, "true");

false


TopLink JPA Extensions for Database, Session, and Application Server

Table 1-4 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure TopLink extensions for database, session, and application server.

Table 1-4 TopLink JPA Extensions for Database, Session, and Application Server

Property Usage Default

toplink.target-database

Specify the type of database that your JPA application uses. The TargetDatabase enum contains an entry for many of the more common database types supported.

Valid values: oracle.toplink.essentials.config.TargetDatabase

  • Attunity - configure the persistence provider to use an Attunity database.

  • Auto - TopLink accesses the database and uses the metadata that JDBC provides to determine the target database. Applicable to JDBC drives that support this metadata.

  • Cloudscape - configure the persistence provider to use a Cloudscape database.

  • Database - configure the persistence provider to use a generic choice if your target database is not listed here and your JDBC driver does not support the use of metadata that the Auto option requires.

  • DB2 - configure the persistence provider to use a DB2 database.

  • DB2Mainframe - configure the persistence provider to use a DB2Mainframe database.

  • DBase - configure the persistence provider to use a DBase database.

  • Derby - configure the persistence provider to use a Derby database.

  • HSQL - configure the persistence provider to use an HSQL database.

  • Informix - configure the persistence provider to use an Informix database.

  • JavaDB - configure the persistence provider to use a JavaDB database.

  • MySQL4 - configure the persistence provider to use a MySQL4 database.

  • Oracle - configure the persistence provider to use an Oracle database.

  • PointBase - configure the persistence provider to use a PointBase database.

  • PostgreSQL - configure the persistence provider to use a PostgreSQL database.

  • SQLAnyWhere - configure the persistence provider to use an SQLAnyWhere database.

  • SQLServer - configure the persistence provider to use an SQLServer database.

  • Sybase - configure the persistence provider to use a Sybase database.

  • TimesTen - configure the persistence provider to use a TimesTen database.

Example: persistence.xml file

<property name="toplink.target-database" value="Oracle"/>

Example: property Map

import oracle.toplink.essentials.config.TargetDatabase;
import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.TARGET_DATABASE, TargetDatabase.Oracle);

Auto

toplink.session-name

Specify the name by which the TopLink session is stored in the static session manager. Use this option if you need to access the TopLink shared session outside of the context of the Java Persistence API.

Valid values: a valid TopLink session name that is unique in a server deployment.

Example: persistence.xml file

<property name="toplink.session-name" value="MySession"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.SESSION_NAME, "MySession");

TopLink generated unique name.

toplink.target-server

Specify the type of application server that your JPA application uses:

Valid values: oracle.toplink.essentials.config.TargetServer

  • None - configure the persistence provider to use no application server.

  • OC4J_10_1_3 - configure the persistence provider to use OC4J 10.1.3.0.

  • SunAS9 - configure the persistence provider to use Sun Application Server version 9.

Example: persistence.xml file

<property name="toplink.target-server" value="OC4J_10_1_3"/>

Example: property Map

import oracle.toplink.essentials.config.TargetServer;
import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.TARGET_SERVER, TargetServer.OC4J_10_1_3);

None


TopLink JPA Extensions for Customization

Table 1-5 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure TopLink customization and validation.

Table 1-5 TopLink JPA Extensions for Customization and Validation

Property Usage Default

toplink.orm.throw.exceptions

Specify whether or not TopLink JPA should throw an exception or log a warning when it encounters a problem with any of the files listed in a persistence.xml file <mapping-file> element.

Valid values:

  • true - throw exceptions.

  • false - log warning only.

Example: persistence.xml file

<property name="oracle.orm.throw.exceptions" value="false"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.TOPLINK_ORM_THROW_EXCEPTIONS, "false");

true

toplink.weaving

Control whether or not the weaving of the entity classes is performed. Weaving is required in order to use lazy fetching of @OneToOne and @ManyToOne relationships.

Valid values:

  • true - weave entity classes.

  • false - do not weave entity classes.

  • static - weave entity classes statically.

     

    Use this option if you plan to execute your application outside of a Java EE 5 container in an environment that does not permit the use of -javaagent:toplink-essentials-agent.jar on the JVM command line.

For more information, including the option of using the TopLink JPA weave Ant task, see TopLink JPA Lazy Loading.

Example: persistence.xml file

<property name="toplink.weaving" value="true"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.WEAVING, "true");

true

toplink.session.customizer

Specify a TopLink session customizer class: a Java class that implements the oracle.toplink.essentials.tools.sessionconfiguration.SessionCustomizer interface and provides a default (zero-argument) constructor. Use this class's customize method, which takes an oracle.toplink.essentials.sessions.Session, to programmatically access advanced TopLink session API.

For more information, see "Session Customization".

Valid values: class name of a SessionCustomizer class fully qualified by its package name.

Example: persistence.xml file

<property name="toplink.session.customizer" value="acme.sessions.MySessionCustomizer"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.SESSION_CUSTOMIZER, "acme.sessions.MySessionCustomizer");

toplink.descriptor.customizer.<ENTITY>

Specify a TopLink descriptor customizer class: a Java class that implements the oracle.toplink.essentials.tools.sessionconfiguration.DescriptorCustomizer interface and provides a default (zero-argument) constructor. Use this class's customize method, which takes an oracle.toplink.essentials.descriptors.ClassDescriptor, to programmatically access advanced TopLink descriptor and mapping API for the descriptor associated with the JPA entity named <ENTITY>.

For more information on entity names, see @Entity.

For more information on TopLink descriptors, see:

Valid values: class name of a DescriptorCustomizer class fully qualified by its package name.

Example: persistence.xml file

<property name="toplink.descriptor.customizer.Order" value="acme.sessions.MyDescriptorCustomizer"/>

Example: property Map

import oracle.toplink.essentials.config.TopLinkProperties;
propertiesMap.put(TopLinkProperties.DESCRIPTOR_CUSTOMIZER+".Order", "acme.sessions.MyDescriptorCustomizer");


TopLink JPA Extensions for Schema Generation

Table 1-6 lists the TopLink JPA extensions that you can define in a persistence.xml file to configure schema generation.

Table 1-6 TopLink JPA Extensions for Schema Generation

Property Usage Default

toplink.ddl-generation

Specify what Data Descriptor Language (DDL) generation action you want for your JPA entities. To specify the DDL generation target, see toplink.ddl-generation.output-mode.

Valid values: oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider

If you are using persistence outside the EJB container and would like to create the DDL files without creating tables, additionally define a Java system property INTERACT_WITH_DB and set its value to false.

Example: persistence.xml file

<property name="toplink.ddl-generation" value="create-tables"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION, EntityManagerFactoryProvider.CREATE_ONLY);

none

toplink.application-location

Specify where TopLink should write generated DDL files (see toplink.create-ddl-jdbc-file-name and toplink.drop-ddl-jdbc-file-name). Files are written iftoplink.ddl-generation is set to anything other than none.

Valid values: a file specification to a directory in which you have write access. The file specification may be relative to your current working directory or absolute. If it does not end in a file separator, TopLink will append one valid for your operating system.

Example: persistence.xml file

<property name="toplink.application-location" value="C:\ddl\"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.APP_LOCATION, "C:\ddl\");

"."+File.separator

toplink.create-ddl-jdbc-file-name

Specify the file name of the SQL file that TopLink generates containing SQL statements to create tables for JPA entities. This file is written to the location specified bytoplink.application-location when toplink.ddl-generation is set to create-tables or drop-and-create-tables.

Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of toplink.application-location +toplink.create-ddl-jdbc-file-name is a valid file specification for your operating system.

Example: persistence.xml file

<property name="toplink.create-ddl-jdbc-file-name" value="create.sql"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.CREATE_JDBC_DDL_FILE, "create.sql");

createDDL.jdbc

toplink.drop-ddl-jdbc-file-name

Specify the file name of the SQL file that TopLink generates containing the SQL statements to drop tables for JPA entities. This file is written to the location specified bytoplink.application-location when toplink.ddl-generation is set to drop-and-create-tables

Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of toplink.application-location +toplink.drop-ddl-jdbc-file-name is a valid file specification for your operating system.

Example: persistence.xml file

<property name="toplink.drop-ddl-jdbc-file-name" value="drop.sql"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.DROP_JDBC_DDL_FILE, "drop.sql");

dropDDL.jdbc

toplink.ddl-generation.output-mode

Use this property to specify the DDL generation target.

Valid values: oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider

Example: persistence.xml file

<property name="toplink.ddl-generation.output-mode" value="database"/>

Example: property Map

import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider;
propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION_MODE, EntityManagerFactoryProvider.DDL_DATABASE_GENERATION);

  • In Java EE mode (whencreateContainerEntityManagerFactoryis called), default is: sql-script



    NOTE: This setting may be overridden by containers with specific TopLink support. Please see your container documentation for details.



  • In Java SE mode (whencreateEntityManagerFactory is called), default is: both


TopLink JPA Query Customization Extensions

This section describes:

TopLink JPA Query Hints

Table 1-7 lists the TopLink JPA query hints that you can specify when you construct a JPA query as Example 1-4 shows or when you specify a JPA query using the @QueryHint annotation as Example 1-5 shows.

When you set a hint, you can set the value using the public static final field in the appropriate configuration class in oracle.toplink.essentials.config, including:

Example 1-4 and Example 1-5 shows how to set the value of hint toplink.jdbc.bind-parameters using the TopLinkQueryHints configuration class to set the name of the hint and the HintValues configuration class to set the value.

Example 1-4 Specifying a TopLink JPA Query Hint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;

Customer customer = (Customer)entityMgr.createNamedQuery("findCustomerBySSN"). setParameter("SSN", "123-12-1234").setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.PERSISTENCE_UNIT_DEFAULT).getSingleResult();

Example 1-5 Specifying a TopLink JPA Query Hint With @QueryHint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;

@Entity
@NamedQuery(
    name="findAllEmployees",
    query="SELECT * FROM EMPLOYEE WHERE MGR=1"
    hints={
        @QueryHint={name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.PERSISTENCE_UNIT_DEFAULT}
    }
)
public class Employee implements Serializable {
    ...
}

Table 1-7 TopLink JPA Query Hints

Hint Usage Default

toplink.jdbc.bind-parameters

Control whether or not the query uses parameter binding.

For more information, see "Parameterized SQL (Binding) and Prepared Statement Caching".

Valid values: oracle.toplink.essentials.config.HintValues

  • true - bind all parameters.

  • false - do not bind all parameters.

  • PersistenceUnitDefault - use the parameter binding setting made in your TopLink session's database login.

     

    For more information, see "Configuring JDBC Options".

Example: JPA Query API

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;
query.setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.TRUE);

Example: @QueryHint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TargetDatabase;
@QueryHint(name=TopLinkQueryHints.BIND_PARAMETERS, value=HintValues.PERSISTENCE_UNIT_DEFAULT);

PersistenceUnitDefault

toplink.pessimistic-lock

Control whether or not pessimistic locking is used.

Valid values: oracle.toplink.essentials.config.PessimisticLock

  • NoLock - pessimistic locking is not used.

  • Lock - TopLink issues a SELECT .... FOR UPDATE.

  • LockNoWait - TopLink issues a SELECT .... FOR UPDATE NO WAIT.

Example: JPA Query API

import oracle.toplink.essentials.config.PessimisticLock;
import oracle.toplink.essentials.config.TopLinkQueryHints;
query.setHint(TopLinkQueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);

Example: @QueryHint

import oracle.toplink.essentials.config.PessimisticLock;
import oracle.toplink.essentials.config.TopLinkQueryHints;
@QueryHint(name=TopLinkQueryHints.PESSIMISTIC_LOCK, value=PessimisticLock.LockNoWait);

NoLock

toplink.refresh

Control whether or not to update the TopLink session cache with objects that the query returns.

Valid values: oracle.toplink.essentials.config.HintValues

  • true - refresh cache.

  • false - do not refresh cache.

Example: JPA Query API

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;
query.setHint(TopLinkQueryHints.REFRESH, HintValues.TRUE);

Example: @QueryHint

import oracle.toplink.essentials.config.HintValues;
import oracle.toplink.essentials.config.TopLinkQueryHints;
@QueryHint(name=TopLinkQueryHints.REFRESH, value=HintValues.TRUE);

false

toplink.refresh.cascade

Control whether or not to update the TopLink session cache with entities associated with the objects that the query returns. Applicable only when toplink.refresh is set to true.

Valid values: oracle.toplink.essentials.config.CascadePolicy

  • NoCascading - do not cascade at all.

  • CascadePrivateParts - cascade to private-owned associations where the associations are configured using a descriptor customizer class (see toplink.descriptor.customizer.<ENTITY>) to call oracle.toplink.essentials.mappings.ForeignReferenceMapping method privateOwnedRelationship or setIsPrivateOwned(true).

  • CascadeAllParts - cascade to all associations.

  • CascadeByMapping - cascade by mapping metadata.

Example: JPA Query API

import oracle.toplink.essentials.config.CascadePolicy;
import oracle.toplink.essentials.config.TopLinkQueryHints;
query.setHint(TopLinkQueryHints.REFRESH_CASCADE, CascadePolicy.CascadePrivateParts);

Example: @QueryHint

import oracle.toplink.essentials.config.CascadePolicy;
import oracle.toplink.essentials.config.TopLinkQueryHints;
@QueryHint(name=TopLinkQueryHints.REFRESH_CASCADE, value=CascadePolicy.CascadePrivateParts);
CascadeByMapping

Using TopLink Query API in JPA Queries

TopLink JPA provides a TopLink implementation class for each JPA persistence interface. By casting to the TopLink implementation class, you have full access to TopLink functionality.

This section provides the following examples:

For more information, see "Understanding TopLink Query API".

Creating a JPA Query Using the TopLink Expressions Framework

TopLink provides an expression framework with which you can express queries in a database-neutral fashion as an alternative to raw SQL.

Example 1-6 shows how to cast an entity manager to access a TopLink persistence provider createQuery method that takes a TopLink Expression.

Example 1-6 Creating a Query With the TopLink Expressions Framework

((oracle.toplink.essentials.ejb.cmp3.EntityManager)entityManager.getDelegate()).createQuery(Expression expression, Class resultType);

TopLink expressions offer the following advantages over SQL when you access a database:

  • Expressions are easier to maintain because the database is abstracted.

  • Changes to descriptors or database tables do not affect the querying structures in the application.

  • Expressions enhance readability by standardizing the Query interface so that it looks similar to traditional Java calling conventions.

    For example, the Java code required to get the street name from the Address object of the Employee class looks like this:

    emp.getAddress().getStreet().equals("Meadowlands");

    The expression to get the same information is similar:

    emp.get("address").get("street").equal("Meadowlands");

  • Expressions allow read queries to transparently query between two classes that share a relationship. If these classes are stored in multiple tables in the database, TopLink automatically generates the appropriate join statements to return information from both tables.

  • Expressions simplify complex operations.

    For example, the following Java code retrieves all employees that live on "Meadowlands" whose salary is greater than 10,000:

    ExpressionBuilder emp = new ExpressionBuilder();
Expression exp = emp.get("address").get("street").equal("Meadowlands");
Vector employees = session.readAllObjects(Employee.class,
exp.and(emp.get("salary").greaterThan(10000)));

    TopLink automatically generates the appropriate SQL from that code:

    SELECT t0.VERSION, t0.ADDR_ID, t0.F_NAME, t0.EMP_ID, t0.L_NAME, t0.MANAGER_ID, t0.END_DATE, t0.START_DATE, t0.GENDER, t0.START_TIME, t0.END_TIME,t0.SALARY FROM EMPLOYEE t0, ADDRESS t1 WHERE (((t1.STREET = 'Meadowlands')AND (t0.SALARY > 10000)) AND (t1.ADDRESS_ID = t0.ADDR_ID))

For more information, see "Understanding the TopLink Expressions Framework".

Creating a JPA Query Using a TopLink DatabaseQuery

A TopLink DatabaseQuery is a query object that provides a rich API for handling a variety of database query requirements, including reading and writing at the object level and at the data level.

For more information, see "Understanding the TopLink DatabaseQuery".

Example 1-7 shows how to cast a JPA query from an entity manager to access a TopLink persistence provider setDatabaseQuery method that takes a TopLink DatabaseQuery.

Example 1-7 DatabaseQuery

((oracle.toplink.essentials.ejb.cmp3.EJBQuery)query).setDatabaseQuery(DatabaseQuery query);

Example 1-8 shows how to cast a JPA query from an entity manager to access a TopLink persistence provider setDatabaseQuery method that takes a TopLink DataReadQuery initialized with a TopLink SQLCall object that specifies a SELECT. This query will return one or more objects.

Example 1-8 DatabaseQuery with Selecting Call

((oracle.toplink.essentials.ejb.cmp3.EJBQuery)query).setDatabaseQuery(new DataReadQuery(new SQLCall("SELECT...")));

Example 1-9 shows how to cast a JPA query from an entity manager to access a TopLink persistence provider setDatabaseQuery method that takes a TopLink DataModifyQuery initialized with a TopLink SQLCall object that specifies an UPDATE. This query will modify one or more objects.

Example 1-9 DatabaseQuery with Non-Selecting Call

((oracle.toplink.essentials.ejb.cmp3.EJBQuery)query).setDatabaseQuery(new DataModifyQuery(new SQLCall("UPDATE...")));

Creating a JPA Query Using a TopLink Call Object

Using DatabaseQuery method setCall, you can define your own TopLink Call to accommodate a variety of data source options such as SQL stored procedures and stored functions, EJB QL queries, and EIS interactions.

Example 1-10 shows how to cast a JPA query from an entity manager to access a TopLink persistence provider getDatabaseQuery method to set a new SQLCall.

Example 1-10 Call

((oracle.toplink.essentials.ejb.cmp3.EJBQuery)query).getDatabaseQuery().setCall(new SQLCall("..."));

For more information, see "Understanding TopLink Call Queries".

Using Named Parameters in a Native Query

Using TopLink Essentials, you can specify a named parameter in a native query using the TopLink # convention (see Example 1-11).

Support for the TopLink # convention is helpful if you are already familiar with TopLink queries or if you are migrating TopLink queries to a JPA application.

Example 1-11 Specifying a Named Parameter With #

Query queryEmployees = entityManager.createNativeQuery(
    "SELECT OBJECT(emp) FROM Employee emp WHERE emp.firstName = #firstname"
);
queryEmployeeByFirstName.setParameter("firstName", "Joan");
Collection employees = queryEmployees.getResultList();

Using Java Persistence Query Language Positional Parameters in a Native Query

Using TopLink Essentials, you can specify positional parameters in a native query using the Java Persistence Query Language positional parameter convention ?n to specify a parameter by number.

Example 1-12 shows how to specify positional parameters using the ?n convention. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%".

Example 1-12 Specifying Positional Parameters Using ?

Query queryEmployees = entityManager.createNativeQuery(
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?2", Employee.class
);
queryEmployees.setParameter(1, "D%");
queryEmployees.setParameter(2, "C%");
Collection employees = queryEmployees.getResultList();

You can easily re-use the same parameter in more than one place in the query as Example 1-13 shows. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%".

Example 1-13 Specifying Positional Parameters Using ?n

Query queryEmployees = entityManager.createNativeQuery(
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ?1 AND L_NAME LIKE ?1", Employee.class
);
queryEmployees.setParameter(1, "D%");
Collection employees = queryEmployees.getResultList();

Using JDBC-Style Positional Parameters in a Native Query

Using TopLink Essentials, you can specify positional parameters in a native query using the JDBC-style positional parameter ? convention.

Example 1-14 shows how to specify positional parameters using the ? convention. Each occurrence of ? must be matched by a corresponding setParameter call. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "C%".

Example 1-14 Specifying Positional Parameters With ?

Query queryEmployees = entityManager.createNativeQuery(
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class
);
queryEmployees.setParameter(1, "D%");
queryEmployees.setParameter(2, "C%");
Collection employees = queryEmployees.getResultList();

If you want to re-use the same parameter in more than one place in the query, you must repeat the same parameter as Example 1-15 shows. In this example, the query string will be SELECT * FROM EMPLOYEE WHERE F_NAME LIKE "D%" AND L_NAME LIKE "D%".

Example 1-15 Re-Using Positional Parameters With ?

Query queryEmployees = entityManager.createNativeQuery(
    "SELECT * FROM EMPLOYEE WHERE F_NAME LIKE ? AND L_NAME LIKE ?", Employee.class
);
queryEmployees.setParameter(1, "D%");
queryEmployees.setParameter(2, "D%");
Collection employees = queryEmployees.getResultList();

TopLink JPA Lazy Loading

JPA specifies that lazy loading is a hint to the persistence provider that data should be fetched lazily when it is first accessed, if possible. Implementors can choose how or if they actually load relationships or attributes lazily.

Table 1-8 lists TopLink JPA support for lazy loading by mapping type.

Table 1-8 TopLink JPA Support for Lazy Loading by Mapping Type

Mapping Java EE (inside container)Foot 1  Java SE (outside container)

@ManyToMany

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY (the default).

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY (the default).

@OneToMany

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY (the default).

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY (the default).

@OneToOne

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY.

By default, TopLink JPA ignores the fetch attribute and default FetchType.EAGER applies.

To configure TopLink JPA to perform lazy loading when the fetch attribute set to FetchType.LAZY, configure one of:

@ManyToOne

TopLink JPA performs lazy loading when the fetch attribute is set to FetchType.LAZY.

By default, TopLink JPA ignores the fetch attribute and default FetchType.EAGER applies.

To configure TopLink JPA to perform lazy loading when the fetch attribute set to FetchType.LAZY, configure one of:

@Basic

TopLink JPA ignores the fetch attribute. Default FetchType.EAGER always applies.

TopLink JPA ignores the fetch attribute. Default FetchType.EAGER always applies.


Footnote 1 Fully supported in any container that implements the appropriate container contracts in the EJB 3.0 specification. For example: GlassFish V1, SunAS 9, OracleAS 10.1.3.1, and Spring 2.0.

Dynamic Weaving

When using a @OneToOne or @ManyToOne mapping in a Java SE environment (outside of a container) that permits the use of -javaagent on the JVM command line, to configure TopLink JPA to perform lazy loading when the annotation attribute fetch is set toFetchType.LAZY, you can use the toplink-essentials-agent.jar.

Use this option to weave applicable class files one at a time, as they are loaded at runtime, when the number of classes is few or the time taken to weave the classes is short. If the number of class files is large or the time required to weave the classes is long, consider using static weaving (see Static Weaving Using the StaticWeave Class on the Command Line or Static Weaving Using the weave Ant Task).

To use the toplink-essentials-agent.jar:

  1. Configure your persistence unit with a toplink.weaving extension set to true.

  2. Modify your application JVM command line to include:

    -javaagent:toplink-essentials-agent.jar

  3. Ensure that the toplink-essentials-agent.jar is in your application classpath.

Static Weaving Using the StaticWeave Class on the Command Line

When using a @OneToOne or @ManyToOne mapping in a Java SE environment (outside of a container) that does not permit the use of -javaagent on the JVM command line, to configure TopLink JPA to perform lazy loading when annotation attribute fetch is set toFetchType.LAZY, you can use the StaticWeave class on the command line.

Use this option to weave all applicable class files at buildtime so that you can deliver pre-woven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see Dynamic Weaving).

Alternatively, you can do this using Ant (see Static Weaving Using the weave Ant Task).

To use the StaticWeave class:

  1. Ensure that the toplink-essentials.jar file is in your system classpath.

  2. Execute the StaticWeave class on the command line as follows:

    java oracle.toplink.weaving.StaticWeave [arguments] <source> <target>

    Example 1-16 shows how to use the StaticWeave class on Windows. Table 1-9 lists the arguments of this class.

    Example 1-16 Executing StaticWeave on the Command Line

    java oracle.toplink.weaving.StaticWeave  -persistenceinfo c:\foo-containing-persistencexml.jar -classpath c:\classpath1;c:\classpath2 c:\foo-source.jar c:\foo-target.jar

    Table 1-9 TopLink StaticWeave Class Command Line Arguments

    Argument Description

    -persistenceinfo

    Optional.

    Specifies the location of the persistence.xml file if it is not in the same location as the source (see -classpath).

    -classpath

    Mandatory.

    Specifies the location of the Java source files to weave: either a directory or a JAR file. For Windows, use delimiter ; and for Unix, use delimiter :.

    If the persistence.xml file is not in this location, you must specify the location of the persistence.xml using the -persistenceinfo attribute.

    -log

    Optional.

    Specifies a logging file.

    Default: see Logging

    -loglevel

    Optional.

    Specifies the amount and detail of log output. Valid java.util.logging.Level values are:

    • OFF - disable logging (Default)

    • SEVERE - Logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.

    • WARNING - Logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.

    • INFO - Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.

    • CONFIG - Logs only login, JDBC connection, and database information.

    • FINE - Logs SQL.

    • FINER - Similar to warning. Includes stack trace.

    • FINEST - Includes additional low level information.

    <source>

    Mandatory.

    Specifies the location of the Java source files to weave: either a directory or a JAR file.

    If the persistence.xml file is not in this location, you must specify the location of the persistence.xml using the persistenceinfo attribute.

    <target>

    Mandatory.

    Specifies the output location: either a directory or a JAR file.



    Note:

    If <source> and <target> point to the same location and if the <source> is a directory (not a JAR file), TopLink JPA will weave in place. If <source> and <target> point to different locations or if thesource is a JAR file (as Example 1-16 shows), TopLink JPA cannot weave in place.

Static Weaving Using the weave Ant Task

When using a @OneToOne or @ManyToOne mapping in a Java SE environment (outside of a container) that does not permit the use of -javaagent on the JVM command line, to configure TopLink JPA to perform lazy loading when annotation attribute fetch is set toFetchType.LAZY, you can use the TopLink JPA weave Ant task.

Use this option to weave all applicable class files at buildtime so that you can deliver pre-woven class files. By doing so, you can improve application performance by eliminating the runtime weaving step required by dynamic weaving (see Dynamic Weaving).

To use the TopLink JPA weave Ant task:

  1. Configure the weave Ant task in your build script as Example 1-17 shows. Table 1-10 lists the attributes of this task.

    Example 1-17 TopLink weave Ant Task

    <target name="define.task" description="New task definition for toplink static weaving"/>
    <taskdef name="weave" classname="oracle.toplink.essentials.weaving.StaticWeaveAntTask"/>
</target>
<target name="weaving" description="perform weaving" depends="define.task">
    <weave  source="c:\foo.jar"
            target="c:\wovenfoo.jar"
            persistenceinfo="c:\foo-containing-persistenceinfo.jar">
        <classpath>
            <pathelement path="c:\foo-dependent.jar"/>
        </classpath>
    </weave>
</target>

    Table 1-10 TopLink weave Ant Task Attributes

    Attribute Description

    source

    Mandatory.

    Specifies the location of the Java source files to weave: either a directory or a JAR file.

    If the persistence.xml file is not in this location, you must specify the location of the persistence.xml using the persistenceinfo attribute.

    target

    Mandatory.

    Specifies the output location: either a directory or a JAR file.

    persistenceinfo

    Optional.

    Specifies the location of the persistence.xml file if it is not in the same location as the source.

    log

    Optional.

    Specifies a logging file.

    Default: see Logging

    loglevel

    Optional.

    Specifies the amount and detail of log output. Valid java.util.logging.Level values are:

    • OFF - disable logging (Default)

    • SEVERE - Logs exceptions indicating TopLink cannot continue, as well as any exceptions generated during login. This includes a stack trace.

    • WARNING - Logs exceptions that do not force TopLink to stop, including all exceptions not logged with severe level. This does not include a stack trace.

    • INFO - Logs the login/logout per sever session, including the user name. After acquiring the session, detailed information is logged.

    • CONFIG - Logs only login, JDBC connection, and database information.

    • FINE - Logs SQL.

    • FINER - Similar to warning. Includes stack trace.

    • FINEST - Includes additional low level information.



    Note:

    If source and target point to the same location and if the source is a directory (not a JAR file), TopLink JPA will weave in place. If source and target point to different locations or if the source is a JAR file (as Example 1-17 shows), TopLink JPA cannot weave in place.

  2. Configure the weave task with an appropriate <classpath> element, as Example 1-17 shows, so that TopLink JPA can load all required source classes.

  3. Execute the Ant task using the command line that Example 1-18 shows.

    In this example, the weave Ant task is in the build.xml file.

    Example 1-18 TopLink JPA weave Ant Task Command Line

    ant -lib C:\toplink-essentials.jar -f build.xml weave

    Note:

    You must specify the toplink-essentials.jar file (the JAR that contains the TopLink JPA weave Ant task) using the Ant command line -lib option instead of using the taskdef attribute classpath.

Index of Extensions

toplink.application-location

toplink.cache.shared.<ENTITY>

toplink.cache.shared.default

toplink.cache.size.<ENTITY>

toplink.cache.size.default

toplink.cache.type.<ENTITY>

toplink.cache.type.default

toplink.create-ddl-jdbc-file-name

toplink.ddl-generation

toplink.ddl-generation.output-mode

toplink.descriptor.customizer.<ENTITY>

toplink.drop-ddl-jdbc-file-name

toplink.jdbc.bind-parameters (persistence.xml)

toplink.jdbc.bind-parameters (query hint)

toplink.jdbc.driver

toplink.jdbc.password

toplink.jdbc.read-connections.max

toplink.jdbc.read-connections.min

toplink.jdbc.read-connections.shared

toplink.jdbc.url

toplink.jdbc.user

toplink.jdbc.write-connections.max

toplink.jdbc.write-connections.min

toplink.logging.exceptions

toplink.logging.logger

toplink.logging.level

toplink.logging.level.<CATEGORY>

toplink.logging.session

toplink.logging.thread

toplink.logging.timestamp

toplink.orm.throw.exceptions

toplink.pessimistic-lock

toplink.refresh

toplink.refresh.cascade

toplink.session.customizer

toplink.session-name

toplink.target-database

toplink.target-server

History