5 Navigating MBeans (WLST Online)
The following sections describe how to navigate, interrogate, and edit MBeans using WLST:
Navigating and Interrogating MBeans
WLST online provides simplified access to MBeans. While JMX APIs require you to use JMX object names to interrogate MBeans, WLST enables you to navigate a hierarchy of MBeans in a similar fashion to navigating a hierarchy of files in a file system.
WebLogic Server organizes its MBeans in a hierarchical data model. In the WLST file system, MBean hierarchies correspond to drives; MBean types and instances are directories; MBean attributes and operations are files. WLST traverses the hierarchical structure of MBeans using commands such as cd, ls, and pwd in a similar way that you would navigate a file system in a UNIX or Windows command shell. After navigating to an MBean instance, you interact with the MBean using WLST commands.
In the configuration hierarchy, the root directory is DomainMBean (see "DomainMBean" in the Oracle WebLogic Server MBean Reference); the MBean type is a subdirectory under the root directory; each instance of the MBean type is a subdirectory under the MBean type directory; and MBean attributes and operations are nodes (like files) under the MBean instance directory. The name of the MBean instance directory matches the value of the MBean's Name attribute. If the MBean does not have a Name attribute, WLST generates a directory name using the following pattern: NO_NAME_number, where number starts at 0 (zero) and increments by 1 for each additional MBean instance.
WLST first connects to a WebLogic Server instance at the root of the server's configuration MBeans, a single hierarchy whose root is DomainMBean. WLST commands provide access to all the WebLogic Server MBean hierarchies within a WebLogic domain, such as a server's run-time MBeans, run-time MBeans for domain-wide services, and an editable copy of all the configuration MBeans in the domain. For more information, see "Tree Commands" in WebLogic Scripting Tool Command Reference.
For more information about MBean hierarchies, see "WebLogic Server MBean Data Model" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server.
Changing the Current Management Object
WLST online provides a variable, cmo, that represents the current management object. You can use this variable to perform any get, set, or invoke method on the management object. For example, the cmo variable enables the following command:
wls:/mydomain/edit> cmo.setAdministrationPort(9092)
The variable is available in all WLST hierarchies except custom and jndi.
WLST sets the value of cmo to the current WLST path. Each time you change directories, WLST resets the value of cmo to the current WLST path. For example, when you change to the serverRuntime hierarchy, cmo is set to ServerRuntime. When you change to the serverConfig hierarchy, cmo is set to DomainMBean. If you change to the Servers directory under DomainMBean, cmo is set to an instance of ServerMBean (see Example 5-1).
Example 5-1 Changing the Current Management Object
C:\> java weblogic.WLST Initializing WebLogic Scripting Tool (WLST) ... Welcome to Weblogic Server Administration Scripting Shell ... wls:/(offline)> connect('username','password') Connecting to weblogic server instance running at t3://localhost:7001 as username weblogic ... Successfully connected to Admin Server 'myserver' that belongs to domain 'mydomain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, the SSL port or Admin port should be used instead. wls:/mydomain/serverConfig> cmo [MBeanServerInvocationHandler]com.bea:Name=mydomain,Type=Domain wls:/mydomain/serverConfig> cd('Servers') wls:/mydomain/serverConfig/Servers> cmo [MBeanServerInvocationHandler]com.bea:Name=mydomain,Type=Domain wls:/mydomain/serverConfig/Servers> cd('myserver') wls:/mydomain/serverConfig/Servers/myserver> cmo [MBeanServerInvocationHandler]com.bea:Name=myserver,Type=Server
For more information on WLST variables, see "WLST Variable Reference" in WebLogic Scripting Tool Command Reference.
Navigating and Displaying Configuration MBeans Example
The commands in Example 5-2 instruct WLST to connect to an Administration Server instance and display attributes, operations, and child MBeans in DomainMBean.
Example 5-2 Navigating and Displaying Configuration MBeans
C:\> java weblogic.WLST wls:/offline> connect('username','password') wls:/mydomain/serverConfig> ls() dr-- AppDeployments dr-- BridgeDestinations dr-- Clusters dr-- DeploymentConfiguration dr-- Deployments dr-- EmbeddedLDAP ... -r-- AdminServerName myserver -r-- AdministrationMBeanAuditingEnabled false -r-- AdministrationPort 9002 -r-- AdministrationPortEnabled false -r-- AdministrationProtocol t3s -r-- ArchiveConfigurationCount 5 ... wls:/mydomain/serverConfig> cd('Servers') wls:/mydomain/serverConfig/Servers> ls() dr-- managed1 dr-- myserver wls:/mydomain/serverConfig/Servers> cd('myserver') wls:/mydomain/serverConfig/Servers/myserver> ls() dr-- COM dr-- CandidateMachines dr-- Cluster dr-- DefaultFileStore dr-- ExecutiveQueues dr-- IIOP dr-- JTAMigrateableTarget dr-- Log dr-- Machine dr-- NetworkAccessPoints dr-- OverloadProtection dr-- SSL ... -r-- AcceptBacklog 50 -r-- AdminReconnectIntervalSeconds 10 -r-- AdministrationPort 0 -r-- AdministrationPortAfterOverride 9002 -r-- AdministrationPortEnabled false -r-- AdministrationProtocol t3s -r-- AutoKillIfFailed false -r-- AutoRestart true .... wls:/mydomain/serverConfig/Servers/myserver> cd('Log/myserver') wls:/mydomain/serverConfig/Servers/myserver/Log/myserver> ls() dr-- DomainLogBroadcastFilter dr-- LogFileFilter dr-- MemoryBufferFilter dr-- StdoutFilter -r-- DomainLogBroadcastFilter null -r-- DomainLogBroadcastSeverity Warning -r-- DomainLogBroadcasterBufferSize 0 -r-- FileCount 7 -r-- FileMinSize 500 -r-- FileName myserver.log -r-- FileTimeSpan 24 -r-- Log4jLoggingEnabled false -r-- LogFileFilter null -r-- LogFileRotationDir null -r-- LogFileSeverity Debug -r-- MemoryBufferFilter null -r-- MemoryBufferSeverity Debug -r-- MemoryBufferSize 500 -r-- Name myserver -r-- Notes null -r-- NumberOfFilesLimited false -r-- RedirectStderrToServerLogEnabled false -r-- RedirectStdoutToServerLogEnabled false -r-- RotateLogOnStartup true -r-- RotationTime 00:00 -r-- RotationType bySize -r-- StdoutFilter null -r-- StdoutSeverity Warning -r-- Type Log -r-x isSet Boolean : String(propertyName) -r-x unSet Void : String(propertyName)
In the ls command output information, d designates an MBean with which you can use the cd command (analogous to a directory in a file system), r indicates a readable property, w indicates a writeable property, and x an executable operation.
Note:
The read, write, and execute indicators assume that there are no restrictions to the current user's access privileges. A specific user might not be able to read values that WLST indicates as readable because the user might not have been given appropriate permission by the policies in the WebLogic Security realm. See "Default Security Policies for MBeans" in the Oracle WebLogic Server MBean Reference.To navigate back to a parent MBean, enter the cd('..') command:
wls:/mydomain/serverConfig/Servers/myserver/Log/myserver> cmo [MBeanServerInvocationHandler]mydomain:Name=myserver,Server=myserver,Type=Log wls:/mydomain/serverConfig/Servers/myserver/Log/myserver> cd('..') wls:/mydomain/serverConfig/Servers/myserver/Log> wls:/mydomain/serverConfig/Servers/myserver/Log> cmo [MBeanServerInvocationHandler]mydomain:Name=myserver,Type=Server
After navigating back to the parent MBean type, WLST changes the cmo from LogMBean to ServerMBean.
To get back to the root MBean after navigating to an MBean that is deep in the hierarchy, enter the cd('/') command.
Browsing Runtime MBeans
Similar to the configuration information, WebLogic Server run-time MBeans are arranged in a hierarchical data structure. When connected to an Administration Server, you access the run-time MBean hierarchy by entering the serverRuntime or the domainRuntime command. The serverRuntime command places WLST at the root of the server run-time management objects, ServerRuntimeMBean; the domainRuntime command, at the root of the domain-wide run-time management objects, DomainRuntimeMBean. When connected to a Managed Server, the root of the run-time MBeans is ServerRuntimeMBean. The domain run-time MBean hierarchy exists on the Administration Server only; you cannot use the domainRuntime command when connected to a Managed Server.
For more information, see "ServerRuntimeMBean" and "DomainRuntimeMBean" in the Oracle WebLogic Server MBean Reference.
Using the cd command, WLST can navigate to any of the run-time child MBeans. The navigation model for run-time MBeans is the same as the navigation model for configuration MBeans. However, run-time MBeans exist only on the same server instance as their underlying managed resources (except for the domain-wide run-time MBeans on the Administration Server) and they are all un-editable.
Navigating and Displaying Runtime MBeans Example
The commands in Example 5-3 instruct WLST to connect to an Administration Server instance, navigate, and display server and domain run-time MBeans.
Example 5-3 Navigating and Displaying Runtime MBeans
wls:/(offline) > connect('username','password') wls:/mydomain/serverConfig> serverRuntime() Location changed to serverRuntime tree. This is a read-only tree with ServerRuntimeMBean as the root. For more help, use help('serverRuntime') wls:/mydomain/serverRuntime> ls() dr-- ApplicationRuntimes dr-- ClusterRuntime dr-- ConnectorServiceRuntime ... dr-- JDBCServiceRuntime dr-- JMSRuntime dr-- JTARuntime dr-- JVMRuntime dr-- LibraryRuntimes dr-- MailSessionRuntimes dr-- RequestClassRuntimes dr-- ServerChannelRuntimes dr-- ServerSecurityRuntime dr-- ServerServices dr-- ThreadPoolRuntime dr-- WLDFAccessRuntime dr-- WLDFRuntime dr-- WTCRuntime dr-- WorkManagerRuntimes -r-- ActivationTime 1093958848908 -r-- AdminServer true -r-- AdminServerHost -r-- AdminServerListenPort 7001 -r-- AdminServerListenPortSecure false -r-- AdministrationPort 9002 -r-- AdministrationPortEnabled false ... wls:/mydomain/serverRuntime> domainRuntime() Location changed to domainRuntime tree. This is a read-only tree with DomainRuntimeMBean as the root. For more help, use help('domainRuntime') wls:/mydomain/domainRuntime> ls() dr-- DeployerRuntime ... dr-- ServerLifecycleRuntimes dr-- ServerRuntimes -r-- ActivationTime Tue Aug 31 09:27:22 EDT 2004 -r-- Clusters null -rw- CurrentClusterDeploymentTarget null -rw- CurrentClusterDeploymentTimeout 0 -rw- Name mydomain -rw- Parent null -r-- Type DomainRuntime -r-x lookupServerLifecycleRuntime javax.management.ObjectName : java.lang.String wls:/mydomain/domainRuntime>
The commands in Example 5-4 instruct WLST to navigate and display run-time MBeans on a Managed Server instance.
Example 5-4 Navigating and Displaying Runtime MBeans on a Managed Server
wls:/offline> connect('username','password','t3://localhost:7701') Connecting to weblogic server instance running at t3://localhost:7701 as username weblogic ... Successfully connected to managed Server 'managed1' that belongs to domain 'mydomain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, the SSL port or Admin port should be used instead. wls:/mydomain/serverConfig> serverRuntime() wls:/mydomain/serverRuntime> ls() dr-- ApplicationRuntimes dr-- ClusterRuntime ... dr-- JMSRuntime dr-- JTARuntime dr-- JVMRuntime dr-- LibraryRuntimes dr-- MailSessionRuntimes dr-- RequestClassRuntimes dr-- ServerChannelRuntimes dr-- ServerSecurityRuntime dr-- ThreadPoolRuntime dr-- WLDFAccessRuntime dr-- WLDFRuntime dr-- WTCRuntime dr-- WorkManagerRuntimes -r-- ActivationTime 1093980388931 -r-- AdminServer false -r-- AdminServerHost localhost -r-- AdminServerListenPort 7001 -r-- AdminServerListenPortSecure false -r-- AdministrationPort 9002 -r-- AdministrationPortEnabled false ... wls:/mydomain/serverRuntime>
Navigating Among MBean Hierarchies
To navigate to a configuration MBean from the run-time hierarchy, enter the serverConfig or domainConfig (if connected to an Administration Server only) command. This places WLST at the configuration MBean to which you last navigated before entering the serverRuntime or domainRuntime command.
The commands in the following example instruct WLST to navigate from the run-time MBean hierarchy to the configuration MBean hierarchy and back:
wls:/mydomain/serverRuntime/JVMRuntime/managed1> serverConfig() Location changed to serverConfig tree. This is a read-only tree with DomainMBean as the root. For more help, use help('serverConfig') wls:/mydomain/serverConfig> cd ('Servers/managed1') wls:/mydomain/serverConfig/Servers/managed1> cd('Log/managed1') wls:/mydomain/serverConfig/Servers/managed1/Log/managed1> serverRuntime() wls:/mydomain/serverRuntime/JVMRuntime/managed1>
Entering the serverConfig command from the run-time MBean hierarchy again places WLST at the configuration MBean to which you last navigated.
wls:/mydomain/serverRuntime/JVMRuntime/managed1> serverConfig()
wls:/mydomain/serverConfig/Servers/managed1/Log/managed1>
For more information, see "Tree Commands" in WebLogic Scripting Tool Command Reference.
Alternatively, you can use the currentTree command to store your current MBean hierarchy location and to return to that location after navigating away from it. See "currentTree" in WebLogic Scripting Tool Command Reference.
For example:
wls:/mydomain/serverConfig/Servers/managed1/Log/managed1> myLocation = currentTree() wls:/mydomain/serverConfig/Servers/managed1/Log/managed1> serverRuntime() wls:/mydomain/serverRuntime> cd('JVMRuntime/managed1') wls:/mydomain/serverRuntime/JVMRuntime/managed1>myLocation() wls:/mydomain/serverConfig/Servers/managed1/Log/managed1>
Finding MBeans and Attributes
To locate a particular MBean and attribute, you use the find command. WLST returns the pathname to the MBean that stores the attribute and its value. You can use the getMBean command to return the MBean specified by the path. For more information, see "find" and "getMBean" in WebLogic Scripting Tool Command Reference.
For example:
wls:/mydomain/edit !> find('logfilename') searching ... /ApplicationRuntimes/myserver_wlnav.war/WebAppComponentRuntime/myserver_myserver _wlnav.war_wlnav_/wlnavLogFilename null /Servers/myserver JDBCLogFileName jdbc.log /Servers/myserver/WebServer/myserver LogFileName access.log wls:/mydomain/edit !> bean=getMBean('Servers/myserver/WebServer/myserver') wls:/mydomain/edit !> print bean [MBeanServerInvocationHandler]mydomain:Name=myserver,Type=WebServer, Server=myserver wls:/mydomain/edit !>
Note:
getMBean does not throw an exception when an instance is not found.Alternatively, the getPath command returns the MBean path for a specified MBean instance or ObjectName for the MBean in the current MBean hierarchy. See "getPath" in WebLogic Scripting Tool Command Reference.
wls:/mydomain/serverConfig>path=getPath('com.bea:Name=myserver,Type=Server') wls:/mydomain/serverConfig> print path Servers/myserver
Accessing Other WebLogic MBeans and Custom MBeans
In addition to accessing WebLogic Server MBeans, WLST can access MBeans that WebLogic Integration and WebLogic Portal provide. It can also access MBeans that you create and register (custom MBeans) to configure or monitor your own resources. (For information on creating and registering your own MBeans, see "Instrumenting and Registering Custom MBeans" in Developing Manageable Applications With JMX for Oracle WebLogic Server.)
To navigate other WebLogic MBeans or custom MBeans, enter the custom command or the domainCustom command, depending on the MBean server (Runtime or Domain Runtime) on which the custom MBean is registered. You can use custom when WLST is connected to an Administration Server or a Managed Server instance. You can use domainCustom only when WLST is connected to an Administration Server. See Accessing Custom MBeans in the Domain Runtime MBean Server, for information about domainCustom.
WLST treats all non-WebLogic Server MBeans as custom MBeans:
-
Instead of arranging custom MBeans in a hierarchy, WLST organizes and lists custom MBeans by JMX object name. All MBeans with the same JMX domain name are listed in the same WLST directory. For example, if you register all of your custom MBeans with JMX object names that start with
mycompany:, then WLST arranges all of your MBeans in a directory namedmycompany. -
Custom MBeans cannot use the
cmovariable because a stub is not available. -
Custom MBeans are editable, but not subject to the WebLogic Server change management process. You can use MBean
get,set,invoke, andcreateanddeletecommands on them without first entering thestartEditcommand. See Using WLST Online to Update an Existing WebLogic Domain.
Here is an example of navigating custom MBeans on the Runtime MBean Server:
wls:/mydomain/serverConfig> custom() Location changed to custom tree. This is a writable tree with No root. For more help, use help('custom') wls:/mydomain/custom> ls() drw- mycompany drw- anothercompany wls:/mydomain/custom> cd("mycompany") wls:/mydomain/custom/mycompany> ls() drw- mycompany:y1=x drw- mycompany:y2=x wls:/mydomain/custom/mycompany> cd("mycompany:y1=x") wls:/mydomain/custom/mycompany/mycompany:y1=x> ls() -rw- MyAttribute 10 wls:/mydomain/custom/mycompany/mycompany:y1=x>
Accessing Custom MBeans in the Domain Runtime MBean Server
Use the domainCustom() command to browse and invoke methods or perform operations on custom MBeans that are registered in the Domain Runtime MBean Server. This is similar to using the custom() command to access custom MBeans that are registered in the Runtime MBean Server, as described in Accessing Other WebLogic MBeans and Custom MBeans. You can use the domainCustom() command only when WLST is connected to the Administration Server.
For information on using domainCustom(), see "domainCustom" in the WebLogic Scripting Tool Command Reference.
For information on how to access custom MBeans in the Domain Runtime MBean server, see "Make Local Connections to the Domain Runtime MBean Server" in Developing Custom Management Utilities With JMX for Oracle WebLogic Server. For information on creating and registering your own MBeans, see "Instrumenting and Registering Custom MBeans" in Developing Manageable Applications With JMX for Oracle WebLogic Server.