Jetty Logo
Version: 9.1.3-SNAPSHOT
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

Managing Startup Modules

Enabling Modules

Starting with Jetty 9.1, a new Module system was introduced. (It replaced the old start.config + OPTIONS techniques from past Jetty Distributions).

The standard Jetty Distribution ships with several modules defined in ${jetty.home}/modules/

What a Jetty Startup Module Defines:

A Module Name

The name of the module is the keyword used by the --module=<name> command line argument to activate/enable modules, and also find dependant modules.

The filename of the module defines its name. (eg: server.mod becomes the module named "server")

List of Dependant Modules

All modules can declare that they depend on other modules with the [depend] section.

The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.

The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.

Of note: there is a special section [optional] used to describe structurally dependant modules that are not technically required, but might be of use to your specific configuration.

List of Libraries

Module can optionally declare that they have libraries that they need to function properly.

The [lib] section declares a set of pathnames that follow the Jetty Base and Jetty Home path resolution rules.

List of Jetty IoC XML Configurations

A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines.

The [xml] section declares a set of pathnames that follow the Jetty Base and Jetty Home path resolution rules.

Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration. Allowing for a simplified configuration of Jetty for the vast majority of deployments.

The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the [depend] sections.

If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the ${jetty.base}/etc/ directory, with the same name. The resolution steps for Jetty Base and Jetty Home will ensure that your copy from ${jetty.base} will be picked up over the default one in ${jetty.home}.

Jetty INI Template

Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the start.ini or start.d/*.ini files when using the --add-to-start=<name> or --add-to-startd=<name> command line arguments in start.jar.

Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.

The [ini-template] section declares this section of sample configuration.

Required Files and Directories

If the activation of a module requires some paths to exist, the [files] section defines them.

There are 2 modes of operation of the entries in this section.

Ensure Directory Exists

If you add a pathname that ends in "/" (slash), such as "webapps/", then that directory will be created if it does not yet exist in ${jetty.base}/<pathname> (eg: "webapps/" will result in ${jetty.base}/webapps/ being created)

Download File

There is a special syntax to allow you to download a file into a specific location if it doesn't exist yet.

<url>:<pathname>

Currently, the <url> must be a http:// scheme URL (file a bug if you want more schemes supported). The <pathname> portion follows the Jetty Base and Jetty Home path resolution rules.

Example:

http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar

This will check for the existence of lib/corp-security-policy.jar, and if it doesn't exist, it will download the jar file from http://repo.corp.com/maven/corp-security-policy-1.0.jar

Enabling Modules

Jetty ships with many modules defined, and a small subset predefined in the start.ini found in the jetty distribution.

Tip

The default distribution has a commingled ${jetty.home} and ${jetty.base}. Where the directories for ${jetty.home} and ${jetty.base} point to the same location.

It is highly encouraged that you learn about the differences in Jetty Base vs Jetty Home and take full advantage of this setup.

When you want enable a module, you can use the --module=<name> syntax on the command line (or start.ini) to enable it + all of its dependant modules.

An example of this, with a new, empty, base directory.

[/home/user]$ mkdir my-base
[/home/user]$ cd my-base
[my-base]$ java -jar ../jetty-distribution/start.jar
WARNING: Nothing to start, exiting ...

Usage: java -jar start.jar [options] [properties] [configs]
       java -jar start.jar --help  # for more information
[my-base]$ java -jar ../jetty-distribution/start.jar --list-config

Java Environment:
-----------------
 java.home=/home/joakim/java/jdk-7u21-x64/jre
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.21-b01
 java.vm.name=Java HotSpot(TM) 64-Bit Server VM
 java.vm.info=mixed mode
 java.runtime.name=Java(TM) SE Runtime Environment
 java.runtime.version=1.7.0_21-b11
 java.io.tmpdir=/tmp

Jetty Environment:
-----------------
 jetty.home=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO
 jetty.base=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.version=9.1.0-DEMO

JVM Arguments:
--------------
 (no jvm args specified)

System Properties:
------------------
 jetty.base = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.home = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO

Properties:
-----------
 (no properties specified)

Jetty Server Classpath:
-----------------------
No classpath entries and/or version information available show.

Jetty Active XMLs:
------------------
 (no xml files specified)

Can't start, as there is no configuration, yet. Lets use a simple one that will start up support for webapps and hot deployment.

[my-base]$ java -jar ../jetty-distribution/start.jar --module=webapp,deploy
2013-10-16 13:30:45.636:INFO:oejs.Server:main: jetty-9.1.0-DEMO
2013-10-16 13:30:45.656:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps] at interval 1
[Ctrl+C]
[my-base]$ java -jar ../jetty-distribution/start.jar --module=webapp,deploy --list-config
Java Environment:
-----------------
 java.home=/home/joakim/java/jdk-7u21-x64/jre
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.21-b01
 java.vm.name=Java HotSpot(TM) 64-Bit Server VM
 java.vm.info=mixed mode
 java.runtime.name=Java(TM) SE Runtime Environment
 java.runtime.version=1.7.0_21-b11
 java.io.tmpdir=/tmp

Jetty Environment:
-----------------
 jetty.home=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO
 jetty.base=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.version=9.1.0-DEMO

JVM Arguments:
--------------
 (no jvm args specified)

System Properties:
------------------
 jetty.base = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.home = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO

Properties:
-----------
 (no properties specified)

Jetty Server Classpath:
-----------------------
Version Information on 11 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
      changes to the --module=name command line options will be reflected here.
 0:                    3.1.0 | ${jetty.home}/lib/servlet-api-3.1.jar
 1:                  3.1.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
 2:               9.1.0-DEMO | ${jetty.home}/lib/jetty-http-9.1.0-DEMO.jar
 3:               9.1.0-DEMO | ${jetty.home}/lib/jetty-continuation-9.1.0-DEMO.jar
 4:               9.1.0-DEMO | ${jetty.home}/lib/jetty-server-9.1.0-DEMO.jar
 5:               9.1.0-DEMO | ${jetty.home}/lib/jetty-xml-9.1.0-DEMO.jar
 6:               9.1.0-DEMO | ${jetty.home}/lib/jetty-util-9.1.0-DEMO.jar
 7:               9.1.0-DEMO | ${jetty.home}/lib/jetty-io-9.1.0-DEMO.jar
 8:               9.1.0-DEMO | ${jetty.home}/lib/jetty-servlet-9.1.0-DEMO.jar
 9:               9.1.0-DEMO | ${jetty.home}/lib/jetty-webapp-9.1.0-DEMO.jar
10:               9.1.0-DEMO | ${jetty.home}/lib/jetty-deploy-9.1.0-DEMO.jar

Jetty Active XMLs:
------------------
 ${jetty.home}/etc/jetty.xml
 ${jetty.home}/etc/jetty-deploy.xml

From here, we can see that the Jetty now starts up with basic WebApp support and automatic deployment.

Just create a my-base/webapps/ directory and toss in a simple war file and you now have a functional server.

To see what modules are active, you can use the --list-modules command line argument.

[my-base]$ java -jar ../jetty-distribution/start.jar --module=webapp,deploy --list-modules
...(snip)...
Jetty Active Module Tree:
-------------------------
 + Module: server [transitive]
   + Module: servlet [transitive]
     + Module: webapp [enabled]
       + Module: deploy [enabled]

We declared webapp and deploy modules on the command line with the servlet and server modules being brought into the active module tree transitively.

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-04-15T11:43:40-05:00)