The following sections describe how to navigate, interrogate, and edit MBeans using WLST:
WLST provides simplified access to MBeans. While the weblogic.Admin
utility (deprecated in this release of WebLogic Server) and WLST provide an interface for interacting with MBeans, the manner in which you retrieve MBeans is different.
The MBean-related commands that the weblogic.Admin
utility provides require you to determine the object name of the MBean with which you want to interact. While the object name is generated based on documented conventions, it can be difficult to accurately determine the object names of child MBeans several layers within a hierarchy.
WLST offers a different style of retrieving MBeans: instead of providing object names, you 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.
Note: | Because WLST offline enables you to access and update the configuration objects that appear in the configuration files only, if you wish to view and/or change attribute values for a configuration object that is not already persisted in the configuration files as an XML element, you must first create the configuration object. |
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; the name of the MBean (the MBean instance) is a subdirectory under the MBean type directory; and MBean attributes and operations are nodes (like files) under the MBean directory. Each MBean instance is a subdirectory of an MBean type. In most cases, there can be multiple instances of a type.
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.
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 4-1).
For more information on WLST variables, see WLST Variable Reference.
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]mydomain:Name=mydomain,Type=Domain
wls:/mydomain/serverConfig> cd('Servers')
wls:/mydomain/serverConfig/Servers> cmo
[MBeanServerInvocationHandler]mydomain:Name=mydomain,Type=Domain
wls:/mydomain/serverConfig/Servers> cd('myserver')
wls:/mydomain/serverConfig/Servers/myserver> cmo
[MBeanServerInvocationHandler]mydomain:Name=myserver,Type=Server
The commands in Listing 4-2 instruct WLST to connect to an Administration Server instance, navigate, and display MBeans in DomainMBean
. If no argument is specified, the ls
command lists all the child MBeans and attributes.
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 ls command property information is based on MBeanInfo ; it does not reflect user permissions. |
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.
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.
The commands in Listing 4-3 instruct WLST to connect to an Administration Server instance, navigate, and display server and domain 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 4-4 instruct WLST to navigate and display runtime MBeans on a Managed Server instance.
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>
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.
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>
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.
wls:/mydomain/edit !>
find('logfilename')
/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.
wls:/mydomain/serverConfig>
path=getPath('com.bea:Name=myserver,Type=Server')
wls:/mydomain/serverConfig>
print path
Servers/myserver
WebLogic Server provides hundreds of MBeans, many of which you use to configure and monitor EJBs, Web applications, and other deployable J2EE modules. If you want to use additional MBeans to configure your applications or resources, you can create and register your own MBeans within the MBean Server subsystem on the Administration Server.
For more information on custom MBeans, see “ Instrumenting and Registering Custom MBeans” in Developing Manageable Applications with JMX.
To navigate custom MBeans, enter the custom
command when WLST is connected to an Administration Server or a Managed Server instance. When connected to a WebLogic Integration or WebLogic Portal server, WLST can interact with all the WebLogic Integration or WebLogic Portal Server MBeans; non-WebLogic Server MBeans appear as custom MBeans.
WLST navigates, interrogates, and edits custom MBeans as it does configuration MBeans; however, custom MBeans cannot use the cmo
variable because a stub is not available.
Custom MBeans are editable, but not subjected to the WebLogic Server change management process. You can use MBean get and set methods, invoke, and create and delete methods on them without first entering the startEdit
command. See Editing Configuration MBeans.
Custom MBeans are listed by domain, as shown in the following example.
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- domain1
drw- domain2
drw- domain3
drw- domain4
wls:/mydomain/custom> cd("domain2")
wls:/mydomain/custom/domain2> ls()
drw- domain2:y1=x
drw- domain2:y2=x
wls:/mydomain/custom/domain2> cd("domain2:y1=x")
wls:/mydomain/custom/domain2/domain2:y1=x> ls()
-rw- MyAttribute 10
wls:/mydomain/custom/domain2/domain2:y1=x>
Within the Administration Server, there is a set of configuration MBeans in a single, editable hierarchy whose root is DomainMBean
. This hierarchy contains an editable copy of all configuration MBeans in the domain and it is used only as part of the change management process. The change management process is a controlled procedure for distributing configuration changes in a domain; a change process that loosely resembles a database transaction.
You start the editing process by obtaining a lock on the editable configuration hierarchy to prevent other people from making changes. When you finish making changes, you save and distribute them to all server instances in the domain. When you distribute changes, each server determines whether it can accept the change. If all servers are able to accept the change, they update their working hierarchy of configuration MBeans and the change is completed.
Note: | The configuration lock does not prevent two processes from starting an edit session under the same user identity. BEA Systems recommends against this because when one of the sessions activates their changes, it releases the lock and the other session will not be able to save or activate their changes. |
Note: | For example, if you start an edit session from WLST and start another concurrent edit session from the Administration Console under the same user name, when you save and activate your changes using WLST, you will lose the edits you are making with the Administration Console. |
For more information on making and managing configuration changes, see “ Configuration Change Management Process” in Understanding Domain Configuration and “ Managing a Domain’s Configuration with JMX” in Developing Custom Management Utilities with JMX.
The following basic steps describe the configuration editing process using WLST online:
edit
command. See edit.This places WLST at the root of the editable configuration hierarchy and obtains an exclusive configuration lock.
startEdit
command.
The startEdit
command initiates modifications that are treated as a part of a batch change that is not committed to the repository until you enter the save
command.
The startEdit
command must be called prior to invoking any command to modify the domain configuration. However, if WLST detects that there is an edit session that is already in progress by the same user, which might have been started via the Administration Console or another WLST session, it continues your edit session and you need not enter the startEdit
command. For detailed information about startEdit
command arguments, see startEdit.
To avoid the possibility that the configuration is locked indefinitely, you can specify a time-out period. Alternatively, an administrator can enter the cancelEdit
command to cancel an edit session and release the lock. See cancelEdit.
To indicate that configuration changes are in process, an exclamation point (!) appears at the end of the WLST command prompt.
Use the validate
command to ensure that changes you make are valid before saving them. See validate.
save
command.
The save
command saves your changes to a pending version of the config.xml
file; it does not release the lock. See save.
startEdit
command, or undo changes you have made by entering the undo
command.
The undo
command reverts all changes that have not been saved. See undo.
activate
command.
The activate
command initiates the distribution of the changes and releases the lock; the exclamation point is removed from the command prompt. See activate.
stopEdit
or the cancelEdit
command.
The stopEdit
command stops the current editing session and releases the edit lock. This command lets you discard any changes you made since last entering the save
command. See stopEdit.
The cancelEdit
command also stops the editing session and releases the configuration lock, discarding changes made since the last save
command. However, the user entering this command does not have to be the current editor; this allows an administrator to cancel an edit session. See cancelEdit.
The WLST online script in Listing 4-5 connects WLST to an Administration Server, initiates an edit session that creates a Managed Server, saves and activates the change, initiates another edit session, creates a startup class, and targets it to the newly created server.
Start WebLogic Server before running this script. See Running Scripts.
connect("username
","password
")
edit()
startEdit()
svr = cmo.createServer("managedServer")
svr.setListenPort(8001)
svr.setListenAddress("my-address")
save()
activate(block="true")
startEdit()
sc = cmo.createStartupClass("my-startupClass")
sc.setClassName("com.bea.foo.bar")
sc.setArguments("foo bar")
# get the server mbean to target it
tBean = getMBean("Servers/managedServer")
if tBean != None:
print "Found our target"
sc.addTarget(tBean)
save()
activate(block="true")
disconnect()
exit()
If you attempt to make changes without first entering the edit
command, WLST displays a message stating that you have not locked the configuration for changes and gives you the opportunity to do so. If you forget to call save
after entering the startEdit
command and attempt to exit the scripting shell, you are warned about the outstanding, non-committed changes. At that point you can commit or abandon all changes that you made to the configuration.
To determine if a change you made to an MBean attribute requires you to re-start the server, enter the isRestartRequired
command. If you enter the command during an edit session, before activating your changes, it will show the attribute changes in progress that will require you to re-start the server. If you enter the command after activating your changes, it displays the attribute changes that occurred that require you to re-start the server. See isRestartRequired.
WebLogic Server provides a Configuration Manager service to manage the change process. The getConfigManager
function returns the ConfigurationManagerMBean
(see
getConfigManager). ConfigurationManagerMBean
provides methods to start and stop edit sessions, and save, undo, and activate configuration changes. You use ConfigurationManagerMBean
methods to manage configuration changes across a domain. For detailed information, see
ConfigurationManagerMBean in the WebLogic Server MBean Reference.
The WLST online script in Listing 4-6 connects WLST to a server instance as an administrator, checks if the current editor making changes is a particular operator, then cancels the configuration edits. The script also purges all the completed activation tasks.
Start WebLogic Server before running this script. See Running Scripts.
connect("theAdministrator","weblogic")
cmgr = getConfigManager()
user = cmgr.getCurrentEditor()
if user == "operatorSam":
cmgr.undo()
cmgr.cancelEdit()
cmgr.purgeCompletedActivationTasks()
For all changes that are initiated by WLST, you can use the showChanges
command which displays all the changes that you made to the current configuration from the start of the edit session, including any MBean operations that were implicitly performed by the server. See Listing 4-7.
Start WebLogic Server before running this script. See Running Scripts.
wls:/offline> connect('username','password')
wls:/mydomain/serverConfig> edit()
wls:/mydomain/edit> startEdit()
Starting an edit session ...
wls:/mydomain/edit !> cmo.createServer('managed2')
[MBeanServerInvocationHandler]mydomain:Name=managed2,Type=Server
wls:/mydomain/edit !>cd('Servers/managed2')
wls:/mydomain/edit/Servers/managed2 !> cmo.setListenPort(7702)
wls:/mydomain/edit/Servers/managed2 !> showChanges()
Changes that are in memory and saved to disc but not yet activated are:
MBean Changed : mydomain:Name=mydomain,Type=Domain
Operation Invoked : add
Attribute Modified : Servers
Attributes Old Value : null
Attributes New Value : managed2
Server Restart Required : false
MBean Changed : mydomain:Name=managed2,Type=Server
Operation Invoked : modify
Attribute Modified : StagingDirectoryName
Attributes Old Value : null
Attributes New Value : .\managed2\stage
Server Restart Required : true
MBean Changed : mydomain:Name=managed2,Type=Server
Operation Invoked : modify
Attribute Modified : Name
Attributes Old Value : null
Attributes New Value : managed2
Server Restart Required : true
MBean Changed : mydomain:Name=managed2,Type=Server
Operation Invoked : modify
Attribute Modified : ListenPort
Attributes Old Value : null
Attributes New Value : 7702
Server Restart Required : false
wls:/mydomain/edit/Servers/managed2 !> save()
wls:/mydomain/edit !> activate()
Started the activation of all your changes.
The edit lock associated with this edit session is released once the activation is successful.
The Activation task for your changes is assigned to the variable 'activationTask'
You can call the getUser() or getStatusByServer() methods on this variable to determine the status of your activation
[MBeanServerInvocationHandler]mydomain:Type=ActivationTask
wls:/mydomain/edit/Servers/managed2>
The getActivationTask
function provides information about the activation request and returns the latest ActivationTaskMBean
which reflects the state of changes that a user is currently making or made recently. You invoke the methods that this interface provides to get information about the latest activation task in progress or just completed. For detailed information, see
ActivationTaskMBean in the WebLogic Server MBean Reference.
The WLST online script in Listing 4-8 connects WLST to a server instance as an administrator, gets the activation task, and prints the user and the status of the task. It also prints all the changes that took place.
Start WebLogic Server before running this script. See Running Scripts.
connect("theAdministrator","weblogic")
at = getActivationTask()
print "The user for this Task "+at.getUser()+" and the state is "+at.getState()
changes = at.getChanges()
for i in changes:
i.toString()