Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/DesignDocs/235168"

m (Design Specification: WebLogic JMX MBean Support)
m
 
(21 intermediate revisions by the same user not shown)
Line 1: Line 1:
= Design Specification: WebLogic JMX MBean Support =
+
*[http://wiki.eclipse.org/EclipseLink/DesignDocs/248748 248748] : JMX support for WebLogic
<font color="red">This design doc is being finalized the week of June 23 2008</font>
+
*[http://wiki.eclipse.org/EclipseLink/DesignDocs/316513 316513] : JMX support for WebSphere, JBoss and Glassfish
 
+
[http://bugs.eclipse.org/235168 Bug# 235168]
+
 
+
[http://wiki.eclipse.org/EclipseLink/Examples/JMX/MBeans_WebLogic JMX MBean Tutorial for WebLogic]
+
 
+
== Document History ==
+
{|{{BMTableStyle}}
+
|-{{BMTHStyle}}
+
! Date
+
! Author
+
! Version Description & Notes
+
|-
+
| 2008-06-23
+
| Michael O
+
| 0.1 Starting Draft
+
|}
+
 
+
== Project overview ==
+
We require a way to manage EclipseLink sessions using standard JMX API.
+
This enhancement will add JMX MBean support to EclipseLink 1.0 by exposing select runtime and development attributes and methods to custom JMX client code or JConsole.
+
 
+
We will be adding the 2 MBeans below and their associated interfaces and platform support code.
+
<source lang="java">
+
org.eclipse.persistence.services.DevelopmentServices
+
org.eclipse.persistence.services.RuntimeServices
+
</source>
+
 
+
== Concepts ==
+
Based on JMX 1.2 and JMX Remote API 1.0
+
 
+
== References ==
+
[http://wiki.eclipse.org/Integrating_EclipseLink_with_an_Application_Server_(ELUG)#How_to_Integrate_JMX ELUG Documentation]
+
[http://edocs.bea.com/wls/docs100/wlsmbeanref/core/index.html JMX MBeans in WebLogic 10]
+
 
+
== Requirements ==
+
=== R1: Enable JMX MBean Support for WebLogic===
+
=== R2: Enable JMX MBean support for generic J2EE servers - future===
+
=== R3: MBeans have a 1:1 relationship with their session (multiple EARs=multiple beans)===
+
=== R4: Clients can disable post login MBean registration (via SessionCustomizer)===
+
=== R5: Clients can manage their own registration of EclipseLink MBeans (via ApplicationLifecycleListener)===
+
== Design Constraints ==
+
=== C1: MBeans are not available until the first login of a server application (lazy-loaded)===
+
=== C2: Functions marked OBSOLETE will not be implemented if there is no suitable replacement===
+
== Design / Functionality ==
+
===Design Issue 1: Obsolete/deprecated code===
+
 
+
Some functions in the original generic MBean code use code that is no longer in Eclipse or was refactored - listed below
+
*RuntimeServices
+
**public void setSequencePreallocationSize(int size)
+
**public int getSequencePreallocationSize()
+
((DatasourcePlatform)getSession().getDatasourcePlatform()).setSequencePreallocationSize(size);
+
 
+
replaces
+
 
+
((DatabaseLogin)getSession().getDatasourceLogin()).setSequencePreallocationSize(size);
+
 
+
*DevelopmentServices
+
**public void setChangeSetPropagationShouldBeAsynchronous(boolean isAsynchronous)
+
**public boolean getChangeSetPropagationShouldBeAsynchronous()
+
**public void setShouldRemoveConnectionOnError(boolean shouldRemoveConnection)
+
**public boolean getShouldRemoveConnectionOnError()
+
**public void updateSynchronizationDiscoveryMulticastGroup(String multicastIP, int multicastPort)
+
**public void initializeCacheSynchronizationServices() throws SynchronizationException
+
 
+
The following classes were deprecated and removed after M1, replacement functionality is required see [http://bugs.eclipse.org/238408 238408].
+
<pre>
+
org.eclipse.persistence.sessions.remote.CacheSynchronizationManager;
+
org.eclipse.persistence.sessions.remote.AbstractClusteringService;
+
</pre>
+
Any inclusion of refactored code for the above functions will require a test setup that includes a cluster - see [http://bugs.eclipse.org/238412 238412]
+
 
+
====Included MBean Functions/Attributes====
+
The following functions are supported in EclipseLink 1.0
+
=====Runtime Services MBean=====
+
*<font color="red">public int getLogLevel(String category)</font>
+
*<font color="red">public void setLogLevel(int level)</font>
+
*<font color="green">public boolean getShouldLogMessages()</font>
+
*<font color="red">public void setShouldProfilePerformance(boolean shouldProfile)</font>
+
*<font color="green">public boolean getShouldProfilePerformance()</font>
+
*<font color="red">public void setShouldLogPerformanceProfiler(boolean shouldLogPerformanceProfiler)</font>
+
*<font color="green">public boolean getShouldLogPerformanceProfiler()</font>
+
*<font color="red">public void setShouldCacheAllStatements(boolean shouldCacheAllStatements)</font>
+
*<font color="green">public boolean getShouldCacheAllStatements()</font>
+
*<font color="red">public void setStatementCacheSize(int size)</font>
+
*<font color="green">public int getStatementCacheSize()</font>
+
*<font color="red">public void setSequencePreallocationSize(int size)</font>
+
*<font color="green">public int getSequencePreallocationSize()</font>
+
*<font color="green">public void updatePoolSize(String poolName, int maxSize, int minSize)</font>
+
*<font color="green">public List getAvailableConnectionPools()</font>
+
*<font color="green">public List getSizeForPool(String poolName)</font>
+
*<font color="green">public void addNewConnectionPool(String poolName, int maxSize, int minSize, String platform, String driverClassName, String url, String userName, String password) throws ClassNotFoundException</font>
+
*<font color="green">public void resetAllConnections()</font>
+
*<font color="green">public List getClassesInSession()</font>
+
*<font color="green">public List getObjectsInIdentityMap(String className) throws ClassNotFoundException</font>
+
*<font color="green">public Integer getNumberOfObjectsInIdentityMap(String className) throws ClassNotFoundException</font>
+
*<font color="green">public List getObjectsInIdentityMapSubCacheAsMap(String className) throws ClassNotFoundException</font>
+
*<font color="green">public Integer getNumberOfObjectsInIdentityMapSubCache(String className) throws ClassNotFoundException</font>
+
*<font color="red">public boolean shouldLog(int Level, String category)</font>
+
*<font color="red">public void setProfileWeight(int weight)</font>
+
 
+
=====Development Services MBean=====
+
*<font color="green">public void initializeIdentityMap(String className) throws ClassNotFoundException
+
*<font color="green">public void initializeAllIdentityMaps()
+
*<font color="green">public void setIdentityMapForClass(String className, String identityMapClassType, int maxSize) throws ClassNotFoundException
+
*<font color="green">public void refreshProject(String projectFilePath)
+
*<font color="green">public void updateCacheSize(String className, int newSize) throws ClassNotFoundException
+
*public void setShouldBindAllParameters(boolean shouldBindAllParameters)
+
*<font color="green">public boolean getShouldBindAllParameters()
+
*public void setStringBindingSize(int size)
+
*<font color="green">public int getStringBindingSize()
+
*public void setUsesBatchWriting(boolean usesBatchWriting)
+
*<font color="green">public boolean getUsesBatchWriting()</font>
+
*<font color="red">public void setUsesByteArrayBinding(boolean usesByteArrayBinding)</font>
+
*<font color="green">public boolean getUsesByteArrayBinding()</font>
+
*<font color="red">public void setUsesJDBCBatchWriting(boolean usesJDBCBatchWriting)</font>
+
*<font color="green">public boolean getUsesJDBCBatchWriting()</font>
+
*<font color="red">public void setUsesNativeSQL(boolean usesNativeSQL)</font>
+
*<font color="green">public boolean getUsesNativeSQL()</font>
+
*<font color="red">public void setUsesStreamsForBinding(boolean usesStreamsForBinding)</font>
+
*<font color="green">public boolean getUsesStreamsForBinding()</font>
+
*<font color="red">public void setUsesStringBinding(boolean usesStringBinding)</font>
+
*<font color="green">public boolean getUsesStringBinding()</font>
+
 
+
====Obsolete MBean Functions/Attributes====
+
The following functions are obsolete or deprecated and will not be included.
+
=====Runtime Services MBean=====
+
*public void setShouldLogMessages(boolean shouldLogMessages) // Replaced by setLogLevel(int level)
+
*public void setShouldLogDebug(boolean shouldLogDebug) // Replaced by setLogLevel(int level)
+
*public boolean getShouldLogDebug() // Replaced by getLogLevel(String category)
+
*public void setShouldLogExceptions(boolean shouldLogExceptions) // Replaced by setLogLevel(int level)
+
*public boolean getShouldLogExceptions() // replaced by getLogLevel(String category)
+
*public void setShouldLogExceptionStackTrace(boolean shouldLogExceptionStackTrace)
+
*public boolean getShouldLogExceptionStackTrace()
+
*public void setShouldPrintDate(boolean shouldPrintDate)
+
*public boolean getShouldPrintDate()
+
*public void setShouldPrintSession(boolean shouldPrintSession)
+
*public boolean getShouldPrintSession()
+
*public void setShouldPrintThread(boolean shouldPrintThread)
+
*public boolean getShouldPrintThread()
+
*public void setShouldPrintConnection(boolean shouldPrintConnection)
+
*public boolean getShouldPrintConnection()
+
*public void addNewConnectionPool(String poolName, int maxSize, int minSize, String platform, String driverClassName, String url, String userName, String password, String licencePath) throws ClassNotFoundException
+
*public List getObjectsInIdentityMapSubCache(String className) throws ClassNotFoundException // replaced by getObjectsInIdentityMapSubCacheAsMap(String className)
+
 
+
=====Development Services MBean=====
+
*public void setChangeSetPropagationShouldBeAsynchronous(boolean isAsynchronous)
+
*public boolean getChangeSetPropagationShouldBeAsynchronous()
+
*public void setShouldRemoveConnectionOnError(boolean shouldRemoveConnection)
+
*public boolean getShouldRemoveConnectionOnError()
+
*public void updateSynchronizationDiscoveryMulticastGroup(String multicastIP, int multicastPort)
+
*public void initializeCacheSynchronizationServices() throws SynchronizationException
+
 
+
====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 disabled by ommitting 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.
+
<pre>
+
rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.dev.mbean=true
+
rem set JAVA_OPTIONS=%JAVA_OPTIONS% -Declipselink.register.run.mbean=true
+
</pre>
+
 
+
 
+
*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.
+
<source lang="xml">
+
<!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>
+
</source>
+
 
+
===Design Issue 2: Session names in WebLogic 10.x===
+
We can not use the session name as-is as part of the MBean registration name because the characters ":" and "'" are reserved in JMX.
+
The session name will be undergo character replacement of ":," into "_"
+
<pre>
+
EclipseLink_Domain:Name=Development_file_/C_/opt/wls103/user_projects/domains/base_domain/servers/AdminServer/tmp/_WL_user/_appsdir_weblogicEAR7_ear/jmidq0/weblogicEJB.jar-unifiedWebLogicEL7,Type=Configuration
+
</pre>
+
 
+
===Design Issue 3: Initial state of MBean registration===
+
We will default to "registration" for the WebLogic platform.  The server administrator can disable registration for either bean using the 2 system properties [eclipselink.register.dev.mbean] or [eclipselink.register.run.mbean].
+
At the user level, registration can also be disabled by setting the property [] in sessions.xml or using a SessionCustomizer for JPA applications.
+
 
+
===Design Issue 4: MBean Unregistration===
+
MBeans will be unregistered just before a session logout.  This would occur on a server shutdown/restart, an EAR undeploy/redeploy or a programmatic session logout such as the one that occurs on the DevelopmentServices MBean action "refreshProject".
+
 
+
There is currently an issue #3 [http://bugs.eclipse.org/238343 238343] with security on WebLogic 10.3 that may extend to 9.0 where we get a weblogic.management.NoAccessRuntimeException when we try mBeanServerRuntime.unregisterMBean(name).
+
 
+
===Design Issue 5: Where to bootstrap MBean registration===
+
In the past the MBeans were registered along with the CMP 2.x beans in ProjectDeployment.deployEJB().  In EclipseLink we need a suitable place for registration to occur.
+
 
+
====Option 1: Register in JPA EM predeploy====
+
The predeploy option is only available in pure JPA applications and is not available to EclipseLink ORM applications.  Also, creating MBean instances requires a logged in session to associate with - we don't have any sessions at the predeploy stage to use
+
====In Use - Option 2: Register in ServerPlatformBase during postLogin====
+
In DatabaseSessionImpl.postConnectDatasource() we execute getServerPlatform().registerMBean() which will run in the generic superclass ServerPlatformBase which will invoke a callback to WebLogic_10_Platform.serverSpecificRegisterMBean() that registers the 2 MBeans (UML Sequence diagram required)
+
 
+
In EclipseLink the MBean registration and unregistration occurs in the platform class.  For WebLogic we have the following callback functions implemented.
+
<source lang="java">
+
org.eclipse.persistence.platform.server.wls.WebLogic_10_Platform extends WebLogic_9_Platform
+
public void serverSpecificRegisterMBean()
+
public void serverSpecificUnregisterMBean()
+
</source>
+
 
+
===Design Issue 6: Exception Handling===
+
We will log warning messages and the stack trace for exceptions involving naming, security and session collision
+
 
+
== Use Cases ==
+
=== UC1: EclipseLink managed MBean registration===
+
=== UC2: Application managed MBean registration===
+
=== UC3: No MBean registration
+
==== UC3.1 No MBean registration because JVM properties and sessions.xml element are both not set ====
+
==== UC3.2 No MBean registration sessions.xml element is not set ====
+
==== UC3.3 No MBean registration because JVM properties are not set ====
+
 
+
=== UC4: Variant: Attempt to register 2 sessions with the same name ===
+
Fails before MBean registration step as expected with
+
 
+
Exception Description: Attempted to redeploy a session named eclipselinkwls without closing it.
+
=== UC5: Variant: Attempt to register with a default EAR session containing a ":"===
+
Converted to to "_" and processed
+
 
+
=== UC6: Variant: Attempt to register with a named session containing a space===
+
<source lang="xml"><property name="eclipselink.session-name" value="eclipselink wls"/></source>
+
Proceeds ok
+
 
+
=== UC7: Exception handling ===
+
==== UC7.1: NoAccessRuntimeException ====
+
weblogic.management.NoAccessRuntimeException: Access not allowed for subject: principals=[], on ResourceType: Reporting Action: unregister, Target: null
+
 
+
== Testing ==
+
A formal JMX J2SE client test suite is required.
+
 
+
===Manual Testing Results===
+
Action: Runtime | resetAllConnections
+
<pre>
+
[EL Config]: 2008.06.24 09:34:32.072--ServerSession(31078592)--Connection(4360542)--Thread(Thread[RMI TCP Connection(2)-10.156.52.98,5,RMI Runtime])--Connected: jdbc:bea:oracle://127.0.0.1:1521;CATALOGOPTIONS=2;CONNECTIONRETRYDELAY=1;SUPPORTLINKS=false;MAXPOOLEDSTATEMENTS=0;KEYSTORE=;ENABLECANCELTIMEOUT=false;TRUSTSTOREPASSWORD=;VALIDATESERVERCERTIFICATE=true;CODEPAGEOVERRIDE=;REFCURSORSUPPORT=true;KEYSTOREPASSWORD=;CONNECTIONRETRYCOUNT=5;SENDFLOATPARAMETERSASSTRING=false;COMMITBEHAVIOR=serverDefault;TNSSERVERNAME=;BATCHPERFORMANCEWORKAROUND=false;INITIALIZATIONSTRING=;RESULTSETMETADATAOPTIONS=0;QUERYTIMEOUT=0;HOSTNAMEINCERTIFICATE=;WIREPROTOCOLMODE=1;CATALOGINCLUDESSYNONYMS=true;JAVADOUBLETOSTRING=false;LOADLIBRARYPATH=;IMPORTSTATEMENTPOOL=;ALTERNATESERVERS=;KEYPASSWORD=;ENCRYPTIONMETHOD=noEncryption;CONVERTNULL=1;TRUSTSTORE=;TNSNAMESFILE=;AUTHENTICATIONMETHOD=auto;SERVICENAME=;SERVERTYPE=;LOADBALANCING=false;SID=orcl;WORKAROUNDS=0;INSENSITIVERESULTSETBUFFERSIZE=2048;SYSLOGINROLE=;FETCHTSWTZASTIMESTAMP=false
+
</pre>
+
 
+
Action: Runtime | getNumberOfObjectsInIdentityMap(org.eclipse.persistence.example.unified.business.StatLabel) == 84
+
<pre>[EL Config]: 2008.06.24 09:34:32.072--ServerSession(31078592)--Connection(4360542)--Thread(Thread[RMI TCP Connection(2)-10.156.52.98,5,RMI Runtime])--Connected: jdbc:bea:oracle://127.0.0.1:1521;CATALOGOPTIONS=2;CONNECTIONRETRYDELAY=1;SUPPORTLINKS=false;MAXPOOLEDSTATEMENTS=0;KEYSTORE=;ENABLECANCELTIMEOUT=false;TRUSTSTOREPASSWORD=;VALIDATESERVERCERTIFICATE=true;CODEPAGEOVERRIDE=;REFCURSORSUPPORT=true;KEYSTOREPASSWORD=;CONNECTIONRETRYCOUNT=5;SENDFLOATPARAMETERSASSTRING=false;COMMITBEHAVIOR=serverDefault;TNSSERVERNAME=;BATCHPERFORMANCEWORKAROUND=false;INITIALIZATIONSTRING=;RESULTSETMETADATAOPTIONS=0;QUERYTIMEOUT=0;HOSTNAMEINCERTIFICATE=;WIREPROTOCOLMODE=1;CATALOGINCLUDESSYNONYMS=true;JAVADOUBLETOSTRING=false;LOADLIBRARYPATH=;IMPORTSTATEMENTPOOL=;ALTERNATESERVERS=;KEYPASSWORD=;ENCRYPTIONMETHOD=noEncryption;CONVERTNULL=1;TRUSTSTORE=;TNSNAMESFILE=;AUTHENTICATIONMETHOD=auto;SERVICENAME=;SERVERTYPE=;LOADBALANCING=false;SID=orcl;WORKAROUNDS=0;INSENSITIVERESULTSETBUFFERSIZE=2048;SYSLOGINROLE=;FETCHTSWTZASTIMESTAMP=false
+
</pre>
+
 
+
 
+
Action: DevelopmentServices | initializeIdentityMap p1=org.eclipse.persistence.example.unified.business.StatLabel
+
<pre>
+
[EL Finer]: 2008.06.24 08:58:13.722--ServerSession(32676101)--Thread(Thread[RMI TCP Connection(16)-10.156.52.98,5,RMI Runtime])--
+
initialize identitymaps
+
[EL Finer]: 2008.06.24 08:59:04.004--ServerSession(32676101)--Thread(Thread[RMI TCP Connection(18)-10.156.52.98,5,RMI Runtime])--
+
initialize identitymap: class org.eclipse.persistence.example.unified.business.StatLabel
+
</pre>
+
 
+
===Extended Manual Testing===
+
We need access to a cluster and need to setup multiple connection pools.
+
 
+
== API ==
+
No new jar dependencies.
+
 
+
The JMX API is included in J2SE 1.5 (new to J2SE 1.5 from J2EE 1.4) - the interfaces from this JMX API is 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
+
 
+
[http://java.sun.com/j2se/1.5.0/docs/guide/management/mxbeans.html J2SE 1.5 JMX]
+
 
+
JMX used to be in J2EE 1.4
+
 
+
[http://java.sun.com/j2ee/1.4/docs/api/javax/management/MBeanServer.html J2EE 1.4 JMX]
+
 
+
 
+
*UML Class Diagram
+
[[Image:Eclipselink_uml_design_jmx.jpg]]
+
*UML Sequence Diagram
+
 
+
== GUI ==
+
===<JAVA_HOME>/bin/JConsole client===
+
You should see the following EclipseLink MBeans off the root of the JNDI tree.  In this example there are 2 separate EARs deployed to WebLogic - each with its own set of MBeans based on the login session.
+
 
+
[[Image:Eclipselink_jmx_mbeans_in_jconsole.jpg]]
+
 
+
== Config files ==
+
 
+
== Documentation ==
+
 
+
http://wiki.eclipse.org/Integrating_EclipseLink_with_an_Application_Server_(ELUG)#How_to_Integrate_JMX
+
 
+
- move and rewrite for WebLogic
+
 
+
http://wiki.eclipse.org/Configuring_a_Session_%28ELUG%29#Configuring_the_Server_Platform
+
 
+
- WebLogic replaces the other server in
+
 
+
"Check this field to configure the EclipseLink runtime to enable the deployment of a JMX MBean that allows monitoring of the EclipseLink session. Currently, this is only supported for "
+
 
+
== Open Issues ==
+
 
+
 
+
{|{{BMTableStyle}}
+
|-{{BMTHStyle}}
+
! Issue #
+
! Owner
+
! Description / Notes
+
|-
+
|I1
+
| mobrien
+
|[http://bugs.eclipse.org/238408 238408] Add cache synchronization and clustering service functionality to developmentServices MBean
+
|-
+
|I2
+
|
+
|[http://bugs.eclipse.org/238246 238246] Wiki Documentation changes
+
|-
+
|I3
+
|mobrien
+
|[http://bugs.eclipse.org/238252 238252] Method exceptions are not logged - they are only propagated to the client UI
+
|-
+
|I4
+
|mobrien
+
|[http://bugs.eclipse.org/238343 238343] unregisterMBean() causes NoAccessRuntimeException after successful registration
+
|-
+
|I5
+
|mobrien
+
|Investigate session timeout behavior
+
|-
+
|I6
+
|mobrien
+
|Investigate if DevelopmentServices.refreshProject() should unregister MBean via its logout/login sequence
+
|-
+
|I7
+
|mobrien
+
|[http://bugs.eclipse.org/238412 238412] - Add J2SE scriptable JMX Client test suite
+
|-
+
|I8
+
|mobrien
+
|Test this MBean implementation on other application servers and WLS 6-9
+
|}
+
 
+
== Decisions ==
+
 
+
 
+
{|{{BMTableStyle}}
+
|-{{BMTHStyle}}
+
! Issue #
+
! Description / Notes
+
! Decision
+
|-
+
|
+
|
+
|
+
|}
+
 
+
== Future Considerations ==
+
 
+
During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.
+
 
+
* OC4J, WebSphere, JBoss, Geronimo specific MBean support
+

Latest revision as of 09:40, 13 July 2010

  • 248748 : JMX support for WebLogic
  • 316513 : JMX support for WebSphere, JBoss and Glassfish

Back to the top