Version: 9.2.11-SNAPSHOT
Version: 9.2.11-SNAPSHOT |
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
Table of Contents
The start.jar bootstrap manages the startup of standalone Jetty. It is responsible for:
The start.jar bootstrap builds a classpath for all the
required Jetty features and their dependencies. It builds the classpath using either the --lib option to start.jar to add an individual
classpath entry, or with the --module option that
includes all the libs and their dependencies for a module (a named
Jetty feature).
The server and its components are instantiated using either
Jetty IoC XML or spring. The Jetty server is just a collection of java
POJOs for the server, connectors, session managers and others. These are
instantiated, injected, and wired up together in XML files, commonly
one per module/feature, that are passed as arguments to
start.jar.
The start.jar mechanism resolves
canonical locations for the ${jetty.home} and the
${jetty.base} directories.
The ${jetty.home} directory is the location of the standard
distribution of Jetty.
The ${jetty.base} directory is the location of the local server
customization and configurations.
If you want to modify the Jetty distribution, base and home can be the same directory. Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the the home directory, and thus simplifies subsequent server version upgrades.
XML files primarily determine the server configuration. Many of these files are parameterized to allow simple
injection of host names, ports, passwords and more. The
start.jar mechanism allows you to set parameters
on the command line or in properties files.
To achieve these start up mechanisms, the start.jar
uses:
You can configure the entire server with command line arguments that specify libraries, properties and XML files. However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
The
start.jar mechanism uses the contents of the ${jetty.base}/start.ini
and ${jetty.base}/start.d/*.ini files with each line equivalent to a start.jar command line
argument. This means that either a global start.ini file or multiple start.d/feature.ini files control the configuration of the server.
Instead of explicitly listing all the libraries, properties and
XML files for a feature, the start.jar mechanism
allows you to create modules. You define a module in a
modules/*.mod file, including the libraries,
dependencies, XML, and template INI files for a Jetty feature. Thus you can use a
single --module=name command line option as the equivalent of specifying many
--lib=location, feature.xml, name=value arguments
for a feature and all its dependencies. Modules also use their
dependencies to control the ordering of libraries and XML
files.
XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server. This includes all major components such as connectors, keystores, session managers, and data sources. Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.
The simplest way to start Jetty is via the
start.jar mechanism using the following Java command
line:
[user]$ cd jetty-distribution-9.2.11-SNAPSHOT [jetty-distribution-9.2.11-SNAPSHOT]$ java -jar start.jar --module=http jetty.port=8080
This command uses the start.jar mechanism to
bootstrap the classpath, properties, and XML files with the metadata
obtained from the http module. Specifically the
http module is defined in the
${jetty.home}/modules/http.mod file, and includes the
following:
[jetty-distribution-9.2.11-SNAPSHOT]$ cat modules/http.mod [depend] server [xml] etc/jetty-http.xml [ini-template] jetty.port=8080 http.timeout=30000
The http module declares that
http depends on the server module, uses the
jetty-http.xml file, and can be parameterized with
jetty.port and http.timeout
parameters. The INI-template section is not actually used by the command
above, so the jetty.port must still be defined on the
command line.
Following the server dependency, the
${jetty.home}/modules/server.mod file
includes:
[jetty-distribution-9.2.11-SNAPSHOT]$ cat modules/server.mod
[lib]
lib/servlet-api-3.1.jar
lib/jetty-http-${jetty.version}.jar
lib/jetty-server-${jetty.version}.jar
lib/jetty-xml-${jetty.version}.jar
lib/jetty-util-${jetty.version}.jar
lib/jetty-io-${jetty.version}.jar
[xml]
etc/jetty.xml
[ini-template]
threads.min=10
threads.max=200
The server module declares the libraries the server needs
and t0 use jetty.xml file.
The combined metadata of the http and
server modules results in
start.jar generating the effective Java command line
required to start Jetty.
Another way to see this is by asking Jetty what its configuration looks like:
[jetty-distribution-9.2.11-SNAPSHOT]$ java -jar start.jar --module=http jetty.port=9099 --list-config
Java Environment:
-----------------
java.home=/user/lib/jvm/jdk-7u21-x64/jre
java.vm.vendor=Oracle Corporation
java.vm.version=23.25-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_25-b15
java.io.tmpdir=/tmp
Jetty Environment:
-----------------
jetty.home=/opt/jetty/jetty-distribution-9.2.11-SNAPSHOT
jetty.base=/opt/jetty/jetty-distribution-9.2.11-SNAPSHOT
jetty.version=9.2.11-SNAPSHOT
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
jetty.home = /opt/jetty/jetty-distribution-9.2.11-SNAPSHOT
jetty.base = /opt/jetty/jetty-distribution-9.2.11-SNAPSHOT
Properties:
-----------
jetty.port = 9099
Jetty Server Classpath:
-----------------------
Version Information on 7 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.2.11-SNAPSHOT | ${jetty.home}/lib/jetty-http-9.2.11-SNAPSHOT.jar
3: 9.2.11-SNAPSHOT | ${jetty.home}/lib/jetty-server-9.2.11-SNAPSHOT.jar
4: 9.2.11-SNAPSHOT | ${jetty.home}/lib/jetty-xml-9.2.11-SNAPSHOT.jar
5: 9.2.11-SNAPSHOT | ${jetty.home}/lib/jetty-util-9.2.11-SNAPSHOT.jar
6: 9.2.11-SNAPSHOT | ${jetty.home}/lib/jetty-io-9.2.11-SNAPSHOT.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml
This represents the entirety of the configuration that is applied to start Jetty.
If you don't want to use the start.jar
bootstrap, you can start Jetty using a traditional Java command
line.
The following is the equivalent java command
line for what the start.jar bootstrap above
performs.
[user]$ cd jetty-distribution-9.2.11-SNAPSHOT
[jetty-distribution-9.2.11-SNAPSHOT]$ echo jetty.port=8080 > /tmp/jetty.properties
[jetty-distribution-9.2.11-SNAPSHOT]$ export JETTY_HOME=`pwd`
[jetty-distribution-9.2.11-SNAPSHOT]$ export JETTY_BASE=`pwd`
[jetty-distribution-9.2.11-SNAPSHOT]$ export JETTY_VERSION="${project.version}"
[jetty-distribution-9.2.11-SNAPSHOT]$ java -Djetty.home=$JETTY_HOME \
-Djetty.base=$JETTY_BASE \
-cp \
$JETTY_HOME/lib/servlet-api-3.1.jar\
:$JETTY_HOME/lib/jetty-schemas-3.1.jar\
:$JETTY_HOME/lib/jetty-http-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-server-$JETTY_VERSION.jar \
:$JETTY_HOME/lib/jetty-xml-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-io-$JETTY_VERSION.jar\
org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml
The java command line sets up the classpath with the core Jetty jars and
the servlet API, executes the XmlConfiguration class, and passes it some
XML files that define the server and an HTTP connector running on the port
defined in the jetty.properties file.
You can further simplify the startup of this server by using the
INI template defined by the modules to create a
start.ini file with the command:
[user]$ cd jetty-distribution-9.2.11-SNAPSHOT
[jetty-distribution-9.2.11-SNAPSHOT]$ mkdir example-base
[example-base]$ cd example-base
[example-base]$ ls -la
total 8
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
[example-base]$ java -jar ../start.jar --add-to-start=http
WARNING: http initialised in ${jetty.base}/start.ini (appended)
WARNING: http enabled in ${jetty.base}/start.ini
WARNING: server initialised in ${jetty.base}/start.ini (appended)
WARNING: server enabled in ${jetty.base}/start.ini
[example-base]$ ls -la
total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
Once complete, you can edit the start.ini file to modify any
parameters and you can run the server with the simple command:
[example-base]$ java -jar ../start.jar