The WebLogic Scripting Tool (WLST) is a command-line scripting environment that you can use to create, manage, and monitor WebLogic domains. It is based on the Java scripting interpreter, Jython. In addition to supporting standard Jython features such as local variables, conditional variables, and flow control statements, WLST provides a set of scripting functions (commands) that are specific to WebLogic Server. You can extend the WebLogic scripting language to suit your needs by following the Jython language syntax. See http://www.jython.org.
The following sections describe the WebLogic Scripting Tool:
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). For information about the WebLogic Server Administration Console, see Oracle WebLogic Server Administration Console Help. For information about the Configuration Wizard, see Creating Domains Using the Configuration Wizard.
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 With JMX for Oracle WebLogic Server.
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) for more information.
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 can cd to the management object and change the attribute value. See "create" in WebLogic Scripting Tool Command Reference.
You can use any of the following techniques to invoke WLST commands:
Interactively, on the command line; see Interactive Mode
In batches, supplied in a file; see Script Mode
Embedded in Java code; see Embedded 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. For more information, see "startRecording" and "stopRecording" in WebLogic Scripting Tool Command Reference.
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.
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.
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('weblogic','welcome1')");
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();
}
}
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:
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 Configuring Server Environments for Oracle WebLogic Server.
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.
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 Oracle WebLogic Server MBean Reference.)
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('weblogic', 'welcome1', 'localhost:7001')
For more information, see "connect" in WebLogic Scripting Tool Command Reference.
Enter the credentials on the command line, 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('weblogic', 'welcome1', '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')
For more information, see "connect" and "storeUserConfig" in WebLogic Scripting Tool Command Reference.
Invoke the connect command from a directory that contains the domain's boot.properties file. By default, when you create an Administration Server, WebLogic Server encrypts the credentials and stores them in a boot.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()
For more information, see "connect" in WebLogic Scripting Tool Command Reference.
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', 'mypassword')
WLST encrypts the string and writes the encrypted value to the domain's configuration file.
For more information, see "set" in WebLogic Scripting Tool Command Reference.
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 the get 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)
For more information, see "ls" and "get" in WebLogic Scripting Tool Command Reference.
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', 'mypassword')
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 WebLogic Scripting Tool Command Reference). For example:
set('DefaultIIOPPasswordEncrypted', encrypt('mypassword'))
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)
To read the unencrypted value of the attribute, pass the name of the unencrypted attribute to the get command. For example:
get('DefaultIIOPPassword')
returns
mypassword
The user names and passwords of WebLogic Server users, security groups, and security roles are not stored in a WebLogic domain's XML configuration documents. 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. For more information, see Managing Security Data (WLST Online).
The following sections summarize the steps for setting up and using WLST:
You can invoke WLST in the following ways:
Execute the appropriate shell script for your environment.
Execute the java weblogic.WLST command.
Run a WLST script.
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 theCONFIG_JVM_ARGS environment variable to the following value to resolve this issue:
-Djava.security.egd=file:/dev/./urandom
See also Running WLST from Ant.
To invoke WLST using a shell script, execute the commands that are appropriate for your environment. Environment variables are automatically set when you invoke WLST this way.
Note:
The following commands apply only to standalone WebLogic Server installations (those that do not include other Fusion Middlware 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 the Oracle Fusion Middleware Administrator's Guide.
cd WL_HOME/common/bin
./wlst.sh
WL_HOME is the path to your WebLogic Server home directory.
cd WL_HOME\common\bin
wlst.cmd
WL_HOME is the path to your WebLogic Server home directory.
To invoke WLST using the java command, you must first set up your environment for WLST. To set up your environment for WLST:
Install and configure the WebLogic Server software, as described in the Oracle WebLogic Server Installation Guide.
Add WebLogic Server classes to the CLASSPATH environment variable and WL_HOME\server\bin to the PATH environment variable, where WL_HOME refers to the top-level installation directory for WebLogic Server.
You can use the setWLSEnv script to set the required 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.
After setting up your environment, use the following syntax to invoke WLST. See Table 2-1 for a description of the WLST command options. See Table 2-2 for a description of the SSL arguments.
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 ]
Table 2-1 Command Options for WLST
| Option | Description |
|---|---|
-loadProperties propertyFilename
|
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 |
-skipWLSModuleScanning |
Use this option to reduce startup time by skipping package scanning and caching for WebLogic Server modules. |
[-i] filePath.py
|
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:
|
| Argument | Definition |
|---|---|
-Dweblogic.security.SSL. ignoreHostnameVerification=true -Dweblogic.security.TrustKeyStore= DemoTrust |
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 ( |
-Dweblogic.security.JavaStandardTrustKeyStorePassPhrase=password
|
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. |
-Dweblogic.security.CustomTrustKeyStoreFileName=filename
-Dweblogic.security.TrustKeystoreType=jks
|
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 |
-Dweblogic.security.CustomTrustKeyStorePassPhrase=password
|
Password that was used to secure the custom keystore. You must use this argument only if the custom keystore is protected by a password. |
-Dweblogic.security.SSL.hostnameVerifier=classname
|
Name of a custom Host Name Verifier class. The class must implement the |
To use WLST in script mode:
java weblogic.WLST c:/Oracle/Middleware/wlserver/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/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('weblogic','welcome1','localhost:7001')
You can run WLST scripts in the following ways:
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/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_10.3/templates/scripts/wlst java weblogic.WLST distributeQueues.py
After invoking WLST, use the execfile() command:
wls:offline> execfile('c:/Oracle/Middleware/wlserver/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. For more information, see Syntax for WLST Commands.To exit WLST, enter the exit() command:
wls:/mydomain/serverConfig> exit()
Exiting WebLogic Scripting Tool ...
c:\>
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-case r character. The \ or r 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')
or
readTemplate(r'c:\userdomains\mytemplates\mytemplate.jar')
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')
is as valid as
readTemplate('c:\\userdomains\\templates\\template.jar')
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)')
To redirect WLST information, error, and debug messages from standard out 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')
For more information, see "redirect" and "stopRedirect" in WebLogic Scripting Tool Command Reference.
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 will support 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()
WebLogic Server provides a custom Ant task, wlst, that 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:
WL_HOME\server\bin\setWLSEnv.cmd (or setWLSEnv.sh on UNIX)
where WL_HOME is the directory in which you installed WebLogic Server.
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" />
Table 2-3 lists the wlst task parameters that you specify as attributes of the <wlst> element.
| 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 |
The following sections describe the wlst task parameters that you specify as nested elements of the <wlst> element.
Contains a WLST script. This element is required if you do not use the fileName attribute to name a script file.
Specifies classes to add to the classpath. Use this element if your script requires classes that are not already on the classpath.
This element is the standard Ant classpath element. You can specify a reference to a path element that you have defined elsewhere in the build file or nest elements that specify the files and directories to add to the class path. See "Path-like Structures" in Apache Ant 1.7.1 Manual at http://ant.apache.org/manual/using.html#path.
The following sections show examples for the createServer, loop, and error targets.
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 at t3://localhost:7001. (Note that executeScriptBeforeFile is set to true, so this is invoked before the specified WLST script file.)
Executes the script file myscript.py that is specified by the fileName 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 the wlst 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('weblogic','welcome1','t3://localhost:7001')
</script>
</wlst>
</target>
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 that executeScriptBeforeFile is set to false, 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 the failOnError="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>
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 the thisWillCauseNameError variable does not exist and the wlst Ant task fails to execute.
Enables debugging.
<target name="error">
<wlst debug="true" failOnError="false">
<script>print thisWillCauseNameError</script>
</wlst>
</target>
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:
Invoke WLST.
c:\>java weblogic.WLST
wls:/(offline)>
Use the writeIniFile command to convert WLST definitions and method declarations to a .py file.
wls:/(offline)> writeIniFile("wl.py")
The Ini file is successfully written to wl.py
wls:/(offline)>
Open a new command shell and invoke Jython directly by entering the following command:
c:\>java org.python.util.jython
The Jython package manager processes the JAR files in your classpath. The Jython prompt appears:
>>>
Import the WLST module into your Jython module using the Jython import command.
>>>import wl
Now you can use WLST methods in the module. For example, to connect WLST to a server instance:
wl.connect('username','password')
....
Notes:
When using WLST as a Jython module, in all WLST commands that have a block argument, block is always set to true, specifying that WLST will block user interaction until the command completes. See "WLST Command and Variable Reference" in WebLogic Scripting Tool Command Reference.When running recorded scripts directly in a Jython interpreter, boolean values of true and false can cause an error. Before running recorded scripts in a Jython interpreter, make one of the following changes to the script:
Add the following two lines to the script to define the true and false values:
true=1 false=0
Change true and false values to wl.true or wl.false, where wl is the name from the import.
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>
The following table describes ways to customize 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, |
|
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 See Adding Integrated Help for Custom Commands for more information. |
Not applicable. |
You can customize WLST to include integrated help for any custom WSLT 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:/mydomaina/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 WebLogic Scripting Tool Command Reference.
For more information on resource bundles and localization, refer to http://java.sun.com/javase/6/docs/api/java/util/ResourceBundle.html.
This 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 String, as follows:
wls:/(offline)> wlstHomeSample()
Sample wlst home command
This 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 example in the previous section. 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 String, as follows:
wls:/(offline)>wlstLibSample.wlstExampleCmd() Example command