2 Using the WebLogic Scripting Tool
Using WLST Online or Offline
You can use WLST as the command-line equivalent to the WebLogic Server Administration Console (WLST online) or as the command-line equivalent to the Configuration Wizard (WLST offline).
The following sections describe how to use WLST online or offline:
Using WLST Online
You can use WLST to connect to a running Administration Server and manage the configuration of an active WebLogic domain, view performance data about resources in the domain, or manage security data (such as adding or removing users). You can also use WLST to connect to Managed Servers, but you cannot modify configuration data from Managed Servers.
WLST online is a Java Management Extensions (JMX) client. It interacts with a server's in-memory collection of Managed Beans (MBeans), which are Java objects that provide a management interface for an underlying resource. For information on WebLogic Server MBeans, see Understanding WebLogic Server MBeans in Developing Custom Management Utilities Using JMX for Oracle WebLogic Server.
Using WLST Offline
Without connecting to a running WebLogic Server instance, you can use WLST to create domain templates, create a new domain based on existing templates, or extend an existing, inactive domain. You cannot use WLST offline to view performance data about resources in a WebLogic domain or modify security data (such as adding or removing users).
WLST offline provides read and write access to the configuration data that is persisted in the domain's config
directory or in a domain template JAR created using Template Builder. See Browsing Information About the Configuration Hierarchy (Offline).
Note the following restrictions for modifying configuration data with WLST offline:
-
Oracle recommends that you do not use WLST offline to manage the configuration of an active WebLogic domain. Offline edits are ignored by running servers and can be overwritten by JMX clients such as WLST online or the WebLogic Server Administration Console.
-
As a performance optimization, WebLogic Server does not store most of its default values in the WebLogic domain's configuration files. In some cases, this optimization prevents management objects from being displayed by WLST offline (because WebLogic Server has never written the corresponding XML elements to the domain's configuration files). For example, if you never modify the default logging severity level for a WebLogic domain while the domain is active, WLST offline will not display the domain's
Log
management object.If you want to change the default value of attributes whose management object is not displayed by WLST offline, you must first use the
create
command to create the management object. Then you cancd
to the management object and change the attribute value. See create in WLST Command Reference for WebLogic Server.
Interactive Mode, Script Mode, and Embedded Mode
WLST can be invoked in a variety of ways.
You can use any of the following techniques to invoke WLST commands:
Interactive Mode
Interactive mode, in which you enter a command and view the response at a command-line prompt, is useful for learning the tool, prototyping command syntax, and verifying configuration options before building a script. Using WLST interactively is particularly useful for getting immediate feedback after making a critical configuration change. The WLST scripting shell maintains a persistent connection with an instance of WebLogic Server.
WLST can write all of the commands that you enter during a WLST session to a file. You can edit this file and run it as a WLST script. See startRecording and stopRecording in WLST Command Reference for WebLogic Server.
Script Mode
Scripts invoke a sequence of WLST commands without requiring your input, much like a shell script. Scripts contain WLST commands in a text file with a .py
file extension, for example, filename
.py
. You use script files with the Jython commands for running scripts.
Using WLST scripts, you can:
-
Automate WebLogic Server configuration and application deployment
-
Apply the same configuration settings, iteratively, across multiple nodes of a topology
-
Take advantage of scripting language features, such as loops, flow control constructs, conditional statements, and variable evaluations that are limited in interactive mode
-
Schedule scripts to run at various times
-
Automate repetitive tasks and complex procedures
-
Configure an application in a hands-free data center
For information about sample scripts that WebLogic Server installs, see WLST Sample Scripts.
Embedded Mode
In embedded mode, you instantiate the WLST interpreter in your Java code and use it to run WLST commands and scripts. All WLST commands and variables that you use in interactive and script mode can be run in embedded mode. Prior to running the program with embedded WLST, you must invoke the following command to set the appropriate environment variables:
-
Windows:
WL_HOME
\server\bin\setWLSEnv.cmd
-
UNIX:
WL_HOME
/server/bin/setWLSEnv.sh
On UNIX operating systems, the
setWLSEnv.sh
command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
Example 2-1 illustrates how to instantiate the WLST interpreter and use it to connect to a running server, create two servers, and assign them to clusters.
Example 2-1 Running WLST From a Java Class
package wlst; import java.util.*; import weblogic.management.scripting.utils.WLSTInterpreter; import org.python.util.InteractiveInterpreter; /** * Simple embedded WLST example that will connect WLST to a running server, * create two servers, and assign them to a newly created cluster and exit. * <p>Title: EmbeddedWLST.java</p> * <p>Copyright: Copyright (c) 2004</p> * <p>Company: Oracle</p> */ public class EmbeddedWLST { static InteractiveInterpreter interpreter = null; EmbeddedWLST() { interpreter = new WLSTInterpreter(); } private static void connect() { StringBuffer buffer = new StringBuffer(); buffer.append("connect('adminusername','adminpassword')"); interpreter.exec(buffer.toString()); } private static void createServers() { StringBuffer buf = new StringBuffer(); buf.append(startTransaction()); buf.append("man1=create('msEmbedded1','Server')\n"); buf.append("man2=create('msEmbedded2','Server')\n"); buf.append("clus=create('clusterEmbedded','Cluster')\n"); buf.append("man1.setListenPort(8001)\n"); buf.append("man2.setListenPort(9001)\n"); buf.append("man1.setCluster(clus)\n"); buf.append("man2.setCluster(clus)\n"); buf.append(endTransaction()); buf.append("print 'Script ran successfully ...' \n"); interpreter.exec(buf.toString()); } private static String startTransaction() { StringBuffer buf = new StringBuffer(); buf.append("edit()\n"); buf.append("startEdit()\n"); return buf.toString(); } private static String endTransaction() { StringBuffer buf = new StringBuffer(); buf.append("save()\n"); buf.append("activate(block='true')\n"); return buf.toString(); } public static void main(String[] args) { new EmbeddedWLST(); connect(); createServers(); } }
Security for WLST
WLST uses the WebLogic Security Framework to prevent unauthorized users from modifying a WebLogic domain or from viewing encrypted data.
The following sections describe the actions you must take to satisfy WLST security requirements:
Securing the WLST Connection
If you use WLST to connect to a WebLogic Server instance, Oracle recommends that you connect to the server instance through the administration port. The administration port is a special, secure port that all WebLogic Server instances in a WebLogic domain can use for administration traffic.
By default, this port is not enabled, but Oracle recommends that you enable the administration port in a production environment. The default value for the administration port is 9002
. Separating administration traffic from application traffic ensures that critical administration operations (starting and stopping servers, changing a server's configuration, and deploying applications) do not compete with high-volume application traffic on the same network connection.
The administration port requires all communication to be secured using SSL. By default, all servers in a WebLogic domain use demonstration certificate files for SSL, but these certificates are not appropriate for a production environment.
For information about configuring the administration port, see Administration Port and Administrative Channel in Administering Server Environments for Oracle WebLogic Server.
Securing Access to Configuration Data
A WebLogic domain stores its configuration data in a collection of XML documents that are saved in the domain directory. For example, these configuration documents describe the names, listen addresses, and deployed resources in the domain. When one or more servers in a WebLogic domain are running, each server instance maintains an in-memory representation of the configuration data as a collection of Managed Beans (MBeans).
You must use your own security measures to make sure that only authorized users can access your domain's configuration files through the file system. Anyone who is authorized to access the domain's configuration files through the file system can use a text editor, WLST offline, or other tools to edit the configuration files.
Securing Access from WLST Online
If you use WLST to connect to a running instance of WebLogic Server, you must provide the credentials (user name and password) of a user who has been defined in the active WebLogic security realm. Once you are connected, a collection of security policies determine which configuration attributes you are permitted to view or modify. (See Default Security Policies for MBeans in the MBean Reference for Oracle WebLogic Server.)
When you invoke the WLST connect
command, you can supply user credentials by doing any of the following:
-
Enter the credentials on the command line. This option is recommended only if you are using WLST in interactive mode.
For example:
connect('adminusername', 'adminpassword', 'localhost:7001'
See connect in WLST Command Reference for WebLogic Server.
-
Enter the credentials on the command line, and then use the
storeUserConfig
command to create a user configuration file that contains your credentials in an encrypted form and a key file that WebLogic Server uses to unencrypt the credentials. On subsequent WLST sessions (or in WLST scripts), supply the name of the file instead of entering the credentials on the command line. This option is recommended if you use WLST in script mode because it prevents you from storing unencrypted user credentials in your scripts.For example, to create the user configuration file and key file:
connect('adminusername', 'adminpassword', 'localhost:7001') storeUserConfig('c:/myFiles/myuserconfigfile.secure', 'c:/myFiles/myuserkeyfile.secure')
To use the user configuration file and key file:
connect(userConfigFile='c:/myfiles/myuserconfigfile.secure', userKeyFile='c:/myfiles/myuserkeyfile.secure')
See connect and storeUserConfig in WLST Command Reference for WebLogic Server.
-
Invoke the
connect
command from a directory that contains the domain'sboot.properties
file. By default, when you create an Administration Server, WebLogic Server encrypts the credentials and stores them in aboot.properties
file. WLST can use this file only if you start WLST from the domain directory.For example, if you have not deleted the domain's
boot.properties
file, you can start WLST and invoke the connect command as follows:c:\mydomain\> java weblogic.WLST wls:/offline> connect()
See connect in WLST Command Reference for WebLogic Server.
Writing and Reading Encrypted Configuration Values
Some attributes of a WebLogic domain's configuration are encrypted to prevent unauthorized access to sensitive data. For example, the password that a JDBC data source uses to connect to an RDBMS is encrypted.
The attribute values are saved in the domain's configuration document as an encrypted string. In a running server instance, the values are available as an MBean attribute in the form of an encrypted byte array. The names of encrypted attributes end with Encrypted. For example, the ServerMBean exposes the password that is used to secure access through the IIOP protocol in an attribute named DefaultIIOPPasswordEncrypted
.
Oracle recommends the following pattern for writing and reading encrypted attributes:
With WLST offline:
-
To write an encrypted value, pass the name of the encrypted attribute and an unencrypted string to the
set
command. For example:set('DefaultIIOPPasswordEncrypted', '<password>')
WLST encrypts the string and writes the encrypted value to the domain's configuration file.
See set in WLST Command Reference for WebLogic Server.
-
WLST offline does not display the unencrypted value of an encrypted attribute. If you use the
ls
command to display management attributes, WLST offline returns asterisks as the value of encrypted attributes. If you use theget
command, WLST offline returns a byte array that represents asterisks.For example:
wls:/offline/wl_server/Server/examplesServer>ls()
returns
... -rw- DefaultIIOPPasswordEncrypted ******** ...
While
wls:/offline/wl_server/Server/examplesServer>get('DefaultIIOPPasswordEncrypted')
returns
array([42, 42, 42, 42, 42, 42, 42, 42], byte)
See ls and get in WLST Command Reference for WebLogic Server.
With WLST online, for each encrypted attribute, an MBean also contains an unencrypted version. For example, ServerMBean contains an attribute named DefaultIIOPPasswordEncrypted
which contains the encrypted value and an attribute named DefaultIIOPPassword
, which contains the unencrypted version of the value.
To write and read encrypted values with WLST online:
-
To write an encrypted value, start an edit session. Then do either of the following:
-
Pass the name of the unencrypted attribute and an unencrypted string to the
set
command. For example:set('DefaultIIOPPassword', '<password>')
-
Pass the name of the encrypted attribute and an encrypted byte array to the set command. You can use the encrypt command to create the encrypted byte array (see encrypt in WLST Command Reference for WebLogic Server). For example:
set('DefaultIIOPPasswordEncrypted', encrypt('<password>'))
-
Note:
Do not pass an unencrypted string to the encrypted attribute. The encrypted attribute assumes that the value you pass to it is already encrypted.
When you activate the edit, WebLogic Server writes the encrypted value to the domain's configuration file.
-
-
To read the encrypted value of the attribute, pass the name of the encrypted attribute to the
get
command. For example:get('DefaultIIOPPasswordEncrypted')
returns
array([105, 114, 111, 110, 115, 116, 101, 101, 108], byte)
Securing Access to Security Data
The user names and passwords of WebLogic Server users, security groups, and security roles are not stored in a WebLogic domain's XML configuration files. Instead, a WebLogic domain uses a separate software component called an Authentication provider to store, transport, and provide access to security data. Authentication providers can use different types of systems to store security data. The Authentication provider that WebLogic Server installs uses an embedded LDAP server.
When you use WLST offline to create a domain template, WLST packages the Authentication provider's data store along with the rest of the domain documents. If you create a domain from the domain template, the new domain has an exact copy of the Authentication provider's data store from the domain template.
You cannot use WLST offline to modify the data in an Authentication provider's data store.
You can, however, use WLST online to interact with an Authentication provider and add, remove, or modify users, groups, and roles. See Managing Security Data (WLST Online).
Main Steps for Using WLST in Interactive or Script Mode
When you use WLST interactive or script mode, you should understand how to invoke it, exit it, and its syntax.
The following sections summarize the steps for setting up and using WLST:
Invoking WLST
You can invoke WLST in the following ways:
-
Execute the appropriate shell script for your environment and enter WLST commands from the WLST shell. See Invoking WLST Using Provided Shell Scripts.
-
Execute the
java weblogic.WLST
command. See Invoking WLST Using the java Command. -
Run a prepared WLST script when invoking the WLST shell script. See Running Scripts.
-
Execute the WebLogic Scripting Tool command from the Start menu (Windows only).
Note:
If you notice that it takes a long time to create or update a domain using WLST on a UNIX or Linux operating system, set the CONFIG_JVM_ARGS
environment variable to the following value to resolve this issue:
-Djava.security.egd=file:/dev/urandom
See also Running WLST from Ant.
Invoking WLST Using Provided Shell Scripts
To invoke WLST using a shell script, execute the command that is appropriate for your environment. This is the recommended way to invoke WLST. Environment variables are automatically set when you invoke WLST this way. You can then enter WLST commands from within the WLST shell.
Note:
The following commands apply only to standalone WebLogic Server installations (those that do not include other Fusion Middleware components). Many Fusion Middleware components supply custom WLST commands. To use them, you must invoke WLST from the appropriate directory. See Using Custom WLST Commands in Administering Oracle Fusion Middleware.
UNIX
cd ORACLE_HOME/oracle_common/common/bin
./wlst.sh
ORACLE_HOME
is the Oracle Home directory you specified at installation.
To set WLST properties in a UNIX environment prior to running WLST:
export WLST_PROPERTIES="-Dweblogic.security.SSL.ignoreHostnameVerification=true, -Dweblogic.security.TrustKeyStore=DemoTrust" ./wlst.sh
Note:
To avoid log file name collisions when multiple WLST offline processes are running, set the following property in the environment prior to invoking WLST:
export WLST_PROPERTIES="-Dwlst.offline.log=./logs/debug.log"
Windows
cd ORACLE_HOME\oracle_common\common\bin
wlst.cmd
ORACLE_HOME
is the Oracle Home directory you specified at installation.
Invoking WLST Using the java Command
To invoke WLST using the java command, you must first set up your environment for WLST. To set up your environment for WLST:
After setting up your environment, use the following syntax to invoke WLST.
java [ -Dweblogic.security.SSL.ignoreHostnameVerification=true -Dweblogic.security.TrustKeyStore=DemoTrust ] [ -Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=password] [ -Dweblogic.security.CustomTrustKeyStoreFileName=filename -Dweblogic.security.TrustKeystoreType=jks [ -Dweblogic.security.CustomTrustKeyStorePassPhrase=password]] [ -Dweblogic.security.SSL.hostnameVerifier=classname] weblogic.WLST [ -loadProperties propertyFilename ] [ -skipWLSModuleScanning ] [ [-i] filePath.py ]
See Table 2-1 for a description of the WLST command options. See Table 2-2 for a description of the SSL arguments. Table 2-3 lists additional optional startup arguments for WLST.
Table 2-1 Command Options for WLST
Option | Description |
---|---|
|
Use this option to load properties into the WLST session, where You cannot use this option when you are importing WLST as a Jython module (see Importing WLST as a Jython Module). Instead of using this command-line option, you can use the |
|
Use this option to reduce startup time by skipping package scanning and caching for WebLogic Server modules. |
|
Use this option to run a WLST script, where By default, WLST exits (stops the Java process) after it executes the script. Include Note: If a WLST script named Instead of using this command-line option, you can use the following command after you start WLST:
|
Table 2-2 SSL Arguments
Argument | Definition |
---|---|
|
Use these system properties if you plan to connect WLST to a WebLogic Server instance through an SSL listen port, and if the server instance is using the demonstration SSL keys and certificates.
By default, WLST trusts only the CA certificates in the Java Standard Trust keystore ( |
|
Password that was used to secure the Java Standard Trust keystore. If the Java Standard Trust keystore is protected by a password, and if you want to trust its CA certificates, you must use this argument. By default, the Java Standard Trust keystore is not protected by a password. |
|
Causes WLST to trust the CA certificates in a custom keystore that is located at filename. You must use both arguments to trust custom keystores. The filename must match exactly the |
|
Password that was used to secure the custom keystore. You must use this argument only if the custom keystore is protected by a password. |
|
Name of a custom Host Name Verifier class. The class must implement the |
Table 2-3 Additional WLST Startup Arguments
Argument | Description |
---|---|
|
If |
|
A comma-separated list of directory paths from which to load |
|
Sets the path and file name for WLST offline logging, for example, |
|
Sets the log priority level to debug for WLST offline logging. |
Example 2-2 Examples of Invoking WLST Using the Java Command
To use WLST in script mode:
java weblogic.WLST c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributeQueues.py
To run a WLST script on a WebLogic Server instance that uses the SSL listen port and the demonstration certificates:
java -Dweblogic.security.SSL.ignoreHostnameVerification=true -Dweblogic.security.TrustKeyStore=DemoTrust weblogic.WLST c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributeQueues.py
To use WLST in interactive mode:
java weblogic.WLST
To connect to a WebLogic Server instance after you start WLST in interactive mode:
wls:/offline> connect('adminusername','adminpassword','localhost:7001')
Running Scripts
You can run WLST scripts in the following ways:
-
Include the script in the
wlst.cmd
orwlst.sh
command:wlst.sh /oracle/middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py
-
Include the script in the
java weblogic.WLST
command. You can either include the full path to the script, as shown here:java weblogic.WLST c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py
or you can navigate to the directory where the script is located before invoking WLST, in which case you only need to include the script name in the command:
cd C:/Oracle/Middleware/wlserver/common/templates/scripts/wlst java weblogic.WLST distributeQueues.py
-
After invoking interactive WLST, use the
execfile()
command:wls:offline> execfile('c:/Oracle/Middleware/wlserver/common/templates/scripts/wlst/distributedQueues.py')
Note:
If you use backslashes (\) in the path name, be aware that WLST interprets them as a special character, which you must escape. See Syntax for WLST Commands.
Exiting WLST
To exit WLST, enter the exit()
command:
wls:/mydomain/serverConfig> exit()
Exiting WebLogic Scripting Tool ...
Syntax for WLST Commands
Follow this syntax when entering WLST commands or writing them in a script:
-
Command names and arguments are case sensitive.
-
Enclose arguments in single or double quotes. For example,
'newServer'
or"newServer"
. -
If you specify a backslash character (
\
) in a string, either precede the backslash with another backslash or precede the entire string with a lower-caser
character. The \ orr
prevents Jython from interpreting the backslash as a special character.For example when specifying a file path name that contains a backslash:
readTemplate('c:\\userdomains\\mytemplates\\mytemplate.jar', 'Expanded')
or
readTemplate(r'c:\userdomains\mytemplates\mytemplate.jar', 'Expanded')
Note:
When specifying path names in WLST commands on a Windows machine, you can use a forward slash (/). For example:
readTemplate('c:/userdomains/templates/template.jar', 'Expanded')
is as valid as
readTemplate('c:\\userdomains\\templates\\template.jar', 'Expanded')
-
When using WLST offline, the following characters are not valid in names of management objects: period (
.
), forward slash (/
), or backward slash (\
).If you need to
cd
to a management object whose name includes a forward slash (/
), surround the object name in parentheses. For example:cd('JMSQueue/(jms/REGISTRATION_MDB_QUEUE)')
Considerations When Invoking Multiple WLST Instances
At WLST startup, Jython stores information in a temporary directory based on the username of the person who started WLST. If the same user invokes two different WLST instances which will run at the same time, conflicts may occur when saving this information in the temporary directory.
If you plan to invoke multiple WLST instances with the same username, Oracle recommends that you define the java.io.tmpdir
system property to point to a temporary directory that will not be shared by other WLST instances that are running at the same time. For example, include the following parameter in the Java command you use to start WLST:
-Djava.io.tmpdir=C:\mytempdir
Redirecting Error and Debug Output to a File
You can redirect error and debug information to a file.
To redirect WLST information, error, and debug messages from standard output to a file, enter
redirect(outputFile,[toStdOut])
stopRedirect()
This command also redirects the output of the dumpStack()
and dumpVariables()
commands.
For example, to redirect WLST output to the logs/wlst.log
file under the directory from which you started WLST, enter the following command:
wls:/mydomain/serverConfig> redirect('./logs/wlst.log')
See redirect and stopRedirect in WLST Command Reference for WebLogic Server.
Getting Help for WLST
WLST provides command line help for each command.
To display information about WLST commands and variables, enter the help
command.
If you specify the help
command without arguments, WLST summarizes the command categories. To display information about a particular command, variable, or command category, specify its name as an argument to the help
command. To list a summary of all online or offline commands from the command line using the following commands, respectively:
help('online') help('offline')
The help
command supports a query. For example, help('get*')
displays the syntax and usage information for all commands that begin with get
.
For example, to display information about the disconnect
command, enter the following command:
wls:/mydomain/serverConfig> help('disconnect')
The command returns the following:
Description:
Disconnect from a WebLogic Server instance.
Syntax:
disconnect()
Example:
wls:/mydomain/serverConfig> disconnect()
Running WLST from Ant
WebLogic Server provides a custom Ant task, wlst
, which invokes a WLST script from an Ant build file. You can create a WLST script (.py
) file and then use this task to invoke the script file, or you can create a WLST script in a nested element within this task.
For more information about Ant, see the Apache Ant 1.7.1 Manual at http://ant.apache.org/manual/
.
The wlst
task is predefined in the version of Ant that is installed with WebLogic Server. To add this version of Ant to your build environment, run the following script, where WL_HOME
is the directory in which you installed WebLogic Server.
WL_HOME
\server\bin\setWLSEnv.cmd
(or setWLSEnv.sh
on UNIX)
On UNIX operating systems, the setWLSEnv.sh
command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
If you want to use the wlst
task with your own Ant installation, include the following task definition in your build file:
<taskdef name="wlst" classname="weblogic.ant.taskdefs.management.WLSTTask" />
WLST Task Parameters
Table 2-4 lists the wlst
task parameters that you specify as attributes of the <wlst>
element.
Table 2-4 wlst Parameters
Attribute | Description | Required |
---|---|---|
properties=" |
Name and location of a properties file that contains name-value pairs that you can reference in your WLST script. |
No |
fileName=" |
Name and location of the WLST script file that you would like to execute. If the specified WLST script file does not exist, this task fails. |
Yes, if no nested |
arguments=" |
List of arguments to pass to the script. These arguments are accessible using the |
No |
failOnError=" |
Boolean value specifying whether the Ant build will fail if this task fails. |
No; default is |
executeScriptBeforeFile=" |
Boolean value specifying whether this task invokes the script in the nested |
No; default is |
debug=" |
Boolean value specifying whether debug statements should be output when this task is executed. |
No; default is |
replaceProperties=" |
Boolean value that specifies whether ant property expansion will work in the specified WLST script. |
No; default is |
WLST Task Parameters Specified as Nested Elements
Table 2-5 describes the wlst
task parameters that you specify as nested elements of the <wlst>
element.
Table 2-5 Parameters Specified as Nested Elements
Attribute | Description | Required |
---|---|---|
script |
The script to be executed. |
Required, if you do not use the fileName attribute to name a script file. |
classpath |
The classes to add to the classpath. This element is the standard Ant |
No. Use if your script requires classes that are not already on the classpath. |
WLST Ant Task Examples
The following sections show examples for the createServer
, loop
, and error
targets.
CreateServer Target Example
In the following example, the createServer
target does the following:
-
Adds classes to the task's classpath.
-
Executes the script in the nested
script
element. This script connects to a WebLogic domain's Administration Server att3://localhost:7001
. (Note thatexecuteScriptBeforeFile
is set totrue
, so this is invoked before the specified WLST script file.) -
Executes the script file
myscript.py
that is specified by thefileName
attribute. The script file is located in the directory from which you started Ant. You could use such a file to start an edit session, create a new server, save, and activate the configuration changes. -
Defines three arguments that are passed to the script. These arguments are accessible using the
sys.argv
variable. -
Continues execution, as per the
failOnError="false"
setting, even if thewlst
Ant task fails to execute. -
Disables debugging.
<target name="configServer"> <wlst debug="false" failOnError="false" executeScriptBeforeFile="true" fileName="./myscript.py"> <classpath> <pathelement location="${my.classpath.dir}"/> </classpath> <script> connect('adminusername','adminpassword','t3://localhost:7001') </script> </wlst> </target>
Loop Target Example
In the following example, the loop
target does the following:
-
Adds classes to the task's classpath using a path reference.
-
Executes the WLST script file
myscript.py
in the directory from which you started Ant. (Note thatexecuteScriptBeforeFile
is set tofalse
, so the WLST script file is executed first, before the embedded script.) -
Executes the embedded script to connect to the server at
t3://localhost:7001
and access and print the list of servers in the WebLogic domain. -
Results in a build failure if the
wlst
task fails to execute, as per thefailOnError="true"
setting. -
Enables debugging.
<path id="my.classpath"> <pathelement location="${my.classpath.dir}"/> </path> <target name="loop"> <wlst debug="true" executeScriptBeforeFile="false" fileName="./myscript.py" failOnError="true"> <classpath> <pathelement location="${my.classpath.dir}"/> </classpath> <script replaceProperties="true"> print 'In the target loop' connect('${admin.user}','${admin.password}','t3://localhost:7001') svrs = cmo.getServers() print 'Servers in the domain are' for x in svrs: print x.getName() </script> </wlst> </target>
Error Target Example
In the following example, the error
target:
-
Executes the embedded script to print the variable,
thisWillCauseNameError
. -
Continues execution, as per the
failOnError="false"
setting, even if thethisWillCauseNameError
variable does not exist and thewlst
Ant task fails to execute. -
Enables debugging.
<target name="error"> <wlst debug="true" failOnError="false"> <script>print thisWillCauseNameError</script> </wlst> </target>
Importing WLST as a Jython Module
Advanced users can import WLST from WebLogic Server as a Jython module. After importing WLST, you can use it with your other Jython modules and invoke Jython commands directly using Jython syntax.
The main steps include converting WLST definitions and method declarations to a .py
file, importing the WLST file into your Jython modules, and referencing WLST from the imported file.
To import WLST as a Jython module:
Customizing WLST
You can customize WLST using the WLST home directory, which is located at WL_HOME
/common/wlst
, by default, where WL_HOME
refers to the top-level installation directory for WebLogic Server. All Python scripts that are defined within the WLST home directory are imported at WLST startup.
Note:
You can customize the default WLST home directory by passing the following argument on the command line:
-Dweblogic.wlstHome=<another-directory>
Table 2-6 describes ways to customize WLST.
Table 2-6 Customizing WLST
To define custom... | Do the following... | For a sample script, see... |
---|---|---|
WLST commands |
Create a Python script defining the new commands and copy that file to |
|
WLST commands within a library |
Create a Python script defining the new commands and copy that file to The scripts located within this directory are imported as Jython libraries. |
|
WLST commands as a Jython module |
Create a Python script defining the new commands and copy that file to This script can be imported into other Jython modules, as described in Importing WLST as a Jython Module. |
A JAR file, To import |
Integrated help for custom WLST commands |
Define the help text for each command group and command in a resource bundle. Use Use Typically, you will call the |
Not applicable. |
Adding Integrated Help for Custom Commands
You can customize WLST to include integrated help for any custom WLST commands you've defined. To add integrated help, you define the help text for each command group and command in a resource bundle, which can be either a class or a property resource file. You can define the help for multiple command groups in the same resource bundle.
Note:
The resource bundle must be present in the classpath.
The resource bundle contains the following entries for each command group:
<commandGroup>_ShortDescription=\ <short description of command group> <commandGroup>_Description=\ \n<description of command group>
For example, the following lines define the short description and description for the command group navigate
:
navigate_ShortDescription=\ Lists commands for navigating the hierarchy of beans. navigate_Description=\ \n Navigates the hierarchy of beans and controls the prompt display. \n
When you enter the help()
command to display a list of command groups, the short description for navigate
is displayed in the listing:
wls:/offline>help() WLST is a command line scripting tool to configure and administer a WebLogic Server. Try: help('all') List all WLST commands available. help('browser') List commands for browsing the hierarchy. help('navigate') List commands for navigating the bean hierarchy.
When you enter the help('navigate')
command, the description is displayed above the list of commands in the group:
wls:/offline> help('navigate') Navigates the hierarchy of beans and controls the prompt display. help('mycd') Navigate the hierarchy of beans. help('myprmpt') Toggle the display of path information at the prompt.
The resource bundle contains help text entries for commands using a standard pattern. For each command name, there are several entries:
<commandName>_ShortDescription <commandName>_Description <commandName>_Example <commandName>_Syntax
The following defines the help for mycd
command:
mycd_ShortDescription=\ Navigate the hierarchy of beans. mycd_Description=\ \nNavigate the hierarchy of configuration or runtime beans. This \ \ncommand uses a model that is similar to navigating a file system \ \nin a Windows or UNIX command shell. For example, to navigate back \ \nto a parent configuration or runtime bean, enter mycd(".."). The \ \ncharacter string .. (dot-dot) refers to the directory immediately \ \nabove the current directory. To get back to the root configuration \ \nbean after navigating to a configuration or runtime bean that is \ \ndeep in the hierarchy, enter mycd("/"). \ mycd_Example=\ wls:/mydomain/serverConfig> mycd('Servers')\n\ wls:/mydomain/serverConfig/Servers> mycd('myserver)\n\ wls:/mydomain/serverConfig/Servers/myserver>mycd('../..')\n\ wls:/mydomain/serverConfig> mycd_syntax=\ mycd(mbeanName) \n- mbeanName = Path to the configuration or runtime bean in the namespace.\ \n
The short description is shown to the right of the command name when you enter the help('
commandGroup
')
command to list all commands in a group:
wls:/offline> help('navigate') Navigates the hierarchy of beans and controls the prompt display. help('mycd') Navigate the hierarchy of beans. help('myprmpt') Toggle the display of path information at the prompt.
The description, example, and syntax are displayed when you enter the help('
commandName
')
command:
wls:/offline> help('mycd')
Description:
Navigate the hierarchy of configuration or runtime beans. This
command uses a model that is similar to navigating a file system
in a Windows or UNIX command shell. For example, to navigate back
to a parent configuration or runtime bean, enter mycd(".."). The
character string .. (dot-dot) refers to the directory immediately
above the current directory. To get back to the root configuration
bean after navigating to a configuration or runtime bean that is
deep in the hierarchy, enter mycd("/").
Syntax:
mycd(mbeanName)
- mbeanName = Path to the configuration or runtime bean in the namespace.
Example:
wls:/mydomain/serverConfig> mycd('Servers')\n\
wls:/mydomain/serverConfig/Servers> mycd('myserver)\n\
wls:/mydomain/serverConfig/Servers/myserver>mycd('../..')\n\
wls:/mydomain/serverConfig>
After defining the help text in the resource bundle, use addHelpCommandGroup
to add the command group name to the list of command groups output by the help()
command. Use addHelpCommand
to add each command in a group to the list of commands displayed by the help('
commandGroup
')
command. See addHelpCommandGroup and addHelpCommand in the WLST Command Reference for WebLogic
Server.
For more information on resource bundles and localization, refer to http://download.oracle.com/javase/6/docs/api/java/util/ResourceBundle.html
.
Sample Scripts For Defining new WLST Commands
The following sample script demonstrates how to define a new WLST command.
def wlstHomeSample(): print 'Sample wlst home command'
Within this script, the wlstHomeSample()
command is defined, which prints a text string:
wls:/offline>
wlstHomeSample()
Sample wlst home command
When defining new WLST commands in this way, store the .py
file in the WL_HOME/common/wlst directory.
The following sample script demonstrate usage of the WLST lib
directory, where layered products and ISVs can add commands to WLST in their namespace. The script has the same structure as the previous example. It differs only in that it is stored in the WL_HOME/common/wlst/lib directory instead of the WL_HOME/common/wlst directory.
def wlstExampleCmd(): print 'Example command'
Within this script, the wlstExampleCmd()
command is defined, which prints a text string:
wls:/offline> wlstLibSample.wlstExampleCmd()
Example command
Note that you must create the WLST lib
directory if it does not already exist.