e-docs > WebLogic Server > Administration Guide > Using Ant Tasks to Configure a WebLogic Server Domain |
Administration Guide |
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
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.
Notes: The WebLogic Server Ant tasks are incompatible with Ant versions prior to 1.5. Also, if you use a version of Ant that is not included with WebLogic Server, you must specify the appropriate task definition in your build.xml file, as described in the sections that follow.
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:
The sections that follow describe how to use the configuration Ant tasks, wlserver and wlconfig. For more information about the wldeploy task, see wldeploy Ant Task in Developing WebLogic Server Applications.
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 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.
prompt> ant
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>
The following table describes the attributes of the wlserver Ant task.
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:
Basic Steps for Using wlconfig
<target name="doconfig">
<wlconfig url="t3://localhost:7001" username="weblogic"
password="weblogic">
</target>
prompt> ant doconfig
Sample build.xml Files for wlconfig
This example shows a single build.xml file that creates a new domain using wlserver and performs various domain configuration tasks with wlconfig.
The script starts by creating the new domain:
<target name="sample.config">
mkdir dir="config"/>
<wlserver username="a" password="a" servername="SampleServer"
domainname="sample" 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 ${sampleserver} Ant property:
<query domain="sample" type="Server" name="SampleServer"
property="sampleserver"/>
The script the uses a create element to create a new JDBC connection pool in the domain, storing the object name in the ${samplepool} 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 ${sampleserver} Ant property set in the query above:
<create type="JDBCConnectionPool" name="SamplePool"
property="samplepool">
<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="samplename"/>
<set attribute="Properties" value="user=samplepwd"/>
<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="${sampleserver}"/>
</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="SampleTxDataSource"/>
<set attribute="PoolName" value="SamplePool"/>
<set attribute="Targets" value="${sampleserver}"/>
</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="${sampleserver}"/>
</create>
A new JMS JDBC store is created using the SamplePool:
<create type="JMSJDBCStore" name="SampleJDBCStore"
property="samplejdbcstore">
<set attribute="ConnectionPool" value="${samplepool}"/>
<set attribute="PrefixName" value="Sample"/>
</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="SampleJMSServer">
<set attribute="Store" value="${samplejdbcstore}"/>
<set attribute="Targets" value="${sampleserver}"/>
<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/SampleMailSession"/>
<set attribute="Properties"
value="mail.user=joe;mail.host=mail.mycompany.com"/>
<set attribute="Targets" value="${sampleserver}"/>
</create>
<create type="StartupClass" name="StartBrowser">
<set attribute="Arguments" value="port=${listenport}"/>
<set attribute="ClassName"
value="com.bea.sample.startup.StartBrowser"/>
<set attribute="FailureIsFatal" value="false"/>
<set attribute="Notes" value="Automatically starts a browser on server boot."/>
<set attribute="Targets" value="${sampleserver}"/>
</create>
Finally, the script obtains the WebServer MBean and sets the log filename using a nested set element:
<query domain="sample" type="WebServer" name="SampleServer">
<set attribute="LogFileName" value="logs/access.log"/>
</query>
</wlconfig>
</target>
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>
Note: Separate multiple values with a comma (,) not a semi-colon (;) .
The following table describes the main attributes of the wlconfig Ant task.
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.
The name of an optional Ant property that holds the object name of the newly-created MBean. |
The delete element removes an existing MBean from the WebLogic Server domain. delete takes a single attribute:
Required when the delete element is a direct child of the wlconfig task. Not required when nested within a query element. |
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:
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 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. |
Required only when the set element is a direct child of the wlconfig task. |
||
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. |
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.
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: