5 Navigating MBeans (WLST Online)

The following sections describe how to navigate, interrogate, and edit MBeans using WLST:

Navigating and Interrogating MBeans
Browsing Runtime MBeans
Navigating Among MBean Hierarchies
Finding MBeans and Attributes
Accessing Other WebLogic MBeans and Custom MBeans

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.

Figure 5-1 Configuration MBean Hierarchy

Description of "Figure 5-1 Configuration MBean Hierarchy"

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

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

wls:/offline> connect('username','password')
wls:/mydomain/serverConfig> ls()
dr--   AdminConsole
dr--   AppDeployments
dr--   BridgeDestinations
dr--   Clusters
dr--   CoherenceClusterSystemResources
dr--   CoherenceServers
dr--   CustomResources
dr--   DeploymentConfiguration
dr--   Deployments
...
-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--   AdminServer
dr--   managed1
dr--   myserver
wls:/mydomain/serverConfig/Servers> cd('myserver')
wls:/mydomain/serverConfig/Servers/myserver> ls()
dr--   COM
dr--   CandidateMachines
dr--   Cluster
dr--   CoherenceClusterSystemResource
dr--   DefaultFileStore
dr--   ExecutiveQueues
dr--   FederationServices
dr--   IIOP
dr--   JTAMigrateableTarget
dr--   Log
dr--   Machine
dr--   NetworkAccessPoints
...
-r--   AcceptBacklog                                50
-r--   AdminReconnectIntervalSeconds                10
-r--   AdministrationPort                           0
-r--   AdministrationProtocol                       t3s
-r--   AutoKillIfFailed                             false
-r--   AutoMigrationEnabled                         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--   BufferSize                                   8
-r--   DateForatPattern                             MMM d, yyyy h:mm:ss a z
-r--   DomainLogBroadcastFilter                     null
-r--   DomainLogBroadcastSeverity                   Warning
-r--   DomainLogBroadcasterBufferSize               1
-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--   LoggerSeverity                               Info
-r--   LoggerSeverityProperties                     null
-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--   ServerLogBridgeUseParentLoggersEnabled       false
-r--   StdoutFilter                                 null
-r--   StdoutFormat                                 standard
-r--   StdoutLogStack                               true
-r--   StdoutSeverity                               Warning
-r--   Type                                         Log

-r-x   freezeCurrentValue                           Void : String(attributeName)

-r-x   isSet                                        Boolean : String(propertyName) 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('DebugEjbCaching') 

finding 'DebugEjbCaching' in all registered MBean instances ...

/Servers/AdminServer/ServerDebug/AdminServer                          false

/Servers/managed2/ServerDebug/managed2                           false

wls:/mydomain/edit !> bean=getMBean('Servers/managed2/ServerDebug/managed2') 
wls:/mydomain/edit !> print bean 
[MBeanServerInvocationHandler]bea.com:Name=managed2,Type=ServerDebug,
Server=managed2
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 named mycompany.
Custom MBeans cannot use the cmo variable 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, and create and delete commands on them without first entering the startEdit command. 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.