Using Ant Tasks to Configure a WebLogic Server Domain

Using Ant Tasks to Configure a WebLogic Server Domain

The following sections describe how to start and stop WebLogic Server instances and configure WebLogic Server domains using WebLogic Ant tasks:
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

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. For more information about other Ant tasks included with WebLogic Server, see the WebLogic Server Tools Reference.

Starting Servers and Creating Domains Using the wlserver Ant Task

What the wlserver Ant Task Does

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.

Basic Steps for Using wlserver

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 directory WL_HOME/server/bin, where WL_HOME is the top-level directory of your WebLogic Server installation. Note that 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"/>
Add a call to the wlserver task in the build script to start, shutdown, restart, or connect to a server.
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 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>
wlserver Ant Task Reference

The following table describes the 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:\bea\user_projects\mydomain). By default, wlserver uses the current directory. File No
beahome The path to the BEA home directory (for example, c:\bea). File No
weblogichome The path to the WebLogic Server installation directory (for example, c:\bea\weblogic81). File No
servername The name of the server to start, reboot, or connect to. String No
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 username and password attributes, wlserver attempts to obtain the encrypted username and password values from the boot.properties file. See Default Behavior 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 username and password values from the boot.properties file. See Default Behavior 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 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. long No
productionmodeenabled Specifies whether a server instance boots in development mode or in production mode. boolean No
host The DNS name or IP address on which the server instance is listening. String No
port The TCP port number on which the server instance is listening. int No
generateconfig Specifies whether or not wlserver creates a new domain for the specified server. This attribute is false by default. boolean No
action Specifies the action wlserver performs: startup, shutdown, reboot, or connect.The shutdown action can be used with the optional forceshutdown attribute perform a forced shutdown. 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
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"/> Boolean No

Configuring a WebLogic Server Domain Using the wlconfig Ant Task

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
Set your environment in a command shell. See Basic Steps for Using wlserver for details. Note that 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"/>
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.
Sample build.xml Files for wlconfig

Complete Example

This example shows a single build.xml file that creates a new domain using wlserver and performs various domain configuration tasks with wlconfig. The configuration tasks set up domain resources required by the Avitek Medical Records sample application.
The script starts by creating the new domain:
<target name="medrec.config">



   <mkdir dir="config"/>



   <wlserver username="a" password="a" servername="MedRecServer"



      domainname="medrec" dir="config" host="localhost" port="7000"



      generateconfig="true"/>
The script then starts the wlconfig task by accessing the newly-created server:
   <wlconfig url="t3://localhost:7000" username="a" password="a">
Within the wlconfig task, the query element runs a query to obtain the Server MBean object name, and stores this MBean in the ${medrecserver} Ant property:
    <query domain="medrec" type="Server" name="MedRecServer"



         property="medrecserver"/>
The script the uses a create element to create a new JDBC connection pool in the domain, storing the object name in the ${medrecpool} Ant property. Nested set elements in the create operation set attributes on the newly-created MBean. The new pool is target to the server using the ${medrecserver} Ant property set in the query above:
   <create type="JDBCConnectionPool" name="MedRecPool"



      property="medrecpool">



      <set attribute="CapacityIncrement" value="1"/>



      <set attribute="DriverName"



         value="com.pointbase.jdbc.jdbcUniversalDriver"/>



      <set attribute="InitialCapacity" value="1"/>



      <set attribute="MaxCapacity" value="10"/>



      <set attribute="Password" value="MedRec"/>



      <set attribute="Properties" value="user=MedRec"/>



      <set attribute="RefreshMinutes" value="0"/>



      <set attribute="ShrinkPeriodMinutes" value="15"/>



      <set attribute="ShrinkingEnabled" value="true"/>



      <set attribute="TestConnectionsOnRelease" value="false"/>



      <set attribute="TestConnectionsOnReserve" value="false"/>



      <set attribute="URL"



         value="jdbc:pointbase:server://localhost/demo"/>



      <set attribute="Targets" value="${medrecserver}"/>



   </create>
Next, the script creates a JDBC TX DataSource using the JDBC connection pool created above:
   <create type="JDBCTxDataSource" name="Medical Records Tx DataSource">



      <set attribute="JNDIName" value="MedRecTxDataSource"/>



      <set attribute="PoolName" value="MedRecPool"/>



      <set attribute="Targets" value="${medrecserver}"/>



   </create>
The script creates a new JMS connection factory using nested set elements:
   <create type="JMSConnectionFactory" name="Queue">



      <set attribute="JNDIName" value="jms/QueueConnectionFactory"/>



      <set attribute="XAServerEnabled" value="true"/>



      <set attribute="Targets" value="${medrecserver}"/>



   </create>
A new JMS JDBC store is created using the MedRecPool:
   <create type="JMSJDBCStore" name="MedRecJDBCStore"



      property="medrecjdbcstore">



      <set attribute="ConnectionPool" value="${medrecpool}"/>



      <set attribute="PrefixName" value="MedRec"/>



   </create>
When creating a new JMS server, the script uses a nested create element to create a JMS queue, which is the child of the JMS server:
   <create type="JMSServer" name="MedRecJMSServer">



      <set attribute="Store" value="${medrecjdbcstore}"/>



      <set attribute="Targets" value="${medrecserver}"/>



      <create type="JMSQueue" name="Registration Queue">



         <set attribute="JNDIName" value="jms/REGISTRATION_MDB_QUEUE"/>



      </create>



   </create>
This script creates a new mail session and startup class:
   <create type="MailSession" name="Medical Records Mail Session">



      <set attribute="JNDIName" value="mail/MedRecMailSession"/>



      <set attribute="Properties"



         value="mail.user=joe;mail.host=mail.mycompany.com"/>



      <set attribute="Targets" value="${medrecserver}"/>



   </create>
   <create type="StartupClass" name="StartBrowser">



      <set attribute="Arguments" value="port=${listenport}"/>



      <set attribute="ClassName"



         value="com.bea.medrec.startup.StartBrowser"/>



      <set attribute="FailureIsFatal" value="false"/>



      <set attribute="Notes" value="Automatically starts a browser on server boot."/>
      <set attribute="Targets" value="${medrecserver}"/>
    </create>
Finally, the script obtains the WebServer MBean and sets the log filename using a nested set element:
      <query domain="medrec" type="WebServer" name="MedRecServer">



         <set attribute="LogFileName" value="logs/access.log"/>



      </query>



   </wlconfig>



</target>
Query and Delete Example

The query element does not need to specify an MBean name when nested within a query element:
<target name="queryDelete">



   <wlconfig url="${adminurl}" username="${user}" password="${pass}"



      failonerror="false">



      <query query="${wlsdomain}:Name=MyNewServer2,*"



         property="deleteQuery">



         <delete/>



      </query>



   </wlconfig>



</target>
Example of Setting Multiple Attribute Values

The set element allows you to set an attribute value to multiple object names stored in Ant properties. For example, the following target stores the object names of two servers in separate Ant properties, then uses those properties to assign both servers to the target attribute of a new JDBC Connection Pool:
<target name="multipleJDBCTargets">



   <wlconfig url="${adminurl}" username="${user}" password="${pass}">



      <query domain="mydomain" type="Server" name="MyServer"



         property="myserver"/>



      <query domain="mydomain" type="Server" name="OtherServer"



         property="otherserver"/>



      <create type="JDBCConnectionPool" name="sqlpool" property="sqlpool">



         <set attribute="CapacityIncrement" value="1"/>



[.....]



         <set attribute="Targets" value="${myserver};${otherserver}"/>



      </create>



   </wlconfig>



</target>
wlconfig Ant Task Reference

Main Attributes

The following table describes the 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 ps, first store a valid username and encrypted password in a configuration file using the weblogic.Admin 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 username and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wlconfig.See STOREUSERCONFIG 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 username 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, first generate the file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG. 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 userconfigfile attribute). Before specifying the userkeyfile attribute, first generate the key file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG. File No

Nested Elements

wlconfig also has several elements that can be nested to specify configuration options:
create
delete
set
get
query

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.

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. String No

delete

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

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:

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. See Example of Setting Multiple Attribute Values. 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. 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.

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. query can be used with nested set elements or a nested delete element to perform set or delete operations on all MBeans in the result set.
wlconfig can have any number of nested query elements.
query has the following attributes:

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

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:\bea\user_projects\mydomain). By default, wlserver uses the current directory.	File	No
beahome	The path to the BEA home directory (for example, c:\bea).	File	No
weblogichome	The path to the WebLogic Server installation directory (for example, c:\bea\weblogic81).	File	No
servername	The name of the server to start, reboot, or connect to.	String	No
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 username and password attributes, wlserver attempts to obtain the encrypted username and password values from the boot.properties file. See Default Behavior 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 username and password values from the boot.properties file. See Default Behavior 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 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.	long	No
productionmodeenabled	Specifies whether a server instance boots in development mode or in production mode.	boolean	No
host	The DNS name or IP address on which the server instance is listening.	String	No
port	The TCP port number on which the server instance is listening.	int	No
generateconfig	Specifies whether or not wlserver creates a new domain for the specified server. This attribute is false by default.	boolean	No
action	Specifies the action wlserver performs: startup, shutdown, reboot, or connect.The shutdown action can be used with the optional forceshutdown attribute perform a forced shutdown.	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
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"/>	Boolean	No

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 ps, first store a valid username and encrypted password in a configuration file using the weblogic.Admin 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 username and password from a non-default configuration file and key file, use the userconfigfile and userkeyfile attributes with wlconfig.See STOREUSERCONFIG 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 username 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, first generate the file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG.	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 userconfigfile attribute). Before specifying the userkeyfile attribute, first generate the key file using the weblogic.Admin STOREUSERCONFIG command as described in STOREUSERCONFIG.	File	No

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.	String	No

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. See Example of Setting Multiple Attribute Values.	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.	String	No

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