2 Using Ant Tasks to Configure and Use a WebLogic Server Domain

Learn about how to start and stop WebLogic Server instances and configure WebLogic Server domains using WebLogic Ant tasks in your development build scripts.

This chapter includes the following sections:

• Overview of Configuring and Starting Domains Using Ant Tasks

• Starting Servers and Creating Domains Using the wlserver Ant Task

• Configuring a WebLogic Server Domain Using the wlconfig Ant Task

• Using the libclasspath Ant Task

• Overview of Configuring and Starting Domains Using Ant Tasks
  WebLogic Server provides a pair of Ant tasks to help you perform common configuration tasks in a development environment. The configuration tasks enable you to start and stop WebLogic Server instances as well as create and configure WebLogic Server domains.
• Starting Servers and Creating Domains Using the wlserver Ant Task
  The wlserver Ant task enables you to start, reboot, shutdown, or connect to a WebLogic Server instance. The server instance may already exist in a configured WebLogic Server domain, or you can create a new single-server domain for development by using the generateconfig=true attribute.
• Configuring a WebLogic Server Domain Using the wlconfig Ant Task
  You can use the wlconfig Ant task or the WebLogic Scripting Tool (WLST) to configure a WebLogic Server domain.
• Example of Creating a Security Realm with the wlconfig Ant Task
  You can use this example to create a security realm with the wlconfig Ant task:
• Using the libclasspath Ant Task
  Use the libclasspath Ant task to build applications that use libraries, such as application libraries and Web libraries.

Overview of Configuring and Starting Domains Using Ant Tasks

WebLogic Server provides a pair of Ant tasks to help you perform common configuration tasks in a development environment. The configuration tasks enable you to start and stop WebLogic Server instances as well as create and configure WebLogic Server domains.

When combined with other WebLogic Ant tasks, you can create powerful build scripts for demonstrating or testing your application with custom domains. For example, a single Ant build script can:

• Compile your application using the wlcompile, wlappc, and Web services Ant tasks.

• Create a new single-server domain and start the Administration Server using the wlserver Ant task.

• Configure the new domain with required application resources using the wlconfig Ant task.

• Deploy the application using the wldeploy Ant task.

• Automatically start a compiled client application to demonstrate or test product features.

The sections that follow describe how to use the configuration Ant tasks, wlserver and wlconfig.

Starting Servers and Creating Domains Using the wlserver Ant Task

The wlserver Ant task enables you to start, reboot, shutdown, or connect to a WebLogic Server instance. The server instance may already exist in a configured WebLogic Server domain, or you can create a new single-server domain for development by using the generateconfig=true attribute.

When you use the wlserver task in an Ant script, the task does not return control until the specified server is available and listening for connections. If you start up a server instance using wlserver, the server process automatically terminates after the Ant VM terminates. If you only connect to a currently-running server using the wlserver task, the server process keeps running after Ant completes.

The wlserver WebLogic Server Ant task extends the standard java Ant task (org.apache.tools.ant.taskdefs.Java). This means that all the attributes of the java Ant task also apply to the wlserver Ant task. For example, you can use the output and error attributes to specify the name of the files to which output and standard errors of the wlserver Ant task is written, respectively. For full documentation about the attributes of the standard Java Ant task, see Java on the Apache Ant site (http://ant.apache.org/manual/Tasks/java.html).

• Basic Steps for Using wlserver
  
• Sample build.xml Files for wlserver
  
• wlserver Ant Task Reference
  

Basic Steps for Using wlserver

To use the wlserver Ant task:

1. Set your environment.

   On Windows, execute the setWLSEnv.cmd command, located in the directory WL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation.

   On UNIX, execute the setWLSEnv.sh command, located in the directoryWL_HOME\server\bin, where WL_HOME is the top-level directory of your WebLogic Server installation.

   Note:

   The wlserver task is predefined in the version of Ant shipped with WebLogic Server. If you want to use the task with your own Ant installation, add the following task definition in your build file:

   <taskdef name="wlserver" classname="weblogic.ant.taskdefs.management.WLServer"/>

   Note:

   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.

2. Add a call to the wlserver task in the build script to start, shutdown, restart, or connect to a server. See wlserver Ant Task Reference for information about wlserver attributes and default behavior.
3. Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:

   prompt> ant
   

   Use ant -verbose to obtain more detailed messages from the wlserver task.

Sample build.xml Files for wlserver

The following shows a minimal wlserver target that starts a server in the current directory using all default values:

<target name="wlserver-default">
  <wlserver/>
</target>

This target connects to an existing, running server using the indicated connection parameters and user name/password combination:

<target name="connect-server">
  <wlserver host="127.0.0.1" port="7001" username="weblogic" password="weblogic" action="connect"/>
</target>

This target starts a WebLogic Server instance configured in the config subdirectory:

<target name="start-server">
  <wlserver dir="./config" host="127.0.0.1" port="7001" action="start"/>
</target>

This target creates a new single-server domain in an empty directory, and starts the domain's server instance:

<target name="new-server">
  <delete dir="./tmp"/>
  <mkdir dir="./tmp"/>
  <wlserver dir="./tmp" host="127.0.0.1" port="7001"
  generateConfig="true" username="weblogic" password="weblogic" action="start"/>
</target>

wlserver Ant Task Reference

The following table describes the attributes of the wlserver Ant task.

Table 2-1 Attributes of the wlserver Ant Task

Attribute	Description	Data Type	Required?
policy	The path to the security policy file for the WebLogic Server domain. This attribute is used only for starting server instances.	File	No
dir	The path that holds the domain configuration (for example, c:\Oracle\Middleware\user_projects\domains\mydomain). By default, wlserver uses the current directory.	File	No
beahome	The path to the Middleware Home directory (for example, c:\Oracle\Middleware).	File	No
weblogichome	The path to the WebLogic Server installation directory (for example, c:\Oracle\Middleware\wlserver_12.1).	File	No
servername	The name of the server to start, shutdown, reboot, or connect to. A WebLogic Server instance is uniquely identified by its protocol, host, and port values, so if you use this set of attributes to specify the server you want to start, shutdown or reboot, you do not need to specify its actual name using the servername attribute. The only exception is when you want to shutdown the Administration server; in this case you must specify this attribute. The default value for this attribute is myserver. For more information on server naming convention, see Domain and Server Name Restrictions in Understanding Domain Configuration for Oracle WebLogic Server.	String	Required only when shutting down the Administration server.
domainname	The name of the WebLogic Server domain in which the server is configured.	String	No
adminserverurl	The URL to access the Administration Server in the domain. This attribute is required if you are starting up a Managed Server in the domain.	String	Required for starting Managed Servers.
username	The user name of an administrator account. If you omit both the username and password attributes, wlserver attempts to obtain the encrypted user name and password values from the boot.properties file. See Boot Identity Files in the Administering Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties.	String	No
password	The password of an administrator account. If you omit both the username and password attributes, wlserver attempts to obtain the encrypted user name and password values from the boot.properties file. See Boot Identity Files in the Administering Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties.	String	No
pkpassword	The private key password for decrypting the SSL private key file.	String	No
timeout	The maximum time, in milliseconds, that wlserver waits for a server to boot. This also specifies the maximum amount of time to wait when connecting to a running server. The default value for this attribute is 0, which means that the Ant task will wait indefinitely until the server transitions to theRUNNING state.	long	No
timeoutSeconds	The maximum time, in seconds, that wlserver waits for a server to boot. This also specifies the maximum amount of time to wait when connecting to a running server. The default value for this attribute is 0,which means that the Ant task will wait indefinitely until the server transitions to the RUNNING state.	long	No
productionmodeenabled	Specifies whether a server instance boots in development mode or in production mode. Development mode enables a WebLogic Server instance to automatically deploy and update applications that are in the domain_name/autodeploy directory (where domain_name is the name of a WebLogic Server domain). In other words, development mode lets you use auto-deploy. Production mode disables the auto-deployment feature. See Deploying Applications and Modules for more information. Valid values for this attribute are True and False. The default value is False (which means that by default a server instance boots in development mode.) Note: If you boot the server in production mode by setting this attribute to True, you must reboot the server to set the mode back to development mode. Or in other words, you cannot reset the mode on a running server using other administrative tools, such as the WebLogic Server Scripting Tool (WLST).	Boolean	No
host	The DNS name or IP address on which the server instance is listening. The default value for this attribute is localhost.	String	No
port	The TCP port number on which the server instance is listening. The default value for this attribute is 7001.	int	No
generateconfig	Specifies whether or not wlserver creates a new domain for the specified server. Valid values for this attribute are true and false. The default value is false.	Boolean	No
action	Specifies the action wlserver performs: start, shutdown, reboot, or connect. The shutdown action can be used with the optional forceshutdown attribute perform a forced shutdown. The default value for this attribute is start.	String	No
failonerror	This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. Valid values for this attribute are true and false. The default value is false.	Boolean	No
forceshutdown	This optional attribute is used in conjunction with the action="shutdown" attribute to perform a forced shutdown. For example: <wlserver host="${wls.host}" port="${port}" username="${wls.username}" password="${wls.password}" action="shutdown" forceshutdown="true"/> Valid values for this attribute are true and false. The default value is false.	Boolean	No
noExit	(Optional) Leave the server process running after Ant exits. Valid values are true or false. The default value is false, which means the server process will shut down when Ant exits.	Boolean	No
protocol	Specifies the protocol that the wlserver Ant task uses to communicate with the WebLogic Server instance. Valid values are t3, t3s, http, https, and iiop. The default value is t3.	String	No
forceImplicitUpgrade	Specifies whether the wlserver Ant task, if run against an 8.1 (or previous) domain, should implicitly upgrade it. Valid values are true or false. The default value is false, which means that the Ant task does not implicitly upgrade the domain, but rather, will fail with an error indicating that the domain needs to be upgraded. For more information about upgrading domains, see Upgrading Oracle WebLogic Server.	Boolean	No.
configFile	Specifies the configuration file for your domain. The value of this attribute must be a valid XML file that conforms to the XML schema as defined in the WebLogic Server Domain Configuration Schema at http://xmlns.oracle.com/weblogic/domain/1.0/domain.xsd. The XML file must exist in the Administration Server's root directory, which is either the current directory or the directory that you specify with the dir attribute. If you do not specify this attribute, the default value is config.xml in the directory specified by the dir attribute. If you do not specify the dir attribute, then the default domain directory is the current directory.	String	No.
useBootProperties	Specifies whether to use the boot.properties file when starting a WebLogic Server instance. If this attribute is set to true, WebLogic Server uses the user name and encrypted password stored in the boot.properties file to start rather than any values set with the username and password attributes. Note: The values of the username and password attributes are still used when shutting down or rebooting the WebLogic Server instance. The useBootProperties attribute applies only when starting the server. Valid values for this attribute are true and false. The default value is false.	Boolean	No
verbose	Specifies that the Ant task output additional information as it is performing its action. Valid values for this attribute are true and false. The default value is false.	Boolean	No

Configuring a WebLogic Server Domain Using the wlconfig Ant Task

You can use the wlconfig Ant task or the WebLogic Scripting Tool (WLST) to configure a WebLogic Server domain.

The following sections describe how to use the wlconfig Ant task to configure a WebLogic Server domain.

Note:

For equivalent functionality, you should use the WebLogic Scripting Tool (WLST). See Understanding the WebLogic Scripting Tool.

• What the wlconfig Ant Task Does
  
• Basic Steps for Using wlconfig
  
• wlconfig Ant Task Reference
  
• Main Attributes
  
• Nested Elements
  

What the wlconfig Ant Task Does

The wlconfig Ant task enables you to configure a WebLogic Server domain by creating, querying, or modifying configuration MBeans on a running Administration Server instance. Specifically, wlconfig enables you to:

• Create new MBeans, optionally storing the new MBean Object Names in Ant properties.

• Set attribute values on a named MBean available on the Administration Server.

• Create MBeans and set their attributes in one step by nesting set attribute commands within create MBean commands.

• Query MBeans, optionally storing the query results in an Ant property reference.

• Query MBeans and set attribute values on all matching results.

• Establish a parent/child relationship among MBeans by nesting create commands within other create commands.

Basic Steps for Using wlconfig

1. Set your environment in a command shell. See Basic Steps for Using wlserver for details.

   Note:

   The wlconfig task is predefined in the version of Ant shipped with WebLogic Server. If you want to use the task with your own Ant installation, add the following task definition in your build file:

   <taskdef name="wlconfig" classname="weblogic.ant.taskdefs.management.WLConfig"/>

2. wlconfig is commonly used in combination with wlserver to configure a new WebLogic Server domain created in the context of an Ant task. If you will be using wlconfig to configure such a domain, first use wlserver attributes to create a new domain and start the WebLogic Server instance.
3. Add an initial call to the wlconfig task to connect to the Administration Server for a domain. For example:

   <target name="doconfig">
      <wlconfig url="t3://localhost:7001" username="weblogic"
         password=password>
   </target>
   

4. Add nested create, delete, get, set, and query elements to configure the domain.
5. Execute the Ant task or tasks specified in the build.xml file by typing ant in the staging directory, optionally passing the command a target argument:

   prompt> ant doconfig
   

   Use ant -verbose to obtain more detailed messages from the wlconfig task.

   Note:

   Since WLST is the recommended tool for domain creation scripts, you should refer to the WLST offline sample scripts that are installed with the software. The offline scripts demonstrate how to create domains using the domain templates and are located in the following directory: WL_HOME\common\templates\scripts\wlst, where WL_HOME refers to the top-level installation directory for WebLogic Server. For example, the basicWLSDomain.py script creates a simple WebLogic domain, while sampleMedRecDomain.py creates a domain that defines resources similar to those used in the Avitek MedRec sample. See Understanding the WebLogic Scripting Tool.

wlconfig Ant Task Reference

The following sections describe the attributes and elements that can be used with wlconfig.

Main Attributes

The following table describes the main attributes of the wlconfig Ant task.

Table 2-2 Main Attributes of the wlconfig Ant Task

Attribute	Description	Data Type	Required?
url	The URL of the domain's Administration Server.	String	Yes
username	The user name of an administrator account.	String	No
password	The password of an administrator account. To avoid having the plain text password appear in the build file or in process utilities such as ps, first store a valid user name and encrypted password in a configuration file using the WebLogic Scripting Tool (WLST) storeUserConfig command. Then omit both the username and password attributes in your Ant build file. When the attributes are omitted, wlconfig attempts to login using values obtained from the default configuration file. If you want to obtain a user name and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wlconfig. See the command reference for storeUserConfig in the Understanding the WebLogic Scripting Tool for more information on storing and encrypting passwords.	String	No
failonerror	This is a global attribute used by WebLogic Server Ant tasks. It specifies whether the task should fail if it encounters an error during the build. This attribute is set to true by default.	Boolean	No
userconfigfile	Specifies the location of a user configuration file to use for obtaining the administrative user name and password. Use this option, instead of the username and password attributes, in your build file when you do not want to have the plain text password shown in-line or in process-level utilities such as ps. Before specifying the userconfigfile attribute, you must first generate the file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the Understanding the WebLogic Scripting Tool.	File	No
userkeyfile	Specifies the location of a user key file to use for encrypting and decrypting the user name and password information stored in a user configuration file (the userconfigfile attribute). Before specifying the userkeyfile attribute, you must first generate the key file using the WebLogic Scripting Tool (WLST) storeUserConfig command as described in the Understanding the WebLogic Scripting Tool.	File	No

Nested Elements

wlconfig also has several elements that can be nested to specify configuration options:

• create

• delete

• set

• get

• query

• invoke

• create
  
• delete
  
• set
  
• get
  
• query
  
• invoke
  

create

The create element creates a new MBean in the WebLogic Server domain. The wlconfig task can have any number of create elements.

A create element can have any number of nested set elements, which set attributes on the newly-created MBean. A create element may also have additional, nested create elements that create child MBeans.

The create element has the following attributes.

Table 2-3 Attributes of the create Element

Attribute	Description	Data Type	Required?
name	The name of the new MBean object to create.	String	No (wlconfig supplies a default name if none is specified.)
type	The MBean type.	String	Yes
property	The name of an optional Ant property that holds the object name of the newly-created MBean. Note: If you nest a create element inside of another create element, you cannot specify the property attribute for the nested create element.	String	No

delete

The delete element removes an existing MBean from the WebLogic Server domain. delete takes a single attribute:

Table 2-4 Attribute of the delete Element

Attribute	Description	Data Type	Required?
mbean	The object name of the MBean to delete.	String	Required when the delete element is a direct child of the wlconfig task. Not required when nested within a query element.

set

The set element sets MBean attributes on a named MBean, a newly-created MBean, or on MBeans retrieved as part of a query. You can include the set element as a direct child of the wlconfig task, or nested within a create or query element.

The set element has the following attributes:

Table 2-5 Attributes of the set Element

Attribute	Description	Data Type	Required?
attribute	The name of the MBean attribute to set.	String	Yes
value	The value to set for the specified MBean attribute. You can specify multiple object names (stored in Ant properties) as a value by delimiting the entire value list with quotes and separating the object names with a semicolon.	String	Yes
mbean	The object name of the MBean whose values are being set. This attribute is required only when the set element is included as a direct child of the main wlconfig task; it is not required when the set element is nested within the context of a create or query element.	String	Required only when the set element is a direct child of the wlconfig task.
domain	This attribute specifies the JMX domain name for Security MBeans and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain. Note: You cannot use this attribute if the set element is nested inside of a create element.	String	No

get

The get element retrieves attribute values from an MBean in the WebLogic Server domain. The wlconfig task can have any number of get elements.

The get element has the following attributes.

Table 2-6 Attributes of the get Element

Attribute	Description	Data Type	Required?
attribute	The name of the MBean attribute whose value you want to retrieve.	String	Yes
property	The name of an Ant property that will hold the retrieved MBean attribute value.	String	Yes
mbean	The object name of the MBean you want to retrieve attribute values from.	String	Yes

query

The query elements finds MBean that match a search pattern.

The query element supports the following nested child elements:

• set—performs set operations on all MBeans in the result set.

• get—performs get operations on all MBeans in the result set.

• create—each MBean in the result set is used as a parent of a new MBean.

• delete—performs delete operations on all MBeans in the result set.

• invoke—invokes all matching MBeans in the result set.

wlconfig can have any number of nested query elements.

query has the following attributes:

Table 2-7 Attributes of the query Element

Attribute	Description	Data Type	Required?
domain	The name of the WebLogic Server domain in which to search for MBeans.	String	No
type	The type of MBean to query.	String	No
name	The name of the MBean to query.	String	No
pattern	A JMX query pattern.	String	No
property	The name of an optional Ant property that will store the query results.	String	No
domain	This attribute specifies the JMX domain name for Security MBeans and third-party SPI MBeans. It is not required for administration MBeans, as the domain corresponds to the WebLogic Server domain.	String	No

invoke

The invoke element invokes a management operation for one or more MBeans. For WebLogic Server MBeans, you usually use this command to invoke operations other than the getAttribute and setAttribute that most WebLogic Server MBeans provide.

The invoke element has the following attributes.

Table 2-8 Attributes of the invoke Element

Attribute	Description	Data Type	Required?
mbean	The object name of the MBean you want to invoke.	String	You must specify either the mbean or type attribute of the invoke element.
type	The type of MBean to invoke.	String	You must specify either the mbean or type attribute of the invoke element.
methodName	The method of the MBean to invoke.	String	Yes
arguments	The list of arguments (separated by spaces) to pass to the method specified by the methodName attribute.	String	No

Example of Creating a Security Realm with the wlconfig Ant Task

You can use this example to create a security realm with the wlconfig Ant task:

Example 2-1 Creating a Security Realm with wlconfig

<wlconfig url="t3://myhost:7001"
      username="weblogic"
      password="password">
   <create type="weblogic.management.security.Realm" name="MyRealm" property="new.provider">
      <set attribute="DefaultRealm" value="false"/>
      <create name="MyAuthenticator" type="weblogic.security.providers.authentication.DefaultAuthenticator" realm="MyRealm"/>
      <create name="MyAuthorizer" type="weblogic.security.providers.authorization.DefaultAuthorizer" realm="MyRealm"/>
      <create name="MyRoleMapper" type="weblogic.security.providers.authorization.DefaultRoleMapper" realm="MyRealm"/>
      <create name="MyCredentialMapper" type="weblogic.security.providers.credentials.DefaultCredentialMapper" realm="MyRealm"/>
      <create name="MyCertPathProvider" type=""weblogic.security.providers.pk.WebLogicCertPathProvider" realm="MyRealm"/>
   </create>
   <set mbean="Security:Name=MyRealm" attribute="CertPathBuilder" value="Security:Name=MyRealmMyCertPathProvider"/>
</wlconfig>

Using the libclasspath Ant Task

Use the libclasspath Ant task to build applications that use libraries, such as application libraries and Web libraries.

The following sections describe how to build applications:

• libclasspath Task Definition

• wlserver Ant Task Reference

• Example libclasspath Ant Task

• libclasspath Task Definition
  
• libclasspath Ant Task Reference
  
• Main libclasspath Attributes
  
• Nested libclasspath Elements
  
• Example libclasspath Ant Task
  

libclasspath Task Definition

To use the task with your own Ant installation, add the following task definition in your build file:

<taskdef name="libclasspath" classname="weblogic.ant.taskdefs.build.LibClasspathTask"/>

libclasspath Ant Task Reference

The following sections describe the attributes and elements that can be used with the libclasspath Ant task.

• Main libclasspath Attributes

• Nested libclasspath Elements

Main libclasspath Attributes

The following table describes the main attributes of the libclasspath Ant task.

Table 2-9 Attributes of the libclasspath Ant Task

Attribute	Description	Required
basedir	The root of .ear or .war file to extract from.	Either basedir or basewar is required.
basewar	The name of the .war file to extract from.	If basewar is specified, basedir is ignored and the library referenced in basewar is used as the .war file to extract classpath or resourcepath information from.
tmpdir	The fully qualified name of the directory to be used for extracting libraries.	Yes.
classpathproperty	Contains the classpath for the referenced libraries. For example, if basedir points to a .war file that references Web application libraries in the weblogic.xml file, the classpathproperty contains the WEB-INF/classes and WEB-INF/lib directories of the Web application libraries. Additionally, if basedir points to a .war file that has .war files under WEB-INF/bea-ext, the classpathproperty contains the WEB-INF/classes and WEB-INF/lib directories for the Oracle extensions.	At least one of the two attributes is required.
resourcepathproperty	Contains library resources that are not classes. For example, if basedir points to a .war file that has .war files under WEB-INF/bea-ext, resourcepathproperty contains the roots of the exploded extensions.

Nested libclasspath Elements

libclasspath also has two elements that can be nested to specify configuration options. At least one of the elements is required when using the libclasspath Ant task:

• librarydir
  
• library
  

librarydir

The following attribute is required when using this element:

dir—Specifies that all files in this directory are registered as available libraries.

library

The following attribute is required when using this element:

file—Register this file as an available library.

Example libclasspath Ant Task

This section provides example code of a libclasspath Ant task:

Example 2-2 Example libclasspath Ant Task Code

.
.
.
   <taskdef name="libclasspath" classname="weblogic.ant.taskdefs.build.LibClasspathTask"/>

   <!-- Builds classpath based on libraries defined in weblogic-application.xml. -->
   <target name="init.app.libs"> 
      <libclasspath basedir="${src.dir}" tmpdir="${tmp.dir}" classpathproperty="app.lib.classpath">
         <librarydir dir="${weblogic.home}/common/deployable-libraries/"/>
      </libclasspath>
   <echo message="app.lib.claspath is ${app.lib.classpath}" level="info"/>
   </target>
.
.
.