Jetty Logo
Using the Ant Jetty Plugin
Prev Chapter 20. Using Ant with Jetty Next
Contact the core Jetty developers at www.webtide.com

private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery

Using the Ant Jetty Plugin

Preparing Your Project
Preparing the build.xml file
Starting Jetty via Ant
Configuring the Jetty Container
Deploying a Web Application

The Ant Jetty plugin is a part of Jetty 9 under the jetty-ant module. This plugin makes it possible to start a Jetty web server directly from the Ant build script, and to embed the Jetty web server inside your build process. Its purpose is to provide almost the same functionality as the Jetty plugin for Maven: dynamic application reloading, working directly on web application sources, and tightly integrating with the build system.

<dependency>
   <groupId>org.eclipse.jetty</groupId>
   <artifactId>jetty-ant</artifactId>
 </dependency>

Preparing Your Project

To set up your project for Ant to run Jetty, you need a Jetty distribution and the jetty-ant Jar:

  1. Download a Jetty distribution and unpack it in the local filesystem.

  2. Get the jetty-ant Jar.

  3. Make a directory in your project called jetty-lib/.

  4. Copy all of the Jars in your Jetty distribution's lib directory, and all its subdirectories, into your new jetty-lib dir. When copying the Jars, don't preserve the Jetty distribution's lib dir hierarchy – all the jars should be directly inside your jetty-lib dir.

  5. Also copy the jetty-ant Jar you downloaded earlier into the jetty-lib dir.

  6. Make a directory in your project called jetty-temp.

Now you're ready to edit or create your Ant build.xml file.

Preparing the build.xml file

Begin with an empty build.xml:

<project name="Jetty-Ant integration test" basedir=".">
</project>

Add a <taskdef> that imports all available Jetty tasks:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
     <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

  <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

</project>

Now you are ready to add a new target for running Jetty:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

  <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run />
  </target>

</project>

This is the minimal configuration you need. You can now start Jetty on the default port of 8080.

Starting Jetty via Ant

At the command line enter:

> ant jetty.run

Configuring the Jetty Container

A number of configuration options can help you set up the Jetty environment so that your web application has all the resources it needs:

ports and connectors:

To configure the port that Jetty starts on you need to define a connector. First you need to configure a <typedef> for the Connector class and then define the connector in the Jetty tags: 

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

  <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <typedef name="connector" classname="org.eclipse.jetty.ant.types.Connector"
           classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <connectors>
        <connector port="8090"/>
      </connectors>
    </jetty.run>
  </target>

</project>

Tip

You can set the port to 0, which starts the Jetty server connector on an arbitrary available port. You can then access these values from system properties jetty.ant.server.port and jetty.ant.server.host.

login services:

If your web application requires authentication and authorization services, you can configure these on the Jetty container. Here's an example of how to set up an org.eclipse.jetty.security.HashLoginService:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="hashLoginService" classname="org.eclipse.jetty.security.HashLoginService"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <loginServices>
        <hashLoginService name="Test Realm" config="/Users/jesse/docsync/jetty-documentation/realm.properties"/>
      </loginServices>
    </jetty.run>
  </target>

</project>
request log:

The requestLog option allows you to specify a request logger for the Jetty instance. You can either use the org.eclipse.jetty.server.NCSARequestLog class, or supply the name of your custom class:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run requestLog="com.acme.MyFancyRequestLog">
    </jetty.run>
  </target>

</project>
temporary directory:

You can configure a directory as a temporary file store for uses such as expanding files and compiling JSPs by supplying the tempDirectory option:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run tempDirectory="/Users/jesse/docsync/jetty-documentation/jetty-temp">
    </jetty.run>
  </target>

</project>
other context handlers:

You may need to configure some other context handlers to run at the same time as your web application. You can specify these other context handlers using the <contextHandlers> element. You need to supply a <typedef> for it before you can use it:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath"
          resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="contextHandlers" classname="org.eclipse.jetty.ant.types.ContextHandlers"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
     <contextHandlers>
       <contextHandler resourceBase="/Users/jesse/docsync/jetty-documentation/stuff" contextPath="/stuff"/>
     </contextHandlers>
    </jetty.run>
  </target>

</project>
system properties:

As a convenience, you can configure system properties by using the <systemProperties> element. Be aware that, depending on the purpose of the system property, setting it from within the Ant execution may mean that it is evaluated too late, as the JVM evaluates some system properties on entry.

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <systemProperties>
        <systemProperty name="foo" value="bar"/>
      </systemProperties>
    </jetty.run>
  </target>

</project>
jetty XML file:

If you have a lot of configuration to apply to the Jetty container, it can be more convenient to put it into a standard Jetty XML configuration file and have the Ant plugin apply it before starting Jetty:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run jettyXml="/Users/jesse/docsync/jetty-documentation/jetty.xml">
    </jetty.run>
  </target>

</project>
scanning for changes:

The most useful mode in which to run the Ant plugin is for it to continue to execute Jetty and automatically restart your web application if any part of it changes (for example, your IDE recompiles the classes of the web application). The scanIntervalSeconds option controls how frequently the <jetty.run> task scans your web application/WAR file for changes. The default value of 0 disables scanning. Here's an example where Jetty checks for changes every five seconds:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run scanIntervalSeconds="5">
    </jetty.run>
  </target>

</project>
stopping:

In normal mode (daemon="false"), the <jetty.run> task runs until you cntrl-c it. It may be useful to script both the stop AND the start of Jetty. For such a case, we provide the <jetty.stop> task.

To use it, you need to provide a port and an identifying string to both the <jetty.run> and the <jetty.stop> tasks, where <jetty.run> listens on the given port for a stop message containing the given string, and cleanly stops Jetty when it is received. The <jetty.stop> task sends this stop message. You can also optionally provide a stopWait value (in seconds), which is the length of time the <jetty.stop> task waits for confirmation that the stop succeeded:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run stopPort="9999" stopKey="9999">
    </jetty.run>
  </target>

  <target name="jetty.stop">
   <jetty.stop stopPort="9999" stopKey="9999" stopWait="10"/>
  </target>

</project>

To stop jetty via Ant, enter:

> ant jetty.stop
execution without pausing ant:

Usually, the <jetty.run> task runs until you cntrl-c it, pausing the execution of Ant as it does so. In some cases, it may be useful to let Ant continue executing. For example, to run your unit tests you may need other tasks to execute while Jetty is running. For this case, we provide the daemon option. This defaults to false. For true, Ant continues to execute after starting Jetty. If Ant exits, so does Jetty. Understand that this option does not fork a new process for Jetty.

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run daemon="true">
    </jetty.run>
  </target>

</project>

Deploying a Web Application

Add a <typedef> for the org.eclipse.jetty.ant.AntWebAppContext class with name webApp, then add a <webApp> element to <jetty.run> to describe your web application. The following example deploys a web application that is expanded in the local directory foo/ to context path / :

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/"/>
    </jetty.run>
  </target>

</project>
deploying a WAR file:

It is not necessary to expand the web application into a directory. It is fine to deploy it as a WAR file:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo.war" contextPath="/"/>
    </jetty.run>
  </target>

</project>
deploying more than one web application:

You can also deploy more than one web application:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo.war" contextPath="/"/>
      <webApp war="/Users/jesse/docsync/jetty-documentation/other    contextPath="/other"/>
      <webApp war="/Users/jesse/docsync/jetty-documentation/bar.war" contextPath="/bar"/>
    </jetty.run>
  </target>

</project>

Configuring the Web Application

As the org.eclipse.jetty.ant.AntWebAppContext class is an extension of the org.eclipse.jetty.webapp.WebAppContext class, you can configure it by adding attributes of the same name (without the set or add prefix) as the setter methods.

Here's an example that specifies the location of the web.xml file (equivalent to method AntWebAppContext.setDescriptor()) and the web application's temporary directory (equivalent to method AntWebAppContext.setTempDirectory()):

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp descriptor="/Users/jesse/docsync/jetty-documentation/web.xml" tempDirectory="/Users/jesse/docsync/jetty-documentation/my-temp" war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/"/>
    </jetty.run>
  </target>

</project>

Other extra configuration options for the AntWebAppContext include:

extra classes and Jars:

If your web application's classes and Jars do not reside inside WEB-INF of the resource base directory, you can use the <classes> and <jar> elements to tell Ant where to find them. Here's an example:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp descriptor="/Users/jesse/docsync/jetty-documentation/web.xml" tempDirectory="/Users/jesse/docsync/jetty-documentation/my-temp" war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/">
        <classes dir="/Users/jesse/docsync/jetty-documentation/classes">
          <include name="**/*.class"/>
          <include name="**/*.properties"/>
        </classes>
        <lib dir="/Users/jesse/docsync/jetty-documentation/jars">
          <include name="**/*.jar"/>
          <exclude name="**/*.dll"/>
        </lib>
      </webApp>
    </jetty.run>
  </target>

</project>
context attributes:

Jetty allows you to set up ServletContext attributes on your web application. You configure them in a context XML file that is applied to your WebAppContext instance prior to starting it. For convenience, the Ant plugin permits you to configure these directly in the build file. Here's an example:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/">
        <attributes>
          <attribute name="my.param" value="123"/>
        </attributes>
      </webApp>
    </jetty.run>
  </target>

</project>
jetty-env.xml file:

If you are using features such as JNDI with your web application, you may need to configure a WEB-INF/jetty-env.xml file to define resources. If the structure of your web application project is such that the source of jetty-env.xml file resides somewhere other than WEB-INF, you can use the jettyEnvXml attribute to tell Ant where to find it:

<project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/" jettyEnvXml="/Users/jesse/docsync/jetty-documentation/jetty-env.xml">
        <attributes>
      </webApp>
    </jetty.run>
  </target>

</project>
context XML file:

You may prefer or even require to do some advanced configuration of your web application outside of the Ant build file. In this case, you can use a standard context XML configuration file which the Ant plugin applies to your web application before it is deployed. Be aware that the settings from the context XML file override those of the attributes and nested elements you defined in the build file.

project name="Jetty-Ant integration test" basedir=".">

  <path id="jetty.plugin.classpath">
    <fileset dir="jetty-lib" includes="*.jar"/>
  </path>

 <taskdef classpathref="jetty.plugin.classpath" resource="tasks.properties" loaderref="jetty.loader" />

 <typedef name="webApp" classname="org.eclipse.jetty.ant.AntWebAppContext"
          classpathref="jetty.plugin.classpath" loaderref="jetty.loader" />

  <target name="jetty.run">
    <jetty.run>
      <webApp war="/Users/jesse/docsync/jetty-documentation/foo" contextPath="/" contextXml="/Users/jesse/docsync/jetty-documentation/jetty-env.xml">
        <attributes>
      </webApp>
    </jetty.run>
  </target>

</project>
Prev Up Next
Chapter 20. Using Ant with Jetty Home Chapter 21. Jetty Runner

See an error or something missing? Contribute to this documentation at Github!