BEA WebLogic Server R EJB Enhancements

Transcription

1 BEA WebLogic Server R EJB Enhancements Version: 10.3 Tech Preview Document Date: October 2007

2 Table of Contents Overview of EJB Enhancements... 3 Using the persistence-configuration.xml Descriptor... 3 Kodo-specifc Configuration via the persistence-configuration.xml Descriptor... 3 Usage... 3 Availability... 4 Location of Persistence Descriptors... 4 Exclusivity... 4 Dependency... 4 Appc/Kodoc Integration... 4 Background... 5 Availability... 5 Usage... 5 Kodo MBean Integration... 5 Background... 6 MBeans for Kodo... 6 Usage... 7 JMX, Profiling, and ExecutionContextNameProvider Configuration... 7 Background... 7 Usage... 7 Annotations for Concepts in the weblogic-ejb-jar.xml File... 8 Background... 8 Usage... 8 Dynamically-Updatable Descriptor Elements Background Usage Overview How to Use Dynamically-Updatable Descriptor Elements How to Configure the Dynamic Properties... 11

3 Overview of EJB Enhancements This document covers the various performance improvements made in the WebLogic Server 10.3 Tech Preview in the area of EJB primarily in the area of JPA. Using the persistence-configuration.xml Descriptor According to the JPA specification, a specific persistence unit is configured via a persistence.xml descriptor. The XML schema for structuring this configuration is available at This schema allows a list of vendor-specific properties listed in a <properties> element which contains a sequence of name-value pairs in <property> elements. For example: <xsd:element name="properties" minoccurs="0"> <xsd:annotation> <xsd:documentation> A list of vendor-specific properties. </xsd:documentation> </xsd:annotation> <xsd:complextype> <xsd:sequence> <xsd:element name="property" minoccurs="0" maxoccurs="unbounded"> <xsd:annotation> <xsd:documentation> A name-value pair. </xsd:documentation> </xsd:annotation> <xsd:complextype> <xsd:attribute name="name" type="xsd:string" use="required"/> <xsd:attribute name="value" type="xsd:string" use="required"/> </xsd:complextype> </xsd:element> </xsd:sequence> </xsd:complextype> </xsd:element> Kodo-specifc Configuration via the persistenceconfiguration.xml Descriptor Kodo provides an alternative to this properties list via the persistenceconfiguration.xml descriptor. This descriptor captures Kodo-specific configuration governed by a XML schema available at Usage When using a persistence-configuration.xml descriptor, you must still supply a persistence.xml descriptor. However, all Kodo-specific settings that you would have otherwise put in <property> elements must be listed in persistence-configuration.xml EJB Enhancements 3

4 descriptor instead. Using a persistence-configuration.xml descriptor allows the WebLogic Server Administration Console and WebLogic Scripting Tool (WLST) to recognize the persistence unit as a Kodo persistence unit, and provide advanced configuration and tunables support. If Kodo-specific properties are put directly into the <properties> list of the persistence.xml descriptor, that persistence unit will be treated as a third-party persistence unit by the Administration console and WLST. Availability Beginning in WebLogic Server 10.3, the persistence-configuration.xml descriptor can be used in both container and standalone Java SE environments. Location of Persistence Descriptors In a standalone Java SE environment, the persistence configuration descriptors must be available as resources in META-INF/persistence.xml and META-INF/persistenceconfiguration.xml. In a container environment, persistence-configuration.xml can be placed in the same locations as persistence.xml as described in Section 6.2: Persistence Unit Packaging in JPA Specification, version 1.0. Note that persistenceconfiguration.xml should be a sibling to persistence.xml. Exclusivity If the persistence-configuration.xml descriptor is available and contains an entry for a given persistence unit, then no Kodo or OpenJPA properties can be specified in the <properties> tag in the persistence.xml descriptor for that unit. Kodo or OpenJPA properties are any property with a kodo. or openjpa prefix. Dependency The weblogic.jar file must be in the CLASSPATH when using the persistenceconfiguration.xml descriptor in a Java SE environment. Appc/Kodoc Integration Term appc kodoc Kodo Definition A tool that performs deployment descriptor validation for applications A tool that performs entity class enhancing BEA System's implementation of Sun's Enterprise JavaBeans Persistence 3.0 and Java Data Objects specifications for the transparent persistence of Java objects. EJB Enhancements 4

5 Background This feature integrates kodoc into appc and allows application classes to be run through the Kodo enhancer when running appc. In order to provide optimal runtime performance, flexible lazy loading, and efficient, immediate dirty tracking, Kodo uses a class enhancer to add code to your persistent classes after you have written and compiled them. The enhancer post-processes the byte code generated by your Java compiler, adding the necessary fields and methods to implement the required persistence features. In WebLogic Server, this enhancement can be done via a standalone enhancer or at runtime when the classes are loaded. Running this process as a compile-time process can help to reduce deployment time and to catch any possible errors earlier in the compile-test cycle. Availability The kodoc command has been available since the addition of Kodo to WebLogic Server In WebLogic Server 10.3, this process is integrated into appc. If you are already running appc against your enterprise archives, the kodoc command is automatically available. Usage Appc will enhance the persistent types in the Kodo persistence units in your enterprise applications. Persistence units can be packaged as part of a WAR or EJB JAR file, or can be packaged as a JAR file that can then be included in a WAR or EAR file. If the persistent unit is packaged as a set of classes in an EJB JAR file, the persistence.xml descriptor should be put in the META-INF directory of the EJB JAR. If the persistence unit is packaged as a set of classes in a WAR file, the persistence.xml descriptor should be located in the WEB-INF/classes/META-INF directory of the WAR file. If the persistence unit is packaged in a JAR file that will be included in a WAR or EAR file, the JAR file should be located: In the WEB-INF/lib directory of a WAR In the top-level of an EAR file In the EAR file's library directory When running appc against an enterprise archive that contains non-kodo persistence units, kodoc will only be run against the Kodo-managed persistence units. For more info on usage of appc, see Kodo MBean Integration Term Definition EJB Enhancements 5

6 JMX MBean The JMX application programming interface (API) is a standard API for management and monitoring of resources MBean (managed bean) is a Java object that represents a manageable resource. Background WebLogic Server 10.3 provides a set of MBeans for monitoring Kodo runtime status. These MBeans are registered automatically in the WebLogic Server Runtime MBean server. Kodo already has a variety of JMX MBeans, including MBeans that provide some of the same information made available by these new MBeans. The new MBeans now available in WebLogic Server 10.3 have been revised to align with WebLogic Server MBean standards. MBeans for Kodo The following tables lists the Kodo MBeans and illustrates where the MBeans are located in the runtime MBean hierarchy. Kodo MBeans Description weblogic.management.runtime.kodopersisten ceunitruntimembean weblogic.management.runtime.kodoquerycach eruntimembean weblogic.management.runtime.kodoquerycomp ilationcacheruntimembean weblogic.management.runtime.kododatacache RuntimeMBean The parent of the Kodo bean tree. Kodo MBeans all have a KodoPersistenceUnitRuntimeMBean as their root MBean. The query cache stores the object ids returned by query executions. This MBean has operations for getting the size of the cache and for clearing the cache. It also has a number of attributes for viewing cache statistics. The query compilation cache is a map used to cache parsed query strings. As a result, most queries are only parsed once in Kodo, and cached thereafter. This MBean has an operation for getting the size of the cache. The cache also has a clear operation. The Data cache is designed to provide significant performance increases over cacheless operation, while guaranteeing that behavior will be identical in both cache-enabled and cacheless operation. This MBean has an operation for getting EJB Enhancements 6

7 the size of the cache. It also has a number of attributes for viewing cache statistics, and a clear operation. Usage The persistence-configuration.xml descriptor does not allow configuration of JMX settings. WebLogic Server will automatically register the JMX tree for Kodo persistence units. Since these MBeans are scoped to a particular persistence unit in a particular application, they are always deployed as child MBeans of a higher-level persistence-unitwide MBean. If the persistence.xml descriptor is put in the META-INF directory of the EJB JAR, the KodoPersistenceUnitRuntimeMBean will be registered in EJBComponentRuntimeMBean. If the persistence.xml descriptor is put in the WEB-INF/classes/META-INF directory of a web application, the KodoPersistenceUnitRuntimeMBean will be registered in WebAppComponentRuntimeMBean. If the persistence.xml descriptor is put in the library director of an EAR, the KodoPersistenceUnitRuntimeMBean will be registered in ApplicationRuntimeMBean For more info on accessing WLS MBeans with JMX, see JMX, Profiling, and ExecutionContextNameProvider Configuration Background These features are described in the following locations: //depot/dev/src/modules/bea-kodo/solarmetric/doc/kodo/ref-guidemanagement.xml //depot/dev/src/modules/bea-kodo/solarmetric/doc/kodo/ref-guide-conf.xml //depot/dev/src/modules/bea-kodo/solarmetric/doc/kodo/ref-guideprofile.xml The Kodo.JMX configuration option is not relevant to the WebLogic Server 10.3 Tech Preview; it is only useful outside of a WebLogic Server environment. Usage These features can be accessed via new XML elements in the persistenceconfiguration.xml file: <xs:choice> <xs:element name="stack-execution-context-name-provider" type="per:stack-execution-context-name-providertype" minoccurs="0" <xs:element name="transaction-name-execution-context-name-provider" type="per:transaction-name-execution-context-name-providertype" minoccurs="0" EJB Enhancements 7

8 <xs:element name="user-object-execution-context-name-provider" type="per:user-object-execution-context-name-providertype" minoccurs="0" </xs:choice> <xs:choice> <xs:element name="none-profiling" type="per:none-profilingtype" minoccurs="0" nillable="true" xmlns:per=" <xs:element name="local-profiling" type="per:local-profilingtype" minoccurs="0" nillable="true" xmlns:per=" <xs:element name="export-profiling" type="per:export-profilingtype" minoccurs="0" nillable="true" xmlns:per=" <xs:element name="gui-profiling" type="per:gui-profilingtype" minoccurs="0" nillable="true" xmlns:per=" </xs:choice> <xs:choice> <xs:element name="none-jmx" type="per:none-jmxtype" minoccurs="0" <xs:element name="local-jmx" type="per:local-jmxtype" minoccurs="0" <xs:element name="gui-jmx" type="per:gui-jmxtype" minoccurs="0" <xs:element name="jmx2-jmx" type="per:jmx2-jmxtype" minoccurs="0" <xs:element name="mx4j1-jmx" type="per:mx4j1-jmxtype" minoccurs="0" <xs:element name="wls81-jmx" type="per:wls81-jmxtype" minoccurs="0" </xs:choice> More details about the possible values can be found in the XSD itself, at //depot/dev/src/modules/bea-kodo-integration/src/beangen/resources/metainf/schemas/persistence-configuration.xsd Annotations for Concepts in the weblogic-ejb-jar.xml File Background The session bean/message-driven-bean implementation in WebLogic Server includes a number of proprietary specification extensions. Most of these are accessible via the the weblogic-ejb-jar.xml file. As of WebLogic Server 10.3, some of these concepts can now be specified in Java 5 annotations. Usage The following annotations are now available in the weblogic.javaee package: EJB Enhancements 8

9 XML element Annotation Annotation { int value() default The presence of this annotation identifies that the methods are all call-by-reference. If call-by-value semantics are desired, this annotation should be omitted. { String value(); transactiondescriptor/transtimeout-seconds enable-call-byreference stateful-sessiondescriptor/allowremove-duringtransaction (target=class) Valid on the remote interfaces themselves and valid on the impl class if there is one remote interface. This is different than mappedname since it s the full name instead of the base from which the name is The presence of this annotation identifies that the instance can be removed during a transaction. If this is not desired, this annotation should be { String connectionfactoryjndiname() default ; Class initialcontextfactory() default weblogic.jndi.wlinitialcontextfactory.class; (see ) String providerurl() default t3://localhost:7001 { Stringvalue(); boolean generateuniqueid() default { int retryonrollbackcount() default 0; Class Class SFSB, SLSB only. Class SFSB, SLSB only. Class SFSB only. Class MDB only. Class MDB only. Method message-drivendescriptor/connec tion-factoryjndi-name message-drivendescriptor/jmsclient-id idempotentmethods retry-methods-onrollback transactionisolation See retry-methods-on-rollback See { IsolationLevel value() default DEFAULT; enum IsolationLevel { READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE Method EJB Enhancements 9

10 { WarningCode[] value(); enum WarningCode { BEA_010001, BEA_010200, BEA_010202, BEA_ All annotation values from all enterprise beans in an enterprise component are collected, and the union of all of them is ignored for the deployment unit being processed. If the weblogic-ejb-jar.xml file contains a warning list, then the annotation-based list is totally disregarded. Class Dynamically-Updatable Descriptor Elements Background The Administration Console in WebLogic Server allows some configuration settings to be dynamically updated without requiring a redeploy. In WebLogic Server 10.3, the following Kodo properties can be dynamically updated: locktimeout datacachetimeout fetchbatchsize Usage These settings can be modified via the Administration console, WLST, or the weblogic.deployer command. Overview The persistence-configuration.xml descriptor contains properties that define specific behavior for persistence units named in the descriptor. Three of these properties: LockTimeout, DataCacheTimeout, and FetchBatchSize are now dynamically configurable meaning changes made to the values of these properties can be activated without redeploying the application that contains the respective persistence units. Before the implementation of this feature it was necessary to redeploy the application for the descriptor property changes to become effective, making applying the changes very cumbersome. If an application has several persistence units, changes to the LockTimeout, DataCacheTimeout, and FetchBatchSize properties can be made individually for the persistence units as well as for several persistence units together in any combination. Changes to the properties are saved in the plan.xml file so that changes do not get lost across application redeployments or server restarts. This is true also for non-dynamic properties, however, non-dynamic property changes require an application redeployment. EJB Enhancements 10

11 How to Use Dynamically-Updatable Descriptor Elements Being able to dynamically change persistence descriptor properties allows application developers as well as application deployers to modify the values of the properties repeatedly without incurring the time it takes to redeploy a whole application. This dynamic process without the need for redeployment saves significant application deployment time and therefore supports a quick and iterative process of fine tuning the property values for optimal performance of the persistence units. Since changes in the value of the properties can be activated in a matter of seconds the fine tuning process can be repeated very quickly and efficiently. Since properties of different persistence units can be changed at the same time, a global tuning strategy becomes possible. As the dynamic values are persistently stored in the plan.xml document it is possible to save alternative combinations of property values by simply making copies of the plan.xml document. This allows exploring different combination of settings. Once the optimal setting is found it can be kept as the only copy of the plan.xml document; or several different tuning strategies can be kept by simply keeping the various copies of the plan.xml document. How to Configure the Dynamic Properties There are two ways to make dynamic property changes: the Administration Console and the deployer.weblogic command. The Administration Console is extended with entry field for the properties that can change dynamically. The following figures show the tabs in the Administration Console where the properties can be changed dynamically. The following figure shows the Data Cache Timeout property as well as the Fetch Batch Size property under the General tab. EJB Enhancements 11

12 The following figure shows the Lock Timeout field on the Advanced tab. In the figures. the name of the persistence unit is test and changes to the properties can be made in any combination. Upon saving the changes the system asks for a location for the plan.xml document (in case it is not already defined). Also, activating the changes follows the procedure as for non-persistence unit related properties. EJB Enhancements 12

13 The deployer.weblogic command can also be used to update property values by deploying a plan.xml document. For example: java weblogic.deployer name JPAService update plan C:/plan.xml where JPAService is the name of the application The plan document in C:/plan.xml contains the property values to be activated EJB Enhancements 13

14 This command attempts to apply all property changes in the plan.xml document located in C:/plan.xml. The changes will be activated dynamically if all properties in the plan.xml file are dynamic properties. If there is at least one non-dynamic property, the activation fails and the application has to be redeployed for the property changes to take effect. EJB Enhancements 14