2 Using Ant Tasks to Configure and Use a WebLogic Server Domain
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
wlserverAnt task. -
Configure the new domain with required application resources using the
wlconfigAnt task. -
Deploy the application using the
wldeployAnt 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.
For action="start" or action="reboot", wlserver waits for the server to reach RUNNING, subject to timeout or timeoutSeconds. action="connect" attempts a management connection to an already running server; it does not use the startup polling loop. By default, a server started by this task is shut down when the Ant build finishes. Set noExit="true" to leave it running. Connecting to a server started outside the build does not register it for automatic shutdown.
The wlserver task extends Ant’s Java task and supports settings such as output and error for server output redirection. It also overrides some Java-task behavior: the server runs in a forked JVM; timeout and timeoutSeconds control the startup wait; and output redirection is ignored when noExit is true. See wlserver Ant Task Reference for these task-specific semantics and the Apache Ant Java task reference for inherited settings. wlserver Ant Task Reference; Apache Ant Java task reference
Note:
The default connection protocol is t3. To use a TLS-protected management endpoint, set protocol to t3s or https, use the port configured for that endpoint, and configure the Ant JVM to trust the server certificate. Use the endpoint required by the domain’s administration-channel and secured-production-mode configuration.Sample build.xml Files for wlserver
These are development examples. Supply WLS_USERNAME and WLS_PASSWORD through the environment used to launch Ant; for domain creation, the password must satisfy the domain’s password policy. Add the following once under the build file’s project element before these targets:
<property environment="env"/>
<fail unless="env.WLS_USERNAME" message="Set WLS_USERNAME before running Ant."/>
<fail unless="env.WLS_PASSWORD" message="Set WLS_PASSWORD before running Ant."/>
The following shows a minimal wlserver target that starts a server in the current directory using all default values:
<target name="wlserver-default">
<wlserver username="${env.WLS_USERNAME}" password="${env.WLS_PASSWORD}"/>
</target>
This target connects to an existing, running server using the indicated connection parameters and user name/password combination:
<target name="connect-server">
<wlserver username="${env.WLS_USERNAME}" password="${env.WLS_PASSWORD}" host="127.0.0.1" port="7001" action="connect"/>
</target>
This target starts a WebLogic Server instance configured in the config subdirectory:
<target name="start-server">
<wlserver username="${env.WLS_USERNAME}" password="${env.WLS_PASSWORD}" 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 username="${env.WLS_USERNAME}" password="${env.WLS_PASSWORD}" dir="./tmp" host="127.0.0.1" port="7001"
generateConfig="true" action="start"/>
</target>For existing domains, supply credentials for that domain and set servername to the configured server name when it differs from myserver.
These substitutions remove fixed secrets from the sample file; they do not conceal credentials from the server JVM command line, because explicit startup credentials are passed as JVM properties. These are not production credential-storage examples.
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? |
|---|---|---|---|
|
|
The path to the security policy file for the WebLogic Server domain. This attribute is used only for starting server instances. |
File |
No |
|
|
The path that holds the domain configuration (for example, |
File |
No |
|
|
The path to the Middleware Home directory (for example, |
File |
No |
|
|
The path to the WebLogic Server installation directory (for example, |
File |
No |
|
|
Name passed to the server process as weblogic.Name for start and reboot. The default is myserver; specify the configured name when starting a server with a different name. For connect and shutdown, the management endpoint identifies the target server.
For server-naming restrictions, see Domain and Server Name Restrictions |
String |
No; set it for start/reboot when the configured name differs from myserver. |
|
|
The name of the WebLogic Server domain in which the server is configured. |
String |
No |
|
|
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. |
|
|
The user name of an administrator account. Supply this attribute for the Ant task’s management connection. A server boot identity file does not supply credentials to the Ant task’s JMX client. See Boot Identity Files in the Administering Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties. |
String |
No |
|
|
The password of an administrator account. Supply this attribute for the Ant task’s management connection. A server boot identity file does not supply credentials to the Ant task’s JMX client. See Boot Identity Files in the Administering Server Startup and Shutdown for Oracle WebLogic Server for more information on boot.properties. |
String |
No |
|
|
The private key password for decrypting the SSL private key file. |
String |
No |
|
|
Maximum startup polling wait for action="start" or action="reboot", in milliseconds. 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. This does not configure a retry wait for action="connect". |
long |
No |
|
|
Maximum startup polling wait for action="start" or action="reboot", in seconds. 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. This does not configure a retry wait for action="connect". |
long |
No |
|
|
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 Valid values for this attribute are True and False. The task attribute defaults to false. When true, wlserver passes -Dweblogic.ProductionModeEnabled=true to the server JVM. When false, it does not set that JVM property; the server’s effective mode depends on the domain configuration and other startup settings. Note: If you boot the server in production mode by setting this attribute to |
Boolean |
No |
|
|
The DNS name or IP address on which the server instance is listening. The default value for this attribute is |
String |
No |
|
|
The TCP port number on which the server instance is listening. The default value for this attribute is |
int |
No |
|
|
Specifies whether or not Valid values for this attribute are |
Boolean |
No |
|
|
Specifies the action The The default value for this attribute is |
String |
No |
|
|
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 |
Boolean |
No |
|
|
This optional attribute is used in conjunction with the
|
Boolean |
No |
|
|
(Optional) Leave the server process running after the Ant build finishes. Valid values are |
Boolean |
No |
|
|
Specifies the protocol that the Valid values are |
String |
No |
|
|
Specifies whether the Valid values are For more information about upgrading domains, see Upgrading Oracle WebLogic Server. |
Boolean |
No. |
|
|
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 For an existing Administration Server domain, wlserver checks for the named configuration file under dir and then under dir/config. The default filename is config.xml. If dir is omitted, the base directory is the current directory. For a normal domain layout, retain the configuration at DOMAIN_HOME/config/config.xml and use DOMAIN_HOME as dir. |
String |
No. |
|
|
Specifies whether to use the This setting applies to credentials passed to the server process during startup. It does not supply the credentials used by the Ant task to monitor startup, connect, shut down, or reboot a server; provide username and password for those management connections. Valid values are true and false. Default: false. |
Boolean |
No |
|
|
Specifies that the Ant task output additional information as it is performing its action. Valid values for this attribute are |
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
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.
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? |
|---|---|---|---|
|
|
The URL of the domain's Administration Server. |
String |
Yes |
|
|
The user name of an administrator account. |
String |
No |
|
|
The password of an administrator account. To avoid having the plain text password appear in the build file or in process utilities such as If you want to obtain a user name and password from a non-default configuration file and key file, use the See the command reference for |
String |
No |
|
|
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 |
|
|
Specifies the location of a user configuration file to use for obtaining the administrative user name and password. Use this option, instead of the Before specifying the |
File |
No |
|
|
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 Before specifying the |
File |
No |
Nested Elements
wlconfig also has several elements that can be nested to specify configuration options:
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? |
|---|---|---|---|
|
|
The name of the new MBean object to create. |
String |
No ( |
|
|
The MBean type. |
String |
Yes |
|
|
Name of an optional Ant property that receives the ObjectName of the newly created MBean. It can be used on a top-level or nested create element. |
String |
No |
|
realm |
For security-provider creation, the name of the destination security realm. If omitted, the task uses the domain’s default realm; nesting a fully qualified security-provider create under a realm create does not replace this selector. |
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? |
|---|---|---|---|
|
|
The object name of the MBean to delete. |
String |
Required when the |
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? |
|---|---|---|---|
|
|
The name of the MBean attribute to set. |
String |
Yes |
|
|
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 |
|
|
The object name of the MBean whose values are being set. This attribute is required only when the |
String |
Required only when the |
Specify the complete target ObjectName, including its JMX domain, in mbean when set is a direct child of wlconfig. When nested in create or query, set receives its target from that parent.
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? |
|---|---|---|---|
|
|
The name of the MBean attribute whose value you want to retrieve. |
String |
Yes |
|
|
The name of an Ant property that will hold the retrieved MBean attribute value. |
String |
Yes |
|
|
ObjectName of the MBean whose attribute is read. A nested get reads the MBean currently selected by its parent query. |
String |
Required for a direct child of wlconfig; supplied by the enclosing query for a nested get. |
|
mbeanserver |
MBean server to read: edit, domainruntime or runtime. When omitted, a direct get uses edit and a nested get uses its query’s server. |
String |
No |
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? |
|---|---|---|---|
|
|
The name of the WebLogic Server domain in which to search for MBeans. |
String |
No |
|
|
The type of MBean to query. |
String |
No |
|
|
The name of the MBean to query. |
String |
No |
|
|
A JMX query pattern. |
String |
No |
|
|
The name of an optional Ant property that will store the query results. |
String |
No |
|
|
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? |
|---|---|---|---|
|
|
The object name of the MBean you want to invoke. |
String |
You must specify either the |
|
|
The type of MBean to invoke. |
String |
You must specify either the |
|
|
The method of the MBean to invoke. |
String |
Yes |
|
|
The list of arguments (separated by spaces) to pass to the method specified by the |
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
This is an online configuration edit through the Administration Server. Run it within an Ant target after defining wlconfig. Supply admin.url, admin.userconfig and admin.userkey as in the basic example. MyRealm must not already exist. The task activates the changes when it completes; the example creates an additional realm and leaves the current default realm selected. It does not configure users or demonstrate switching the domain’s active realm.
<wlconfig url="${admin.url}"
userconfigfile="${admin.userconfig}"
userkeyfile="${admin.userkey}">
<create type="weblogic.management.security.Realm"
name="MyRealm" property="new.realm">
<create name="MyAuthenticator" realm="MyRealm"
type="weblogic.security.providers.authentication.DefaultAuthenticator"/>
<create name="MyAuthorizer" realm="MyRealm"
type="weblogic.security.providers.authorization.DefaultAuthorizer"/>
<create name="MyRoleMapper" realm="MyRealm"
type="weblogic.security.providers.authorization.DefaultRoleMapper"/>
<create name="MyCredentialMapper" realm="MyRealm"
type="weblogic.security.providers.credentials.DefaultCredentialMapper"/>
<create name="MyCertPathProvider" realm="MyRealm"
type="weblogic.security.providers.pk.WebLogicCertPathProvider"
property="new.certpath"/>
</create>
<set mbean="${new.realm}" attribute="CertPathBuilder"
value="${new.certpath}"/>
</wlconfig>
Using the libclasspath Ant Task
Use the libclasspath Ant task to build applications that use libraries, such as application libraries and Web libraries.
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
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 . |
Either |
basewar |
The name of the |
If |
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 Additionally, if |
At least one of the two attributes is required. |
resourcepathproperty |
Contains library resources that are not classes. For example, if |
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
The following attribute is required when using this element:
dir—Specifies that all files in this directory are registered as available libraries.
Example libclasspath Ant Task
This section provides example code of a libclasspath Ant task:
Example 2-2 Example libclasspath Ant Task Code
Insert this taskdef and target fragment under the Ant project element.
<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.classpath is ${app.lib.classpath}" level="info"/>
</target>