WebLogic Scripting Tool
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 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
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 domain, such as a server's runtime MBeans, runtime MBeans for domain-wide services, and an editable copy of all the configuration MBeans in the domain. For more information, see Tree Commands.
For more information about MBean hierarchies, see WebLogic Server MBean Data Model in Developing Custom Management Utilities with JMX.
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 Listing 5-1). Listing 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.
Navigating and Displaying Configuration MBeans Example
The commands in Listing 5-2 instruct WLST to connect to an Administration Server instance and display attributes, operations, and child MBeans in DomainMBean. Listing 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.
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 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 runtime MBeans are arranged in a hierarchical data structure. When connected to an Administration Server, you access the runtime MBean hierarchy by entering the serverRuntime or the domainRuntime command. The serverRuntime command places WLST at the root of the server runtime management objects, ServerRuntimeMBean; the domainRuntime command, at the root of the domain-wide runtime management objects, DomainRuntimeMBean. When connected to a Managed Server, the root of the runtime MBeans is ServerRuntimeMBean. The domain runtime 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 WebLogic Server MBean Reference.
Using the cd command, WLST can navigate to any of the runtime child MBeans. The navigation model for runtime MBeans is the same as the navigation model for configuration MBeans. However, runtime MBeans exist only on the same server instance as their underlying managed resources (except for the domain-wide runtime MBeans on the Administration Server) and they are all un-editable.
Navigating and Displaying Runtime MBeans Example
The commands in Listing 5-3 instruct WLST to connect to an Administration Server instance, navigate, and display server and domain runtime MBeans. Listing 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 Listing 5-4 instruct WLST to navigate and display runtime MBeans on a Managed Server instance. Listing 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 runtime 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 runtime 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 runtime 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.
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.
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.
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 !>
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.
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.)
To navigate other WebLogic MBeans or custom MBeans, enter the custom command when WLST is connected to an Administration Server or a Managed Server instance.
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 Domain.
The following is an example of navigating custom MBeans:
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>