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
For information about restrictions for creating and using domains, see Domain Restrictions in Configuring and Managing WebLogic Server.
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
-
On Windows NT, execute the
setWLSEnv.cmd
command, located in the directoryWL_HOME/server/bin
, whereWL_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
, whereWL_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"/>
- 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 aboutwlserver
attributes and default behavior.
prompt> ant
- Add a call to the
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.
Table 5-1 Attributes of the wlserver Ant Task
The path to the security policy file for the WebLogic Server domain. This attribute is used only for starting server instances. | |||
The path that holds the domain configuration (for example, | |||
The path to the WebLogic Server installation directory (for example, | |||
The name of the WebLogic Server domain in which the server is configured. | |||
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. | |||
The username of an administrator account. If you omit both the | |||
The password of an administrator account. If you omit both the | |||
The private key password for decrypting the SSL private key file. | |||
The maximum time, in seconds, that | |||
Specifies whether a server instance boots in development mode or in production mode. | |||
The DNS name or IP address on which the server instance is listening. | |||
The TCP port number on which the server instance is listening. | |||
Specifies whether or not | |||
Specifies the action The | |||
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. | |||
This optional attribute is used in conjunction with the
|
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: 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"/>
<target name="doconfig">
<wlconfig url="t3://localhost:7001" username="weblogic"
password="weblogic">
</target>
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.
Table 5-2 Main Attributes of the wlconfig Ant Task
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 STOREUSERCONFIG for more information on storing and encrypting passwords. | |||
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. | |||
Specifies the location of a user configuration file to use for obtaining the administrative username and password. Use this option, instead of the | |||
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 |
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 5-3 Attributes of the create Element
delete
The delete
element removes an existing MBean from the WebLogic Server domain. delete
takes a single attribute:
Table 5-4 Attribute of the delete Element
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 5-5 Attributes of the set Element
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. | |||
The object name of the MBean whose values are being set. This attribute is required only when the | Required only when the | ||
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 |
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 5-6 Attributes of the get Element
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:
Table 5-7 Attributes of the query Element