Latest revision as of 09:25, 13 July 2010

Design Specification: WebLogic 10.3 JMX MBean Support

Bug# 235168 - Generic JMX MBeans for WebLogic - complete

Bug# 248748 - WebLogic extensions to generic JMX MBeans - in progress here

JMX MBean Tutorial for Oracle WebLogic Server

JPA EAR, EJB, WAR and SE (DDL Generation) WebLogic 10.3 J2EE application Eclipse projects in SVN - use to perform JMX MBean registration

Document History

Project overview

We require specific attributes available outside of the generic MBeans in ER 235168. This enhancement request has 3 phases - we are working on phase 1 and 2 at this time below.

• 1) Add functions originally available on the OC4J server platform that do not require WebLogic API
• 2) Add functions previously available on OC4J that required reflective or API calls
• 3) Add functions new to WebLogic 10/10.3 - future

Public API - For Designers

Note: some of the attribute functionality in the JMX MBean API for WebLogic 10.3 - specifically moduleName and applicationName are only available in build 20081015 and later of WebLogic 10.3.1.

The following JMX MBean public API is exposed by the EclipseLink runtime services MBean and is available to any JMX compliant client.

From your MBeanServer on WebLogic 10.3.1 get an implementation of org.eclipse.persistence.services.weblogic.MBeanWebLogicRuntimeServices which extends WebLogicRuntimeServices and implements the interface MBeanWebLogicRuntimeServicesMBean in the same package.

Enhancement Requests

Phase 2 - complete

• 248748: JMX: Create and Add server specific attributes to WebLogic MBeans - complete
  • http://bugs.eclipse.org/248748
• 248746: JMX: No reference to owning application in WebLogic RuntimeServices MBean - complete
  • http://bugs.eclipse.org/248746
• 254463: JMX: Add isJPASession() attribute to WebLogic 10 runtime services MBean - complete
  • http://bugs.eclipse.org/254463

Post 1.1 release - pending

• 248747: JMX: MBeans require 2nd DevelopmentServices bean disabled by default - per session
  • http://bugs.eclipse.org/248747
• 251895: JMX: Refactor and Internationalize INFO logs in WebLogic specific MBean functions
  • http://bugs.eclipse.org/251895
• 252786: WLS: Add extended metrics functionality to WebLogic specific JMX MBeans
  • http://bugs.eclipse.org/252786
• JMX: ELUG JPA extensions page - documentation updates for extended metrics and MBeans
  • http://bugs.eclipse.org/253730
• 254467: WLS: Add WebLogic 10.3 platform subclass to 10
  • http://bugs.eclipse.org/254467

Requirements

• Add the following functions to a WebLogic version of our RuntimeServices Mbean - to be reviewed.
  • We want to cross-reference this new list with the exclusion list in the 1.0 implementation.
  • Some of the attributes prefixed with print have generic analogs using get already.
  • Some of the attributes contain an internal current keyword that is removed.
  • Some of these public functions may not make it to the public interface

Interface Addition Candidates

• public String getSessionName()

• public String getSessionType()

• public ArrayList <ClassSummaryDetail> getClassSummaryDetailsArray()

• public Object[][] getClassSummaryDetails()

• public String getModuleName()

• public String getDeployedEclipseLinkLogLevel()

• public String getDeployedEclipseLogLevel(String category)

• public String getCurrentEclipseLogLevel()

• public String getCurrentEclipseLogLevel(String category)

• public synchronized void setCurrentEclipseLogLevel(String newLevel)

• public synchronized String getProfilingType()

• public synchronized void setProfilingType(String profileType)

• public void setUsesEclipseProfiling()

• public void setUsesDMSProfiling() - removed

• public Boolean getusesEclipseProfiling() - are we still removing this - it currently exists?

• public Boolean getUsesDMSProfiling() - removed

• public void setUseNoProfiling()

• public synchronized void setshouldLogPerformanceProfiler(Boolean shouldLogPerformanceProfiler) - removed

• public Boolean getshouldLogPerformanceProfiler() - removed

• public Boolean getShouldBindAllParameters()

• public Integer getStringBindingSize()

• public Long getTimeConnectionEstablished()

• public Boolean getUsesJDBCBatchWriting()

• public Boolean getUsesByteArrayBinding()

• public Boolean getUsesNativeSQL()

• public Boolean getUsesStreamsForBinding()

• public Boolean getShouldCacheAllStatements()

• public Integer getStatementCacheSize()

• public synchronized void clearStatementCache()

• public Integer getSequencePreallocationSize()

• public void printAvailableConnectionPools()

• public Integer getMaxSizeForPool(String poolName)

• public Integer getMinSizeForPool(String poolName)

• public void printClassesInSession()

• public void printObjectsInIdentityMap(String className) throws ClassNotFoundException

• public void printAllIdentityMapTypes()

• public void printObjectsInIdentityMaps()

• public Integer getNumberOfObjectsInAllIdentityMaps()

• public Integer getNumberOfPersistentClasses()

• public void printIdentityMapLocks()

• public void printIdentityMapLocks(String registeredClassName)

• public void printProfileSummary()

• public void printProfileSummaryByClass()

• public void printProfileSummaryByQuery()

• public String getLogType()

• public String getDatabasePlatform()

• public synchronized String getConnectionPoolType()

• public synchronized String getDriver()

• public String getLogFilename()

• public synchronized String getdeployedProfileWeight() - removed - superclassed by getProfileWeight()

• public synchronized String getcurrentProfileWeight() - removed - superclassed by getProfileWeight()

• public synchronized void setcurrentProfileWeight(String weight) - removed - superclassed by getProfileWeight()

• public synchronized void initializeAllIdentityMaps()

• public synchronized void initializeIdentityMaps(String[] classNames) throws

ClassNotFoundException

• public synchronized void initializeIdentityMap(String className) throws

ClassNotFoundException

• public synchronized void invalidateAllIdentityMaps() {

• public synchronized void invalidateIdentityMaps(String[] classNamesParam, Boolean

recurse) throws ClassNotFoundException {

• public synchronized void invalidateIdentityMap(String className) throws

ClassNotFoundException

• public synchronized void invalidateIdentityMap(String className, Boolean recurse) throws ClassNotFoundException

• public Boolean getcacheSynchEnabled() - removed

• public Boolean getcacheSynchAsynchronous() - removed

Design / Functionality

Design Constraints

C1: MBeans are not available until the first login of a server application (lazy-loaded)

Design Issue 1: getModuleName() Application Name from WebLogic

• 248746: JMX: No reference to owning application in WebLogic RuntimeServices MBean
  • http://bugs.eclipse.org/248746

There are 2 requirements to this issue.

• 1) Application name - the persistence unit associated with the session (a 1-1 relationship)
• 2) Module name - the ejb or war jar name (there is a 1-many relationship for module:session(s))

The reflective API discussed here requires WebLogic 10.3.3.1 build 20081025 or later to function, or the secondary method of using the contextClassLoader will be used.

The getModuleName() and getApplicationName() functions are required to return the module name of the owner of the current session. These function name will be determined from either the EJB, War or MDB application. There are currently 3 methods we can use to determine this function name.

The following is a screen capture of the moduleName attribute for a specific application.

Alternative 1: Pass module name via weblogic.moduleName property

Pros

• No introduction of a weblogic.jar dependency in EclipseLink

Cons

• Each application must supply the moduleName in persistence.xml or sessions.xml

Alternative 2: Pass module name via WebLogic specific container context API

This is the current API shipped as of label 20081031.

Pros

• Compile-time verification of WebLogic API changes are caught before runtime.

Cons

• Introduction of a compile-time dependency on weblogic.jar from EclipseLink is not advisable.

Alternative 3: Pass module name via Reflective call to the WebLogic context

see

• Oracle Engineering Oxygen Wiki BEA-JEE appinfothread - Application information for application threads
• we will do the the following reflective calls against WebLogic
  • public java.lang.String weblogic.work.ExecuteThreadRuntime.getApplicationName()
  • public java.lang.String weblogic.work.ExecuteThreadRuntime.getModuleName()

Pros

• No introduction of a weblogic.jar dependency in EclipseLink

Cons

• Changes to weblogic API will not show up until runtime - as no compile-time dependency exists as a regression check.
• An automated JMX client test suite will be required to catch any API changes that would only show up as runtime exceptions for users.
• For a full implementation we require WebLogic 10.3.3.1 build 20081025 or later

Decision

Alternative 3 will be implemented as of 20081104 in 248746 is entered as alternative 3.

Test Results

Use the following page on the WebLogic console to compare persistence unit properties - IE: the session name.

Home >Summary of Diagnostics >Summary of Diagnostic Modules >Summary of JMS Servers >Summary of Foreign JNDI Providers >Summary of Persistent Stores >base_domain >Work Context Resources >Summary of Deployments >org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEJB.jar >example

WebLogic 10.3 build 20080422

No executeThread call - revert to the classLoader string.

jpaModuleName	"weblogic.utils.classloaders.ChangeAwareClassLoader@1efb21d finder: weblogic.utils.classloaders.CodeGenClassFinder@74076a annotation: org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEAR@enterprise" (id=11340)	

WebLogic 10.3.3.1 build 20080915

• The reflective call to executeThreadRuntime is working as this new API is in public 10.3.3.1 builds since Aug - it returns the following.
• getModuleName() matches the <context-root> in application.xml in the EAR
• getApplicationName() matches the deployed ear filename.

>>getModuleNameOrClassLoader() ClassLoaderName: weblogic.utils.classloaders.ChangeAwareClassLoader
>>getModuleNameOrClassLoader() executeThread(): enterprise-root
>>getApplicationNameOrClassLoader() ClassLoaderName: weblogic.utils.classloaders.ChangeAwareClassLoader
>>getApplicationNameOrClassLoader() executeThread(): org.eclipse.persistence.example.jpa.server.weblogic.enterpriseEAR

WebLogic 10.3.3.1 build 20081101

TBD by myself but testing confirms that the getApplicationName() call returns the persistence unit name for the session.

Design Issue 2: rename all fuctions in standard MBean format get/setUpperCase()

All functions must be in the format get/setUppercase() not get/setlowerCase() - some of the functions ported from OC4J are not in the correct format, therefore the interface and implementation will be modified to standard MBean naming format.

- complete

Design Issue 3: Rename MBean in standard org.eclipse.persistence format

• Entered: 20081031 (code review)
• Instead of using the existing "EclipseLink_Domain" format, we should move to the a standard . naming format of org.eclipse.persistence.
• "Runtime_<session name>" changed to "Runtime-<session name>"
• This will affect how consumers search for the mbean.

- complete

Design Issue 4: Extended Metrics functionality in WebLogic

On Hold

• 252786: WLS: Add DMS functionality to WebLogic specific JMX MBeans
  • http://bugs.eclipse.org/252786

There is a requirement to port extended profiling functionality to the EclipseLink WebLogic platform. We will need to add this functionality without introducing dependencies on WebLogic specific API.

This will be accomplished by using generic interface functions where possible or reflective calls to WebLogic. Any requirements to add functionality to the WebLogic server itself will be scoped here. We will require an implementation of tools.DMSPerformanceProfiler that implements the existing SessionProfiler.

Design Issue 5: Add isJPASession attribute

Requirements

The enterprise manager group requires a way to filter whether the session attached to a runtime services is an EclipseLink JPA or TopLink BMP session on the WebLogic server.

Constraints

1. No weblogic.jar API dependencies are to be introduced - Use reflective calls into weblogic.work.ExecuteThreadRuntime - if required
2. Try not to add any dependency on the JPA component - even though the unrelated workaround fix for bug# 229634 already introduced dependencies
3. Possibly create a 10_3 subclass of the WebLogic_10_Platform class

API

No new jar dependencies - use reflective calls where server API is required.

The JMX API is included in J2SE 1.5 (new to J2SE 1.5 from J2EE 1.4) - the interfaces from this JMX API are used even though the implementation uses weblogic specific weblogic.management API during runtime.

There is a JMX server now in the 1.5 SE JRE

J2SE 1.5 JMX

JMX used to be in J2EE 1.4

J2EE 1.4 JMX

WebLogic Platform changes

Registration of the new runtime services mbean is implemented as follows.

MBeanWebLogicRuntimeServices runtimeServices = new MBeanWebLogicRuntimeServices((AbstractSession)getDatabaseSession());

Disabling EclipseLink Managed Lazy Registration

By default MBean registration is disabled for WebLogic. This registration would occur as a post step during the first login to the session when it is enabled.

Application Managed Lazy Registration

Disabling MBean Registration

If MBean registration is not required, or the application will be handling registration then you may disable automatic registration at the first login by setting up the following.

• System properties

MBean registration is enabled by adding one or both of the two mbean system properties If [eclipselink.register.dev.mbean] or [eclipselink.register.run.mbean] properties are missing then MBean registration will not proceed for that bean.

rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=true
rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=true

• sessions.xml property

WebLogic ApplicationLifecycleListener Example

Here the application can manage registration/deregistration of the MBeans by using a SessionCustomizer in conjunction with a listener on either a servlet or session bean within the JEE application.

• SessionCustomizer

• Listener

You must configure the EclipseLink Mbeans in the EAR/meta-inf via a weblogic-application.xml descriptor entry.

<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN"  "http://java.sun.com/dtd/application_1_3.dtd">
<weblogic-application xmlns="http://www.bea.com/ns/weblogic/10">
    <listener>
       <listener-class>org.eclipse.persistence.example.unified.integration.ApplicationLifecycleListenerImpl</listener-class>
    </listener>
</weblogic-application>

UML Class Diagram

In the following UML static class diagram we are introducing the blue artifacts that subclass off the existing generic JMX MBean implementation in EclipseLink.

GUI

<JAVA_HOME>/bin/JConsole client

You should see the following single EclipseLink MBean off the root of the JNDI tree. In this example there is one EAR deployed to WebLogic - with its own set of MBeans based on the login session.

Code Reviews

20081031

• Modifications:

http://fisheye2.atlassian.com/changelog/eclipselink/?cs=2700

• - use standard MBean registration format "org.eclipse.persistence" instead of existing "EclipseLink_Domain"
• - "Runtime_<session name>" changed to "Runtime-<session name>"
• - 2 duplicated functions in sub-interface MBeanWebLogicRuntimeMBean that are already in MBeanRuntimeServicesMBean
  • public Integer getNumberOfObjectsInIdentityMap(String className) throws ClassNotFoundException;
  • public void resetAllConnections();
• - Modify null session name error message
  • { "session_key_for_mbean_name_is_null", "Session name used for the MBean registration cannot be null." },
• Four refactoring requests were entered
  • JMX: Refactor: MBean impl/interface naming conventions change
    • http://bugs.eclipse.org/253017
  • JMX: Refactor: Move generic functions out of platform into superclass
    • http://bugs.eclipse.org/253018
  • JMX: Refactor: Additional Human readable time format for TimeConnectionEstablished
    • http://bugs.eclipse.org/253019
  • JMX: Refactor: getCacheTypeFor() for NoIdentityMap should return "NoIdentity" instead "None"
    • http://bugs.eclipse.org/253020

Documentation Changes Required

• http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#How_to_Use_the_Persistence_Unit_Properties_for_Optimization
  • JMX: ELUG JPA extensions page - documentation updates for extended metrics and MBeans
    • http://bugs.eclipse.org/253730
• http://wiki.eclipse.org/Integrating_EclipseLink_with_an_Application_Server_(ELUG)#How_to_Integrate_JMX
• http://wiki.eclipse.org/Configuring_a_Session_%28ELUG%29#Configuring_the_Server_Platform

Open Issues

References

• ELUG Documentation
• JMX MBeans in WebLogic 10
• Obtaining the datasource from an EntityManager