Developing Applications with WebLogic Server

Using Ant Tasks to Configure and Use 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 that you can include in your development build scripts:

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:

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.

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.

Basic Steps for Using wlserver

To use the wlserver Ant 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.

Configuring a WebLogic Server Domain Using the wlconfig Ant Task

The following sections describe how to use the wlconfig Ant task to configure a WebLogic Server domain.

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

Sample build.xml Files for wlconfig

The following sections provide sample Ant build scripts for using the wlconfig Ant task.

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

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.

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.

delete

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

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:

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.

query

The query elements finds MBean that match a search pattern.

The query element supports the following nested child elements:

wlconfig can have any number of nested query elements.

query has the following attributes:

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.

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.

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.

library

The following attribute is required when using this element:

   file—Register this file as an available library.

Example libclasspath Ant Task

This section provides example code of a libclasspath Ant task:

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

   .
   .
   .