The following sections describe how to start and stop WebLogic Server instances and configure WebLogic Server domains using WebLogic Ant tasks that you can include in your development build scripts:
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
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
.
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
).
To use the wlserver Ant task:
Set your environment.
On Windows NT, 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:
Thewlserver
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"/>
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.
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.
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 username/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>
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, |
File |
No |
beahome |
The path to the Middleware Home directory (for example, |
File |
No |
weblogichome |
The path to the WebLogic Server installation directory (for example, |
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 The default value for this attribute is |
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 username of an administrator account. If you omit both the |
String |
No |
password |
The password of an administrator account. If you omit both the |
String |
No |
pkpassword |
The private key password for decrypting the SSL private key file. |
String |
No |
timeout |
The maximum time, in milliseconds, that The default value for this attribute is |
long |
No |
timeoutSeconds |
The maximum time, in seconds, that The default value for this attribute is |
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 Valid values for this attribute are Note: If you boot the server in production mode by setting this attribute to |
boolean |
No |
host |
The DNS name or IP address on which the server instance is listening. The default value for this attribute is |
String |
No |
port |
The TCP port number on which the server instance is listening. The default value for this attribute is |
int |
No |
generateconfig |
Specifies whether or not Valid values for this attribute are |
boolean |
No |
action |
Specifies the action The The default value for this attribute is |
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 |
Boolean |
No |
forceshutdown |
This optional attribute is used in conjunction with the <wlserver host="${wls.host}" port="${port}" username="${wls.username}" password="${wls.password}" action="shutdown" forceshutdown="true"/>
|
Boolean |
No |
noExit |
(Optional) Leave the server process running after ant exits. Valid values are |
Boolean |
No |
protocol |
Specifies the protocol that the Valid values are |
String |
No |
forceImplicitUpgrade |
Specifies whether the Valid values are For more information about upgrading domains, see Upgrade Guide for 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 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 If you do not specify this attribute, the default value is |
String |
No. |
useBootProperties |
Specifies whether to use the Note: The values of the |
Boolean |
No |
verbose |
Specifies that the Ant task output additional information as it is performing its action. Valid values for this attribute are |
Boolean |
No |
The following sections describe how to use the wlconfig
Ant task to configure a WebLogic Server domain.
Note::
Thewlconfig
Ant task works only against MBeans that are compatible with the MBean server, which was deprecated as of version 9.0 of WebLogic Server. In particular, the wlconfig
Ant task uses the deprecated proprietary API weblogic.management.MBeanHome
to access WebLogic MBeans; therefore, wlconfig
does not use the standard JMX interface (javax.management.MBeanServerConnection
) to discover MBeans. This means that the only MBeans that you can access using wlconfig
are those listed under the Deprecated MBeans category in the Oracle WebLogic Server MBean Reference
For equivalent functionality, you should use the WebLogic Scripting Tool (WLST). See Oracle WebLogic Scripting Tool.
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.
Set your environment in a command shell. See Basic Steps for Using wlserver for details.
Note:
Thewlconfig
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"/>
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.
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="weblogic"> </target>
Add nested create
, delete
, get
, set
, and query
elements to configure the domain.
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 Oracle WebLogic Scripting Tool.The following sections describe the attributes and elements that can be used with wlconfig
.
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 username 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 If you want to obtain a username and password from a non-default configuration file and key file, use the See the command reference for |
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 username and password. Use this option, instead of the Before specifying the |
File |
No |
userkeyfile |
Specifies the location of a user key file to use for encrypting and decrypting the username and password information stored in a user configuration file (the Before specifying the |
File |
No |
wlconfig
also has several elements that can be nested to specify configuration options:
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 ( |
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 |
String |
No |
The delete
element removes an existing MBean from the WebLogic Server domain. delete
takes a single attribute:
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 |
String |
Required only when the |
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 |
String |
No |
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 |
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 |
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 get
Attribute
and set
Attribute
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 |
type |
The type of MBean to invoke. |
String |
You must specify either the |
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 |
String |
No |
Use the libclasspath
Ant task to build applications that use libraries, such as application libraries and web libraries.
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"/>
The following sections describe the attributes and elements that can be used with the libclasspath
Ant task.
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 .war file to extract from. |
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 |
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:
The following attribute is required when using this element:
dir
—Specifies that all files in this directory are registered as available libraries.
This section provides example code of a libclasspath
Ant task:
Example 2-1 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> . . .