Using the WebLogic Server Scripting Tool for Offline Configuration

Using the WebLogic Server Scripting Tool for Offline Configuration

This document describes how to use the BEA Products™ Scripting Tool (WLST) for offline configuration. Topics include:

Introducing WLST

WLST is a command-line scripting interface that you use to configure WebLogic Server and WebLogic domains. Using WLST, WebLogic Server administrators and operators can perform administrative tasks and initiate WebLogic Server configuration changes interactively or by using an executable script.

WLST supports both online and offline configuration:

Refer to the following resources for additional information:

Getting Started Using WLST Offline Configuration

The following sections describe how to get started using WLST offline configuration. The following topics are described:

Setting up Your Environment—WebLogic Platform 8.1 SP5 and Later

For WebLogic Platform 8.1 SP5 (or a later release of 8.1), to set up your environment for WLST offline configuration, perform the following steps:

Setting up Your Environment—WebLogic Platform 8.1 SP4, SP3, or SP2

For WebLogic Platform 8.1 SP4, SP3, or SP2, to set up your environment for WLST offline configuration, perform the following steps:

Invoking WLST

You can invoke WLST in interactive or script mode:

The methods for invoking WLST in each mode are described in the following sections. A summary of the sample scripts available is also provided in Summary of Sample Scripts.

Invoking WLST in Interactive Mode

To invoke WLST offline configuration in interactive mode, at a command prompt enter one of the following commands:

Windows: WL_HOME\common\bin\runWLSToffline.cmd
Unix: WL_HOME/common/bin/runWLSToffline.sh

WLST starts in interactive mode, and a welcome message and the WLST offline configuration prompt appears:

Welcome to Weblogic Scripting Shell
wls_offline:/>

You can begin entering commands, setting variables, or running a script to create a new or update an existing domain.

To run a WLST script in interactive mode, enter the execfile command, as follows:

execfile(WLST_script)

WLST_script specifies the full pathname to the WLST script file. For a summary of the sample script files available, see Summary of Sample Scripts.

For more information about the WLST commands and variables, see WLST Offline Configuration Commands and WLST Offline Configuration Variables, respectively.

Invoking WLST in Script Mode

To invoke WLST offline configuration in script mode, at a command prompt enter one of the following commands:

Windows: WL_HOME\common\bin\runWLSToffline.cmd WLST_script
Unix: WL_HOME/common/bin/runWLSToffline.sh WLST_script

The WLST_script argument specifies the full pathname to a WLST script file. For a summary of the sample script files available, see Summary of Sample Scripts.

WLST starts in script mode, executing the specified script without requiring your input.

Summary of Sample Scripts

Table 1 summarizes the WLST offline configuration sample scripts that you can run or use as templates for creating additional scripts.

WLST Offline Configuration Variables

Table 2 describes WLST offline configuration variables and their common usage. All variables are initialized to default values at the start of a user session and are changed according to the user interaction with WLST.

WLST Offline Configuration Commands

WLST offline configuration commands (primitives) are executable functions that are extensions to the Jython language and that follow the Jython syntax.

The following sections describe WLST offline configuration commands and how to use them. These commands are available when using WLST for offline configuration in interactive and script mode.

WLST offline configuration commands are divided into the following four categories:

The commands in each category are described in the following sections. Befor proceeding, it is recommended that you review Guidelines for Entering WLST Commands.

Guidelines for Entering WLST Commands

Please review the following guidelines for entering WLST commands:

Control Commands

Similar to the Configuration Wizard, the control commands for WLST offline configuration enable you to perform the following tasks:

Table 3 lists the control commands for WLST offline configuration used to create a new or update an existing domain, or to exit WLST.

Each command is described in detail in the following sections. Commands are described alphabetically.

addTemplate

Extends the current domain using the specified application or service extension template.

Syntax

addTemplate(templateFileName)

Examples

The following command extends the current domain using the specified extension template:

wls_offline:/> readDomain(`c:/bea/user_projects/domains/wlw')
wls_offline:/wlw> addTemplate('c:/bea/weblogic81/common/templates/
applications/wlp.jar')

closeDomain

Closes the current domain. The domain is no longer available for editing once it is closed.

Syntax

closeDomain()

Examples

The following command closes the current domain:

wls_offline:/> readDomain(`c:/bea/user_projects/domains/medrec')
...
wls_offline:/medrec> updateDomain()
wls_offline:/medrec> closeDomain()

closeTemplate

Closes the current domain template. The domain template is no longer available once it is closed.

Syntax

closeTemplate()

Examples

The following command closes the current domain template:

wls_offline:/> readTemplate(`c:/bea/weblogic81/common/templates/domains/
medrec.jar')
...
wls_offline:/medrec> writeDomain(`c:/bea/user_projects/domains/medrec')
wls_offline:/medrec> closeTemplate()

exit

Disconnects WLST from the user session and closes the scripting shell.

Syntax

exit()

Example

The following example instructs WLST to disconnect from the user session and close the scripting shell:

wls_offline:/> exit()
Exiting WLS scripting shell ...
c:\>

readDomain

Opens an existing domain for updating.

Syntax

readDomain(domainDirName)

Example

The following command opens the specified domain for editing:

wls_offline:/> readDomain(`c:/bea/user_projects/domains/medrec')
wls_offline:/medrec>

readTemplate

Opens an existing domain template for domain creation.

Syntax

readTemplate(templateFileName)

Examples

The following command opens the specified domain template for domain creation:

wls_offline:/> readTemplate(`c:/bea/weblogic81/common/templates/domains
/medrec.jar')
wls_offline:/medrec>

updateDomain

Updates and saves the current domain. The domain continues to be editable after you update and save it.

Syntax

updateDomain()

Examples

The following command updates and saves the current domain:

wls_offline:/> readDomain(`c:/bea/user_projects/domains/medrec')
...
wls_offline:/medrec> updateDomain()

writeDomain

Writes the domain configuration information to the specified directory. The domain continues to be editable after you execute this command.

Syntax

writeDomain(domainDir)

Examples

The following command writes the domain configuration information to the specified directory:

wls_offline:/> readTemplate(`c:/bea/weblogic81/common/templates/domains
/medrec.jar')
...
wls_offline:/medrec> writeDomain(`c:/bea/user_projects/domains/medrec')

Browse Command (cd)

The cd command navigates the hierarchy of configuration objects. This command uses a model that is similar to navigating a file system in a Windows or UNIX command shell. You can navigate to configuration objects in the current hierarchy and to any child or instance.

To navigate back to a parent resource, enter the cd('..') command. To get back to the root configuration object after navigating to a resource that is deep in the hierarchy, enter the cd('/') command.

The cd command returns a stub of the configuration object instance, if one exists.

Syntax

cd(path)

Example

The following example shows how to navigate the hierarchy of configuration objects:

wls_offline:/medrec> cd('Server')
wls_offline:/medrec/Server> cd('MedRecServer')
wls_offline:/medrec/Server/MedRecServer> cd('../..')
wls_offline:/medrec>

Edit Commands

Table 4 lists the WLST offline configuration Edit commands that you use to interrogate and edit configuration objects.

assign

Assigns configuration objects to one or more destinations.

Syntax

assign(sourceType, sourceName, destinationType, destinationName)

Use the following guidelines for setting the sourceType and destinationType:

Example

The following example performs the following assignments:

assignAll

Assigns all applications or services to one or more destinations.

Syntax

assignAll(sourceType, destinationType, destinationName)

Example

The following example assigns all services to the servers adminServer and cluster1.

wls_offline:/mydomain> assignAll("Services", "Target", "adminServer,cluster1")

The following services, if present, are assigned to the specified targets: MigratableRMIService, Shutdownclass, Startupclass, FileT3, RMCFactory, MailSession, MessagingBridge, JMSConnectionFactory, JDBCConnectionPool, JDBCMultipool, JDBCTxDatasource, JDBCDataSource, JDBCPoolComp, JoltConnectionPool, WLECConnectionPool, and WTCServer.

create

Creates a child object with the specified name and type for the current configuration object. The create command returns a stub for the newly created configuration object.

Syntax

create(Name,childObjectType)

Example

The following example creates a child object of type Server named newServer for the current configuration object, storing the stub as server1:

wls_offline:/medrec> server1=create('newServer','Server')
wls_offline:/medrec> server1.getName()
`newServer'

delete

Deletes an instance of a child object with the specified name and type for the current configuration object.

Syntax

delete(Name,childObjectType)

Example

The following example deletes the child object of type Server named newServer for the current configuration object:

wls_offline:/medrec> delete('newServer','Server')

get

Returns the value of the specified attribute for the current configuration object.

Alternatively, you use the cmo variable to perform any get method on the current configuration object. For example:

cmo.getListenPort()

For more information about the cmo variable, see WLST Offline Configuration Variables.

Syntax

get(attributeName)

Example

The following example returns the value of the AdministrationPort for the current configuration object:

wls_offline:/medrec> get('AdministrationPort')
9002

loadDB

Loads SQL files into a database.

Before executing this command, ensure that the following conditions are true:

The command fails if the above conditions are not met.

Syntax

loadDB(DBVersion, connectionPoolName)

Example

The following example loads SQL files, intended for version 4.4 of the database, using the myPool-PointBase JDBC connection pool:

wls_offline:/mydomain> loadDB(`4.4', `myPool-PointBase')

set

Sets the specified attribute value for the current configuration object.

When you use offline WLST to set password attributes, you need to use the encrypted attribute. For example, to update CustomIdentityKeyStorePassPhrase, you have to use the CustomIdentityKeyStorePassPhraseEncrypted attribute. In this example, if you do not use the encrypted attribute, the "Unable to find attribute CustomIdentityKeyStorePassPhrase" message appears.

Alternatively, you use the cmo variable to perform any set method on the current configuration object. For example:

cmo.setPassword(`weblogic')

For more information about the cmo variable, see WLST Offline Configuration Variables.

Syntax

set(attributeName,attributeValue)

Example

The following example sets the ArchiveConfigurationCount attribute of DomainMBean to 10:

wls_offline:/mydomain/config> set('ArchiveConfigurationCount',10)
wls_offline:/mydomain/config>

setOption

Sets options related to a domain creation or update.

Syntax

setOption(optionName,optionValue)

Example

The following example sets the CreateStartMenu option to false:

wls_offline:/> setOption('CreateStartMenu', 'false')

unassign

Unassign configuration objects from one or more destinations.

Syntax

unassign(sourceType, sourceName, destinationType, destinationName)

Use the following guidelines for setting the sourceType and destinationType:

Example

The following example unassigns the following resources:

unassignAll

Unassigns all applications or services from one or more destinations.

Syntax

unassignAll(sourceType, destinationType, destinationName)

Example

The following example unassigns all services from the servers adminServer and cluster1.

wls_offline:/medrec> unassignAll("Services", "Target", "adminServer,cluster1")

The following services, if present, are unassigned from the specified targets: MigratableRMIService, Shutdownclass, Startupclass, FileT3, RMCFactory, MailSession, MessagingBridge, JMSConnectionFactory, JDBCConnectionPool, JDBCMultipool, JDBCTxDatasource, JDBCDataSource, JDBCPoolComp, JoltConnectionPool, WLECConnectionPool, and WTCServer.

Information Commands

Table 5 lists the information commands for WLST offline configuration that are useful for interrogating domains, servers, and variables, and providing configuration object and WLST-related information.

Each command is described in detail in the following sections.

dumpStack

Displays any stack trace that was produced while performing a WLST action.

Syntax

dumpStack()

Example

This example instructs WLST to display the stack trace.

wls_offline:/medrec> dumpStack()
com.bea.plateng.domain.script.jython.WLSTException: java.lang.reflect.Invocation TargetException
...

dumpVariables

Displays all the variables used by WLST, including their name and value.

Syntax

dumpVariables()

Example

This example instructs WLST to display all the current variables and their values.

wls_offline:/platform>dumpVariables()
cmo: Proxy for medrec: Name=medrec, Type=DomainConfig
exitonerror: true
isrecording: false

help

Provides syntax and usage information for all categories of WLST commands, when no arguments are specified, or for a single command or variable, when a command or variable name argument is specified.

The help command will support a query; for example, help('get*') displays the syntax and usage information for all commands that begin with get.

Syntax

help([`name'])

Example

In the following example, information about using the get command is requested:

wls:/medrec> help('get')

The command returns the following:

Description: 
Get any attribute for the currently navigated configuration object.
Syntax:
get(AttributeName)
AttributeName = current configuration object's attribute name.
Example: 
wls_offline:/medrec/Server/MedRecServer>get('AcceptBacklog')
50
wls_offline:/medrec/Server/MedRecServer>

ls

Lists all the child objects or attributes for current configuration object.

You can optionally control the output by specifying an optional argument.

Table 6 describes the ls command output information.

Syntax

ls(['a' | 'c'])

Example

The following command displays the child objects for the current configuration object:

wls_offline:/medrec> ls()
drw-   Application
drw-   Cluster
drw-   FileRealm
drw-   JDBCConnectionPool
drw-   JDBCTxDataSource
drw-   JMSConnectionFactory
drw-   MailSession
drw-   PasswordPolicy
drw-   Realm
drw-   Security
drw-   Server

The following command displays all the attribute names and values for the current configuration object:

wls_offline:/medrec> ls('a')
-rw-   AdministrationPort                            9002
-rw-   AdministrationPortEnabled                     false
-rw-   AutoConfigurationSaveEnabled                  false
-rw-   ConfigurationVersion                          8.1.2.0
-rw-   ConsoleContextPath                            console
-rw-   ConsoleEnabled                                true
-rw-   LastModificationTime                          0
-rw-   Name                                          medrec
-rw-   Notes                                         null
-rw-   ProductionModeEnabled                         false
wls_offline:/medrec>

prompt

Toggles the display of the configuration object navigation path information at the prompt, when entered without an argument.

This command is useful when the prompt becomes too long due to the length of the configuration object navigation path. For WLST offline configuration, when you disable the prompt details, the prompt displays as follows: wls_offline:/>. In this case, to determine your current location in the hierarchy, you can use the pwd command, as described in pwd. By default, the WLST prompt displays the configuration object navigation path information.

Syntax

prompt([`off'|'on'])

Example

The following example instructs WLST to hide and redisplay the configuration object navigation path information at the prompt:

wls_offline:/medrec/Server/MedRecServer> prompt()
wls_offline:/>
wls_offline:/> prompt()
wls_offline:/medrec/Server/MedRecServer

The following example instructs WLST to hide the prompt and default to the Jython prompt, change the Jython prompt, and redisplay the WLST prompt:

wls_offline:/medrec/Server/MedRecServer> prompt('off')
>>>
>>>sys.ps1="myprompt>"
myprompt>
myprompt> prompt('on')
wls:/medrec/Server/MedRecServerfs>

pwd

Displays the current location in the hierarchy of the configuration tree.

Syntax

pwd()

Example

The following command displays the current location in the hierarchy of the configuration object:

wls_offline:/medrec> pwd()
/medrec

startRecording

Records all user interactions with WLST; useful for capturing commands.

Syntax

startRecording(recordFilePath)

Example

The following example instructs WLST to begin recording WLST commands in the record.py file:

wls_offline:/> startRecording(`c:/myScripts/record.py')
Starting recording to c:\myScripts\record.py

stopRecording

Stops recording WLST commands.

Syntax

stopRecording()

Example

The following example instructs WLST to stop recording WLST commands:

wls_offline:/> stopRecording()
Stopping recording to c:\myScripts\record.py