Jetty Plugin (quokka.plugin.jetty:0.1, namespace=jetty)

The Jetty Plugin runs one or more Jetty server instances and can be used to run a web application directly from sources and compilation output.

Main Targets

run Runs Jetty directly from your webapp sources and compilation output

Minor Targets

run-exploded Runs Jetty from an exploded webapp directory
run-war Runs Jetty with a given .war file
stop Stops the Jetty server instance

Template Targets

run-template Template for running jetty directly from your webapp sources and compilation output
run-exploded-template Template for running Jetty from an exploded webapp directory
run-war-template Template for running Jetty with a given .war file
stop-template Template for stopping a Jetty server instance

In order to run Jetty on a webapp project which is structured according to the usual Quokka defaults you don't need to configure anything. Simply type:

$ quokka jetty:run

This will start Jetty running on port 8080, serving your project under the context name of your project name. Jetty will continue to run until the plugin is explicitly stopped, for example, by a <CTRL>+C. (You can also use the stop target).

It is extremely convenient to leave the plugin running because it can be configured to periodically scan for changes and automatically redeploy the webapp. This makes the development cycle much more productive by eliminating the build and deploy steps: you use your IDE to make changes to the project and the running web container will automatically pick them up, allowing you to test them straight away.

If, for whatever reason, you cannot run on an unassembled webapp, the plugin also supports the run-war and run-exploded targets which are discussed below.

Controlling Dependencies

By default the plugin only includes the minimal dependencies for Jetty, allowing you run servlets. If you are using JSP, or Jetty Plus functionality you need to add them as options. e.g. to use JSP 2.1 you would use:

<plugin group="quokka.plugin.jetty" version="?" paths="(jsp-2.1)"/>

Available options are: jsp-2.0, jsp-2.1, plus, naming, annotations, management. The JSP options are mutually exclusive and add JSP 2.0 and 2.1 support respectively. For more information on the other options, see the Jetty documentation.

Automatic execution of the plugin

Sometimes, for example when doing integration testing, you'd like to be able to automatically have your webapp started at the beginning of the tests, and stopped at the end rather than manually executing quokka jetty:run on the command line.

To do this, you need to set up a couple of <targets> for the jetty plugin and set the daemon property to true to prevent jetty running indefinitely and force it to only execute while quokka is running.

You can bind run and stop targets to the lifecycle initialise-integration-test and finalise-integration-test targets like so:

<property name="q.jetty.defaults.stopKey" value="foo"/>
<property name="q.jetty.defaults.stopPort" value="9999"/>

<plugin group="quokka.plugin.jetty" version="?">
    <target name="start-jetty" template="run-template"
            dependency-of="lifecycle:initialise-integration-test"
                  depends="lifecycle:pre-initialise-integration-test">
        <property name="daemon" value="true"/>
        <property name="scanIntervalSeconds" value="0"/>
    </target>
    <target name="stop-jetty" template="stop-template"
        dependency-of="lifecycle:finalise-integration-test"
              depends="lifecycle:pre-finalise-integration-test"/>
</plugin>

Note: The above example creates new target instances from the templates. Alternatively, you could configure the existing run and stop targets.

Forcing compilation prior to running

By default, the Jetty run targets have no dependencies on other targets. If you prefer compilation to always occur prior to running, use the following configuration:

<plugin group="quokka.plugin.jetty" version="?">
    <target name="run" depends="compile"/>
</plugin>

How to stop the plugin from the command line

The run, run-war and run-exploded goals leave the plugin running indefinitely. You can terminate it with a <CTRL>+C in the controlling terminal window, or by executing the stop goal in another terminal window. If you wish to be able to use quokka jetty:stop then you need to configure the plugin with a special port number and key that you also supply on the stop command:

Here's an example configuration:

<property name="q.jetty.defaults.stopKey" value="foo"/>
<property name="q.jetty.defaults.stopPort" value="9999"/>

<plugin group="quokka.plugin.jetty" version="?">

To start:

quokka jetty:run

To stop:

quokka jetty:stop

Properties common to run, run-war and run-exploded goals

The properties are divided into those that apply to the container as a whole, and those that apply specifically to the webapp:

Container Configuration

  • jettyConfig Optional. The location of a jetty.xml file that will be applied in addition to any plugin configuration parameters. You might use it if you have other webapps, handlers, etc to be deployed, or you have other jetty objects that cannot be configured from the plugin, such as connectors and security realms.
  • scanIntervalSeconds Optional. The pause in seconds between sweeps of the webapp to check for changes and automatically hot redeploy if any are detected. By default this is 0, which disables hot deployment scanning. A number greater than 0 enables it.
  • scanTargets Optional. A map of resource collections that will be scanned for changes and force the reloading of the webapp if reloading is set to automatic. Note: these are in addition to the standard classes and configuration files.
  • sysProp Optional. A map of system properties. These allow you to configure System properties that will be set for the execution of the plugin. Existing system properties will not be overwritten.
  • port Optional. The port the server will bind to. Defaults to 8080.
  • maxIdle Optional. The maximum idle time. Defaults to 30000.
  • stopPort Optional. The port to listen on for stop requests. Must be set together with the stop key to function.
  • stopKey Optional. The key the must be set for a stop command to succeed - it is essentially a password to prevent malicious shut downs of the server
  • reload Optional. Either manual or auto. If manual (the default), the server will reload when the enter key is pressed. If auto (and scanIntervalSeconds > 0 and daemon is false), the plugin will scan for changes to the web app classes and configuration files and automatically reload the webapp.
  • daemon Optional. Either true or false. If false (the default), the server will prevent quokka from exiting. Otherwise, it will simply start the server and continue. This is useful is some cases such as starting and stopping the server automatically for integration tests.
  • extraPaths Optional. Allows additional of extra paths to the plugin class loader. This is intended to allow users to add additional slf4j logging implementations if they desire. The value should be a comma separated list of project paths prefixed with "project.". For example, if you defined a project path logging for the additional libraries, extraPaths should be set to project.logging.

Webapp Configuration

  • contextPath Optional. The context path for your webapp. By default, this is set to the project's war aritifact's name. You can override it and set it to anything you like here.
  • tempDirectory Optional. The temporary directory to use for the webapp. This is set to {${basedir}/target} by default but can be changed here.
  • overrideDescriptor Optional. A web.xml file which will be applied AFTER the webapp's web.xml. This file can be stored anywhere. It is used to add or modify the configuration of a web.xml for different environments eg test, production etc.
  • defaultsDescriptor Optional. A webdefault.xml file to use instead of the supplied jetty default for the webapp.
  • includeInstrumentedOuput Optional. If true, instrumented classes will be added to the classpath if instrumentation is enabled so that code coverage data can be collected for the web application. Defaults to false.

Shared Default Properties

q.jetty.defaults.contextPath ${q.project.artifact.name[war]}
q.jetty.defaults.tempDirectory ${q.project.targetDir}/temp/jetty
q.jetty.defaults.scanIntervalSeconds 0
q.jetty.defaults.daemon false
q.jetty.defaults.reload manual
q.jetty.defaults.sysProp[net.sourceforge.cobertura.datafile] ${@setifdef q.cobertura.instrument.dataFile}

run

Runs Jetty directly from your webapp sources and compilation output

  • depends: lifecycle:compile
  • prefix: q.jetty.run
  • template-name: run-template

Note: this target depends on lifecycle:compile. If you do not want this as a dependency, create a new instance of the run-template instead.

See run-template for configuration options


run-exploded

Runs Jetty from an exploded webapp directory

  • depends: jee:war-exploded
  • prefix: q.jetty.runExploded
  • template-name: run-exploded-template

Note: this target depends on jee:war-exploded. If you do not want this as a dependency, create a new instance of the run-exploded-template instead.

See run-exploded-template for configuration options

Default Properties

webApp ${@setifdef q.jee.warExploded.output}

run-war

Runs Jetty with a given .war file

  • depends: jee:war
  • prefix: q.jetty.runWar

Note: this target depends on jee:war. If you do not want this as a dependency, create a new instance of the run-war-template instead.

See run-war-template for configuration options

Default Properties

webApp ${@q.lifecycle.packageOutput + '/' + q.project.artifact.group + '_' + q.project.artifact.name[war] + '_war' + '_' + q.project.artifact.version + '.war'}

stop

Stops the Jetty server instance

  • prefix: q.jetty.stop
  • template-name: stop-template

See stop-template for configuration options


run-template

Template for running jetty directly from your webapp sources and compilation output

  • template: true

Properties:

  • includeTestCompileOutput Optional. If true, the test classes will be added to the class path
  • libPath Optional. The id of the path that contains dependencies for your web app (that will reside in lib)
  • webApp Optional. The location of the web application sources.
  • webXml Optional. The location of the web.xml file.
  • jettyEnvXml Optional. it is the location of a jetty-env.xml file, which allows you to make JNDI bindings that will satisfy <env-entry>, <resource-env-ref> and <resource-ref> linkages in the web.xml that are scoped only to the webapp and not shared with other webapps that you may be deploying at the same time (e.g. by using a jettyConfig file).

Default Properties

* q.jetty.defaults
includeTestCompileOutput false
libPath war
webApp ${q.project.sourceDir}/main/webapp
webXml ${prefix.webApp}/WEB-INF/web.xml

run-exploded-template

Template for running Jetty from an exploded webapp directory

  • template: true

Properties:

  • webApp The location of the exploded war.

Default Properties

* q.jetty.defaults

run-war-template

Template for running Jetty with a given .war file

  • template: true

Properties:

  • webApp The location of the built war file.

Default Properties

* q.jetty.defaults

stop-template

Template for stopping a Jetty server instance

  • template: true

Default Properties

* q.jetty.defaults

Plugin Paths

runtime : Runtime class path

mortbay.jetty util 6.1.11

quokka.core.plugin-spi plugin-spi 0.3

quokka.core.util util 0.3

quokka.plugin.lifecycle lifecycle 0.3

quokka.core.plugin-spi plugin-spi 0.3

apache.ant ant 1.7.1

quokka.core.bootstrap-util bootstrap-util 0.3

apache.ant ant 1.7.1

mortbay.jetty jetty 6.1.11

mortbay.jetty util 6.1.11

sun.servlet.spec.dist dist 2.5


runtime: Optional dependencies

mortbay.jetty annotations 6.1.11

mortbay.jetty jsp-2.0 6.1.11

mortbay.jetty jsp-2.1 6.1.11

mortbay.jetty management 6.1.11

mortbay.jetty naming 6.1.11

mortbay.jetty plus 6.1.11