3 Creating WebLogic Domains Using WLST Offline

You can create and configure WebLogic domains using WebLogic Scripting Tool (WLST) offline. WLST enables you to create a new WebLogic domain or update an existing WebLogic domain without connecting to a running WebLogic Server (that is, using WLST offline)—supporting the same functionality as the Configuration Wizard.

For information about sample scripts that you can use to create WebLogic domains, see WLST Offline Sample Scripts.

For more information about the Configuration Wizard, see Overview of the Configuration Wizard in Creating WebLogic Domains Using the Configuration Wizard.

Creating and Using a Domain Template (Offline)

A domain template is a JAR file that contains domain configuration documents, applications, security data, startup scripts, and other information needed to create a WebLogic domain.

Note:

If you notice that it takes a long time to create or update a domain using WLST, set the CONFIG_JVM_ARGS environment variable to the following value to resolve this issue:

-Djava.security.egd=file:/dev/urandom

To create and use a domain template, perform the steps described in Table 3-1.

Table 3-1 Steps for Creating a Domain Template (Offline)

To...	Use this command...	See...
Open an existing WebLogic domain or select the templates for the domain	readDomain(domainDirName) selectTemplate(templateName, TemplateVersion) loadTemplates()	readDomain, selectTemplate and loadTemplates in WLST Command Reference for WebLogic Server
(Optional) Modify the WebLogic domain	Browsing and editing commands	Browsing Information About the Configuration Hierarchy (Offline) Editing a WebLogic Domain (Offline)
Set the password for the default user, if it is not already set. The default username and password must be set before you can write the domain template.	cd('/Security/domainname/User/username') cmo.setPassword('password')	WLST Offline Sample Scripts
Write the domain configuration information to a domain template.	writeTemplate(templateName)	writeTemplate in WLST Command Reference for WebLogic Server
Use the template to create a domain.	createDomain(domainTemplate, domainDir, user, password) Note: The Configuration Wizard can also use the domain template. See Introduction to WebLogic Domains in Creating WebLogic Domains Using the Configuration Wizard.	createDomain in WLST Command Reference for WebLogic Server

Example 3-1 shows the basic commands needed to create a domain template from an existing domain:

Example 3-1 Creating a Domain Template From an Existing Domain

# Read the domain from the domain home located at /domains/mydomain
readDomain('/domains/mydomain')

# Create the template jar mydomain.jar in /templates
writeTemplate('/templates/mydomain.jar')

Creating and Updating a WebLogic Domain

When creating or updating a WebLogic domain, there are three phases to the configuration session:

• Load and merge the configuration using readTemplate (for creating) or readDomain (for updating) optionally followed by one or more addTemplate() calls.

• Modify the configuration by navigating the configuration tree and updating attributes.

• Save the configuration using writeDomain (for creating), updateDomain (for updating), or writeTemplate (for creating a template), followed by closeTemplate or closeDomain as appropriate.

The following examples demonstrate the sequence of commands for creating a domain from a single template and creating a domain from multiple templates. More extensive sample WLST offline scripts are available in the following directory:

ORACLE_HOME/wlserver/common/templates/scripts/wlst

Example 3-2 shows the basic sequence of commands needed to create a domain from a single template. This example creates a basic WebLogic Server domain from the wls.jar template.

Example 3-2 Creating a Domain From a Single Template

# Read the template to use for creating the domain
readTemplate('oracle_home/middleware/wlserver/common/templates/wls/wls.jar')

# Set the listen address and listen port for the Administration Server
cd('Servers/AdminServer')
set('ListenAddress','')
set('ListenPort', 7001)
 
# Enable SSL on the Administration Server and set the SSL listen address and
# port
create('AdminServer','SSL')
cd('SSL/AdminServer')
set('Enabled', 'True')
set('ListenPort', 7002)

# Set the domain password for the WebLogic Server administration user
cd('/')
cd('Security/base_domain/User/adminusername')
cmo.setPassword('adminpassword')

# If the domain already exists, overwrite the domain
setOption('OverwriteDomain', 'true')

# write the domain and close the template
writeDomain('/domains/mydomain')
closeTemplate()

exit()

Example 3-3 shows how to create a new domain using a domain template and one or more extension templates. This example creates the basic WebLogic Server domain from the wls.jar template and then extends the domain by adding the WebLogic Web Services Extension template to the domain.

Example 3-3 Creating a Domain From Multiple Templates

# Select the WebLogic domain template, and 
# then load it
selectTemplate('Basic WebLogic Server Domain')
selectTemplate('WebLogic Advanced Web Services for JAX-RPC Extension')
loadTemplates()
# Set the listen address and listen port for the Administration Server
cd('Servers/AdminServer')
set('ListenAddress','')
set('ListenPort', 7001)
 
# Enable SSL on the Administration Server and set the SSL listen address and
# port
create('AdminServer','SSL')
cd('SSL/AdminServer')
set('Enabled', 'True')

set('ListenPort', 7002)

# Set the domain password for the WebLogic Server administration user
cd('/')
cd('Security/base_domain/User/adminusername')
cmo.setPassword('adminpassword')

# If the domain already exists, overwrite the domain
setOption('OverwriteDomain', 'true')

# write the domain and close the templates
writeDomain('/domains/mydomain')

# Select the WebServices for JAX-RPC template, and 
# then load it

selectTemplate('WebLogic Advanced Web Services for JAX-RPC Extension')
loadTemplates()
closeTemplate()

exit()

Browsing Information About the Configuration Hierarchy (Offline)

WLST offline provides read and write access to the configuration data that is persisted in the WebLogic domain's config directory or in a domain template JAR created using Template Builder. This data is a collection of XML documents and expresses a hierarchy of management objects

. The schemas that define a WebLogic domain's configuration document are in the following locations:

• http://xmlns.oracle.com/weblogic/domain/1.0/domain.xsd

• http://xmlns.oracle.com/weblogic/security/1.0/security.xsd

• http://xmlns.oracle.com/weblogic/weblogic-diagnostics/1.0/weblogic-diagnostics.xsd

• In JAR files under WL_HOME/server/lib/schema, where WL_HOME is the directory in which you install WebLogic Server. Within this directory:

  • The domain.xsd document is represented in the weblogic-domain-binding.jar under the pathname META-INF/schemas/schema-0.xsd.

  • The security.xsd document is represented in the weblogic-domain-binding.jar under the pathname META-INF/schemas/schema-1.xsd.

  • The weblogic-diagnostics.xsd document is represented in the diagnostics-binding.jar under the pathname META-INF/schemas/schema-0.xsd.

WLST represents this hierarchy as a file system. The root of the file system is the management object that represents the WebLogic domain. Below the domain directory is a collection of directories for managed-object types; each instance of the type is a subdirectory under the type directory; and each management attribute and operation is a file within a directory. The name of an instance directory matches the value of the management object's Name attribute. If the management object does not have a Name attribute, WLST generates a directory name using the following pattern: NO_NAME_number, where number starts at 0 (zero) and increments by 1 for each additional instance.

Note:

As a performance optimization, WebLogic Server does not store most of its default values in the domain's configuration files. In some cases, this optimization prevents entire 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 WLST Command Reference for WebLogic Server.

To navigate the hierarchy, you use such WLST commands as cd, ls, and pwd in a similar way that you would navigate a file system in a UNIX or Windows command shell (see Table 3-2).

Table 3-2 Displaying WebLogic Domain Configuration Information (Offline)

To...	Use this command...	See this section in WLST Command Reference for WebLogic Server
Navigate the hierarchy of management objects	cd(path)	cd
List child attributes or management objects for the current management object	ls(['a' | 'c'])	ls
Toggle the display of the management object navigation path information at the prompt	prompt(['off'|'on'])	prompt
Display the current location in the configuration hierarchy	pwd()	pwd
Display all variables used by WLST	dumpVariables()	dumpVariables
Display the stack trace from the last exception that occurred while performing a WLST action	dumpStack()	dumpStack

Editing a WebLogic Domain (Offline)

You can edit a WebLogic domain offline.

To edit a WebLogic domain using WLST offline, you can perform any of the tasks defined in Table 3-3.

Table 3-3 Editing a WebLogic Domain

To...	Use this command...	See this section in WLST Command Reference for WebLogic Server
Add an application to a WebLogic domain	selectTemplate(templateName) loadTemplate(templateName)	selectTemplate and loadTemplates
Assign resources to one or more destinations (such as assigning servers to clusters)	assign(sourceType, sourceName, destinationType, destinationName)	assign
Unassign resources	unassign(sourceType, sourceName, destinationType, destinationName)	unassign
Create and delete management objects	create(name, childMBeanType) delete(name, childMBeanType)	create delete
Get and set attribute values	get(attrName) set(attrName, value)	get set
Set configuration options	setOption(optionName, value)	setOption
Load SQL files into a database	loadDB(dbVersion, connectionPoolName)	loadDB

Note:

If you notice that it takes a long time to create or update a domain using WLST, set the CONFIG_JVM_ARGS environment variable to the following value to resolve this issue:

-Djava.security.egd=file:/dev/urandom

Alternative: Using the configToScript Command

WLST includes a command, configToScript, that reads an existing WebLogic domain and outputs a WLST script that can recreate the WebLogic domain. See configToScript in WLST Command Reference for WebLogic Server.

Note:

If you use configToScript for a domain that contains other Fusion Middleware components in addition to WebLogic Server, be aware that configToScript does not include the configuration for those components in the resulting WLST script. Only the WebLogic Server configuration is included in the script.

configToScript will be deprecated in a future release. Oracle recommends that you use pack and unpack to recreate the domain on remote servers. See Overview of the Pack and Unpack Commands in Creating Templates and Domains Using the Pack and Unpack Commands.

Unlike creating and using a domain template, the configToScript command creates multiple files that must be used together. (A domain template is a single JAR file.) In addition, the script that the configToScript command creates:

• Can only be run by WLST.

  A domain template can be used by WLST or the Configuration Wizard.

• Requires a WebLogic Server instance to be running. If a server isn't running, the script starts one.

  WLST offline or the Configuration Wizard can use domain templates to create WebLogic domains without starting a server instance.

• Contains only references to applications and other resources. When you run the generated script, the applications and resources must be accessible to the WebLogic domain through the file system.

  A domain template is a JAR file that contains all applications and resources needed to create a WebLogic domain. Because the domain template is self-contained, you can use it to create WebLogic domains on separate systems that do not share file systems.

Considerations for Clusters, JDBC, and JMS Resources

When using WLST offline to create or extend a clustered WebLogic domain with a template that has applications containing application-scoped JDBC and/or JMS resources, you may need to perform additional steps (after the domain is created or extended) to make sure that the application and its application-scoped resources are targeted and deployed properly in a clustered environment. For more information on the targeting and deployment of application-scoped modules, see Deploying Applications and Modules with weblogic.deployer in Deploying Applications to Oracle WebLogic Server.

If you want to use JDBC resources to connect to a database, modify the environment as the database vendor requires. Usually this entails adding driver classes to the CLASSPATH variable and vendor-specific directories to the PATH variable. To set the environment that the sample Derby database requires as well as add an SDK to the PATH variable and the WebLogic Server classes to the CLASSPATH variable, invoke the following script:

(Windows) ORACLE_HOME\user_projects\domains\wl_server\setExamplesEnv.cmd 
(UNIX) ORACLE_HOME/user_projects/domains/wl_server/setExamplesEnv.sh 

Creating a Managed Server Domain on a Remote Machine

If your WebLogic domain contains multiple Managed Servers, and each Managed Server domain directory is located on a remote machine on which the Administration Server does not reside, you can use the WLST writeTemplate command in online mode. When you execute the writeTemplate command while connected to the Administration Server from a remote machine, it dynamically packs the domain on the Administration Server into a template JAR file and transfers the template JAR to the specified directory.

The following sample WLST script demonstrates how to use writeTemplate to create or update a Managed Server domain on a remote machine. Run the script on each remote machine in the domain.

import os
 
wlsHome = os.getenv('WL_HOME')
mwHome = os.path.join(wlsHome, '..')
 
#Substitute the administrator user name and password values below as needed
connect('adminusername','adminpassword','localhost:7001')
 
#The path on the local machine where the template will be created, 
#it should not already exist.
templatePath = 'user_templates/myTemplate.jar'
 
#get the packed template from the Administration Server
writeTemplate(templatePath)
 
#disconnect from online WLST connection to the Administration Server
disconnect()

#select and load the template that was downloaded from the Administration 
#Server. 
selectCustomTemplate(templatePath)

loadTemplates()

#specify the domain directory where the domain needs to be created
domainPath = 'domains/myRemoteDomain')
 
#create the domain
writeDomain(domainPath)

Note:

When you use the writeDomain() command to copy the domain to the remote node, you must have write permissions to the applications directory (c:/Oracle/Middleware/user_projects/applications/mydomain/).