WLST: Understanding WebLogic Server MBean Tree

The JMX specification does not impose a model for organizing MBeans. However, because the configuration of a WebLogic Server domain is specified in an XML document, WebLogic Server organizes its MBeans into a hierarchical model that reflects the XML document structure.^[1]

With WLST, you can navigate the hierarchy in a filesystem-like structure with subdirectories representing parent-child relationships. There are also "soft-links" with the ability to use the cd command to jump to other positions in the tree (very similar to what can be done on UNIX using the ln -s command).

In this article, we will cover different MBeen trees implemented in the WebLogic Server 12c.

Configuration vs. Runtime

There are two main kinds of MBeans in WLS:

• Configuration
• Used to configure WLS
• To navigate to a configuration MBean from the runtime hierarchy, enter the serverConfig or domainConfig () command.
• To edit configuration beans, you must be connected to an Administration Server, and you must navigate to the edit tree (see below) and start an edit session, as described in edit and startEdit, respectively.^[7]
• Runtime
• Used to monitor WLS and for some operation control—starting and stopping servers, shrinking data source connection pools.
• The root of the runtime MBeans is ServerRuntimeMBean
• When connected to 
• Administration Server
• You access the runtime MBean hierarchy by entering the serverRuntime() or the domainRuntime() command
• Managed Server
• You access the runtime MBean hierarchy by entering the serverRuntime() command

MBean Tree

WLS provides the following bean trees:

• edit
• Only available on the admin server, used to modify the configuration—config.xml and system resource files.
• In the configuration hierarchy, the root directory is DomainMBean; 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. 
• runtime
• Available on every server, used to view the configuration that server is using, and to access its monitoring data
• domain runtime
• Only available on the admin server, shadows the runtime beans of all of the running servers, provides single point of access for monitoring

Tree Commands

WLST 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.  Tree commands in WLST can be used to access to all the bean trees within a domain, 

• edit
• You can update an existing WebLogic domain in two modes:^[6]
• Offline mode^[3]
• Online mode^[4]
• When you connect to admin server, 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"^[8]
• runtime
• When connected to either an admin server or a managed server, you can access the run-time MBean hierarchy by entering the serverRuntime() command
• The serverRuntime() command places WLST at the root of the server run-time management objects, ServerRuntimeMBean.
• domain runtime
• When connected to an admin server,  you can access the domain run-time MBean hierarchy by entering domainRuntime() command.
• The domainRuntime() command places WLST at the root of the domain-wide run-time management objects, DomainRuntimeMBean.

References

1. WebLogic Server MBean Data Model
2. Navigating and Interrogating MBeans
3. Using WLST Offline to Update an Existing WebLogic Domain
4. Using WLST Online to Update an Existing WebLogic Domain
5. Editing Commands Reference
6. WLST: Offline and Online Modes (Xml and More)
7. Configuration MBean Hierarchy
8. WebLogic Scripting Tool Command Reference
9. Oracle WebLogic Server on Docker Containers (white paper)
10. WebLogic on Docker (GitHub)
• Sample Docker configurations to facilitate installation, configuration, and environment setup for DevOps users. This project includes quick start dockerfiles and samples for both WebLogic 12.1.3 and 12.2.1 based on Oracle Linux and Oracle JDK 8 (Server).

WLST: Offline and Online Modes

In this article, we will cover the following topics:

• How to invoke WLST?
• Offline and Online WLST
• How to switch from Offline to Online mode?

How to invoke WLST?

In a Windows environment, you can start WLST from the Start program by simply selecting:

Start | Programs | Oracle | Oracle Home | WebLogic Server 12c | Tools | WebLogic Scripting Tool

You can also invoke WLST from the command line by using:^[1]

• The java weblogic.WLST command or 
• The command script wlst.cmd (wlst.sh in UNIX)

java weblogic.WLST Command

D:\>cd Oracle\wls1036tx\user_projects\domains\base1_domain\bin
D:\Oracle\wls1036tx\user_projects\domains\base1_domain\bin>setDomainEnv.cmd
D:\Oracle\wls1036tx\user_projects\domains\base1_domain>java weblogic.WLST

Initializing WebLogic Scripting Tool (WLST) ...
Welcome to WebLogic Server Administration Scripting Shell
Type help() for help on available commands

wls:/offline>

Command Script wlst.cmd

D:\>cd Oracle\wls1036tx\oracle_common\common\bin
D:\Oracle\wls1036tx\user_projects\domains\base1_domain\bin> wlst.comd
CLASSPATH=C:\Oracle\MIDDLE~1\patch_wls1211\profiles\default\sys_manifest_classpath\weblogic_patch.jar;...

Initializing WebLogic Scripting tool (WLST)...
Type help() for help on available commands

wls:/offline>

Note that you use the wlst.cmd script from the ORACLE_HOME\oracle_common\common\bin directory and not a directory specific to any particular WebLogic Server domain.^[1]

Offline and Online WLST

As shown above, both WLST invocations bring you to the offline mode.  In the next section, we will show how to switch from offline to online mode and vice versa.  To begin with, here are what offline and online mode can and can't do:^[5]

	WLST Offline	WLST Online
Can Do	Create/modify domain templates Create domains Extend an existing domains by access and modify the configuration for an offline domain	Change configuration when servers are in RUNNING state View runtime data for monitoring various runtime MBeans performances Deploy applications targeting to Servers or clusters Start and stop servers or cluster members.
Can't Do	View runtime performance data Modify security data	Create a new domain (must be offline mode) You can only update an existing domain configuration.

Online Mode

In online mode, WLST needs to connect to an active Admin or Managed Server.  The WLST online commands are analogous to the Administration Console changes after connecting to Admin Server.  WLST in online mode acts as a Java Management Extensions (JMX) client that manages the domain's resources by modifying the server's in-memory runtime Management Beans (MBeans). Thus, WLST offers you all the domain management configuration capabilities as the Administration Console.

Offline Mode

In offline mode, WLST helps you extend a domain, create domain templates, and create domains with those templates. Since you aren't connected to an active Admin Server, you won't be able to modify domain configuration in offline mode.

The WLST offline configuration commands are analogous to the Configuration Wizard. You just need to know the navigation on the configuration MBean trees, modify the MBean attribute values. Internally WLST offline commands work on WebLogic domain Configuration Framework, which Configuration Wizard also uses.  Using either tool, modified configuration data are persisted consistently in  the domain’s config directory or in a domain template JAR.

You can list a summary of all online and offline commands from the command-line using the following commands, respectively:^[3,4]

help("online")
help("offline")

How to Switch from Offline to Online mode?

You can switch from offline to online mode and vice versa by using connect() and disconnect() commands. When you use connect() command at offline it will transfer your prompt to ServerConfig that indicates online command mode.  The following example shows you how:

wls:/offline> connect('weblogic', 'welcome1', 't3://myserver:7001')

Connecting to t3://myserver:7001 with userid 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> disconnect()

Disconnected from weblogic server: myserver

In order to...	Use this command...	To...	Use with WLST...
Connect to and disconnect from a WebLogic Server instance	connect	Connect WLST to a WebLogic Server instance.	Online or Offline
	disconnect	Disconnect WLST from a WebLogic Server instance.	Online

References

1. Oracle WebLogic Server 12c Administration Handbook
2. Oracle WebLogic Server 11g Administration Handbook
3. WLST Online and Offline Command Summary (11g)
4. WLST Command and Variable Reference (11g)
5. WLST Offline vs WLST Online
6. WebLogic Server 12c and WebLogic Server 11g Releases (OTN)
7. WLST FAQs

WebLogic: How to Create a WLS Domain?

In WebLogic Server, you can create a domain using:^[1]

• WebLogic Configuration Wizard
• WLST
• weblogic.Server (a command-line utility)

Your actual choice of a domain creation tool depends on whether you prefer a graphical or command-line interface, and whether you need to automate the domain creation process. Using above-mentioned tools, you can either create a domain or extend an existing domain.

In this article, we will look at two ways to create a WebLogic domain:

• Creating a new domain based on an existing domain
• Creating a new domain based on a domain template

Domain Template

A template is simply a jar file that contains the necessary scripts and files WebLogic Server needs to create or extend domains.

There are three basic types of templates in WebLogic Server:^[1]

• Domain Templates
• Help create an entire domain
• Defines the full set of resources within a WebLogic domain, including:
• Infrastructure components
• Applications
• Services
• Security options
• General environment and operating system options.
• Extension Templates
• Add to the functionality of a domain
• Oracle uses special extension templates for various Fusion Middleware products.
• Managed Server Templates
• Defines the subset of resources within a WebLogic domain that are required to create a Managed Server domain directory on a remote machine. 

You can create the first two types of templates with the Domain Template Builder,^[2] and you can create all three types with the pack utility.^[3]

Creating a New Domain Based on an Existing Domain

Follow these steps to create a new domain using WLST offline commands:

1. Execute the readDomain command to open an existing WebLogic domain
• wls:/offline>readDomain('C:/Oracle/Middleware/user_projects/domains/base_domain')
• wls:/offline/base_domain>
2. Execute the writeTemplate command to write the current domain configuration to a specific domain template.
• wls:/offline/base_domain>writeTemplate('C:/Oracle/Middleware/user_templates/MyBaseTemplate.jar')
• wls:/offline/base_domain>
3. Execute the closeDomain command to close it
• wls:/offline/base_domain>closeTemplate()
• wls:/offline/base_domain>
4. Execute writeDomain command to create a new domain
• wls:/offline/base_domain>createDomain('C:/Oracle/Middleware/user_templates/ws_server_12.1.2.0.jar', 'C:/Oracle/Middleware/user_projects/domains/my_domain1','weblogic','welcome1')
• wls:/offline/base_domain>

You won’t receive any confirmation that the domain has been created, but the absence of any error messages means that the domain was successfully created. Note that the createDomain WLST command works essentially the same as the unpack command.^[3]

Creating a New Domain Based on a Domain Template

Probably the easiest way to create a domain is through the Configuration Wizard. The Configuration Wizard uses default templates to create or extend an existing domain.

Follow these steps to create a new domain using Configuration Wizard on Windows:^[1,7,8]

1. Click the Windows shortcut at Start | Programs | Oracle | OracleHome | WebLogic Server 12c | Tools | Configuration Wizard
2. Select Create A New Domain On the Create Domain screen
3. Choose one of the following two options on the Templates screen
• Create Domain Using Product Templates
• Create Domain Using Custom Template
4. Specify the login credentials for this new domain on the Administrator Account screen
5. Configure startup mode and JDK on the Domain Mode And JDK screen
6. Configure the database schemas on the Configure JDBC Data Sources screen
7. Specify keystore password on the Configure Keystore Credentials screen
8. Perform certain advanced configuration tasks on the Advanced Configuration screen
9. Review your domain configuration settings on the Configuration Summary screen
10. Check Configuration Progress and Status

You can use Configuration Wizard to create a domain with just an Admin Server or a domain that includes additional Managed Servers or even a cluster. In addition, you can customize a domain by configuring JDBC settings, for example, to point to a different database rather than the default database (Apache Derby database) used by the domain and extension templates.

Avitek Medical Records Sample Domain

Avitek Medical Records Sample Domain Template is one of the WebLogic domain templates that are provided with your WebLogic Server installation.^[5] You can use it to extend the basic WebLogic Server domain, which creates the Avitek Medical Records sample domain.

This domain is a WebLogic Server sample application suite that demonstrates all aspects of the J2EE platform. Read [5] to view the details of generated domain output.

References

1. Oracle WebLogic Server 12c Administration Handbook
2. Using the Domain Template Builder to Create Domain Templates
3. Overview of the Pack and Unpack Commands
• pack and unpack Command Reference
4. WebLogic Server Templates (12c)
5. Avitek Medical Records Sample Domain Template
• Generated Domain Output
6. The Configuration File in WebLogic Server Domain — config.xml (Xml and More)
7. Configuring Your Oracle Service Bus Domain
8. WebLogic Server: Installation to Deployment in 30 Minutes
• To start the wizard on Windows, type:
• %WL_HOME%\common\bin\config.cmd
• To start the new domain, do:
• %MW_HOME%\user_projects\domains\dev_domain\startWebLogic.cmd
9. WebLogic Server 12c and WebLogic Server 11g Releases (OTN)
10. Configuration Wizard Screens (12.1.2)

How to Configure Logging Using Weblogic Scripting Tool

Weblogic Scripting Tool (WLST) is a command-line tool that runs on the same machine as the Weblogic server and allows the user to browse the configuration and state of the server through a tree of mbeans (managememnt beans).  It is based on the Java scripting interpreter, Jython.

Using WLST, you can configure a server instance’s logging and message output.  To determine which log attributes can be configured, see LogMBean and LogFileMBean in the WebLogic Server MBean Reference^[1].

In this article, we first show you how to configure log attributes from WebLogic Server Administration Console and then show you how to set attributes of LogMBean using WLST.

Modifying Attribute from WLS Console

To bring WLS Administration Console up, you type the following address into your browser's address field:

• http://<myserver>:7001/console

and log in with your credentials (say, "weblogic/weblogic1").  To modify "Rotation file size" of the log attribute, you do:

• Click "Lock & Edit"
• Select and Click:
• Environment > Servers > CRMDemo_server1 > Logging

You modify "Rotation file size" to be a different value and then activate your change.  

Next to the "Rotation file size" field, you can click on "More Info..." to see its detailed description.

As you can see, "Rotation file size" field is linked to the following MBean Attibute:

• LogMBean.FileMinSize

Modifying Attribute from WLST

Instead of modifying log attributes from the console, you can also achieve it by using WLST.

$cd $MW_HOME/wlserver_10.3/common/bin

$./wlst.sh

wls:/offline> connect("weblogic","weblogic1", "t3://localhost:7001")  

wls:/atgdomain/serverConfig> cd("Servers/CRMDemo_server1/Log/CRMDemo_server1")

wls:/atgdomain/serverConfig/Servers/CRMDemo_server1/Log/CRMDemo_server1> ls()
dr--   DomainLogBroadcastFilter
dr--   LogFileFilter
-r--   FileMinSize                                  5000
-r--   FileName                                     logs/CRMDemo_server1.log
 .
 .
 .
-r-x   unSet                                        Void : String(propertyName)

As shown above, this is what happened:

1. We connected to the server
2. We set Current Management Object (CMO) to the server log config
3. We listed all LogMBean attributes
4. Our log attribute FileMinSize was shown on the list

To modify "FileMinSize" log attribute, you can create a script (i.e., setFileMinSize.py) such as:

# Connect to the server
connect("weblogic","weblogic1","t3://localhost:7001")
edit()
startEdit()

# set CMO to the server log config
cd("Servers/CRMDemo_server1/Log/CRMDemo_server1")
ls()

# change LogMBean attributes
set("FileMinSize", 400)

# list the current directory to confirm the new attribute values
ls()

# save and activate the changes
save()
activate(block="true")

# all done...
exit()

References

1. WebLogic Server MBean Reference
2. Getting Runtime Information
3. Oracle® Fusion Middleware WebLogic Scripting Tool Command Reference 11g Release 1 (10.3.3)
4. My "enable debug logging" in OAM WLST script
5. Configuring WebLogic Logging Services
6. weblogic.Server Command-Line Reference
7. How to List Current Message Levels of All Loggers Using WLST?

How to Force Shutdown WebLogic Managed Server

WebLogic Server (WLS) provides several ways to start and stop server instances^[1]. The method that you choose depends on whether you prefer using the Administration Console or a command-line interface, and on whether you are using Node Manager to manage the server's life cycle.

In this article, we will show you how to force shutdown WLS Managed Server from the command-line. This may come in handy when your WLS Managed Servers have stuck threads and will take you minutes to connect to it using the Console. Also, you don't care about dropping any user sessions. For example, in our case, we are just running some performance benchmarks.

stopManagedWebLogic.sh

You can stop WLS Managed Server using stopManagedWebLogic.sh script provided in your domain:

• <domain_path>/bin

Note that the environment we demonstrate here is in Linux.  The syntax of the command is:

• DOMAIN_NAME/bin/stopManagedWebLogic.sh managed_server_name admin_url username password

For example, we use:

• ./stopManagedWebLogic.sh CRMDemo_server1 t3://<machine_name>:7001 weblogic weblogic1

However, the default setting is not FORCE SHUTDOWN as shown in the following output line:

Shutting down the server CRMDemo_server1 with force=false while connected to AdminServer ...

stopWebLogic.sh

stopManagedWebLogic.sh actually invokes stopWebLogic.sh indirectly as shown here:

 ${DOMAIN_HOME}/bin/stopWebLogic.sh $1 $2

To make it shutdown forcibly, you need to modify the following line in the stopWebLogic.sh from:

• echo "shutdown('${SERVER_NAME}','Server', ignoreSessions='true')" >>"shutdown.py"

to

• echo "shutdown('${SERVER_NAME}','Server', ignoreSessions='true', force='true')" >>"shutdown.py"

Note that WLST shutdown command^[2] is used to do the work in the script.

Sample Output

After changing the script file, we re-execute the command and here is the sample output:

Stopping Weblogic Server...

Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

Connecting to t3://<machine_name>:7001 with userid weblogic ...

Successfully connected to Admin Server 'AdminServer' that belongs to domain 'xxxx'.

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.

Shutting down the server CRMDemo_server1 with force=true while connected to AdminServer ...

......................................................

Exiting WebLogic Scripting Tool.

Done

Stopping Derby Server...

Stopping Admin Server

Because our change was done in stopWebLogic.sh, if you want to shutdown Admin Server, it also becomes FORCE SHUTDOWN as shown below:

$ ./stopWebLogic.sh

Stopping Weblogic Server...

Initializing WebLogic Scripting Tool (WLST) ...

Welcome to WebLogic Server Administration Scripting Shell

Type help() for help on available commands

Please enter your username :weblogic

Please enter your password :

Connecting to t3://<server_name>:7001 with userid weblogic ...

Successfully connected to Admin Server 'AdminServer' that belongs to domain 'atgdomain'.

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.

Shutting down the server AdminServer with force=true while connected to AdminServer ...

WLST lost connection to the WebLogic Server that you were

connected to, this may happen if the server was shutdown or

partitioned. You will have to re-connect to the server once the

server is available.

Disconnected from weblogic server: AdminServer

Disconnected from weblogic server:

Exiting WebLogic Scripting Tool.

Done

Stopping Derby Server...

Conclusion

Be warned that:

• If you force shutdown server instances, the server immediately stops all processing. Therefore, any pending session data may be lost. 
• Each WebLogic Server instance runs in its own JVM. If you are unable to shut down a server instance using the methods described, you can use an operating system command to kill the JVM.  However, if you kill the JVM for an Administration Server while the server is writing to the config.xml file, you can corrupt the config.xml file.

References

1. Oracle® Fusion Middleware Managing Server Startup and Shutdown for Oracle WebLogic Server 11g Release 1 (10.3.4)
2. WLST Command and Variable Reference
3. Starting and Stopping Fusion Applications the Right Way (Oracle A-Team)
4. Oracle WebLogic Server on Docker Containers (white paper)
5. WebLogic on Docker (GitHub)
• Sample Docker configurations to facilitate installation, configuration, and environment setup for DevOps users. This project includes quick start dockerfiles and samples for both WebLogic 12.1.3 and 12.2.1 based on Oracle Linux and Oracle JDK 8 (Server).