Skip to main content

TopLink Essentials enhancements - category-specific logging level and cascade refresh query hint

Posted by guruwons on July 6, 2007 at 10:39 PM EDT
Recently I've implemented two minor but useful features for TopLink Essentials(TLE) v2 b54(or GlassFish v2 b54). One is the category-specific logging level configuration[1] which is useful for who want to see only SQL logs and the other is the cascade refresh query hint[2] which control the cascade scope of the refresh query dynamically.

Let's see what these are...

Category-specific logging level

Configuring logging level for a PU(Persistence Unit) could be done by "toplink.logging.level" property like below.

     <persistence-unit name="pu1">
         ...
        <properties> 
            ...
            <property name="toplink.logging.level" value="FINE"/> 
         </properties> 
     </persistence-unit>


To see SQLs triggerred by TLE the logging level should be FINE. However this will print other many FINE logs which may be of little interest to normal users. This is like all-or-nothing choice.

Fortunately the logging platform of TLE basically supports categories for different types of logs - "sql", "connection", "transaction" and so on.
This enable users to watch interested logs of specific categories. Especially the "sql" category is the most interesting one.

However there had been no easy way to configure the logging level for the specific category. So I've added the following new category logging level property and connected it with logger code.

Property
 Description
toplink.loging.level.<category> Control the log level for a specific category.

Categories(defined in oracle.toplink.essentials.logging.SessionLog):
  • sql - SQL logs
  • transaction - Transaction related logs
  • event
  • connection - Session related logs
  • query - DatabaseQuery related logs
  • cache - shared cache logs
  • propagation
  • sequencing - sequencing generator logs
  • ejb
  • dms
  • 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(INFO is default) is used.

Example: to see SQL logs
<property name="toplink.logging.level.sql" value="FINE"/>

Cascade refresh query hint for refresh query

TLE provides the query hint toplink.refresh to fetch up-to-date entities from database like below.
    Query query = em.createQuery("SELECT e FROM Employee e WHERE e.id = :id");
    query.setHint("toplink.refresh", "true");
The associated entities will be refreshed also if they are specified with cascade=REFRESH. However the cascade metadata is static configuration which can not be changed in runtime and there may be some cases to apply different cascade options - do not cascade or cascade to all associations from time to time regardless of predefined cascade option. That is, more dynamic cascade refresh option can be useful. Hence I added the following query hint.

Query hint
 Description
toplink.refresh.cascade
 Control whether associated entities are refreshed.

The following are the valid values for the oracle.toplink.essentials.config.CascadePolicy:
  • NoCascading - do not cascade at all
  • CascadePrivateParts - cascade to private-owned associations
  • CascadeAllParts - cascade to all associations
  • CascadeByMapping - cascade by mapping metadata

Default is CascadeByMapping

Example: 

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

or

query.setHint("toplink.refresh.cascade", "CascadeAllParts");
NOTE: This applies only if toplink.refresh is set to TRUE.

At this time CascadePrivateParts option has no difference from CascadeAllParts for Java Persistence Entity, but when using underlying TopLink feature this could behave different in the future.

Other existing properties and query hints are documented in http://www.oracle.com/technology/products/ias/toplink/JPA/essentials/toplink-jpa-extensions.html

Have fun with this enhancements and please comment how you feel.

[1] GlassFish Issue#1338
[2] GlassFish Issue#3269
Related Topics >>
Blog Links >>