Version: 9.4.5.v20170502 |
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 for sponsored feature development
Table of Contents
The start.jar
bootstrap manages the startup of standalone Jetty.
It is responsible for:
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).start.jar
.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 base directory, and thus simplifies subsequent server version upgrades.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:
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.It is important to chose either ${jetty.base}/start.ini
or ${jetty.base}/start.d/*.ini
to manage configuration.
Using both is not recommended and can lead to issues with your server.
start.jar
mechanism allows you to create modules.
A module is defined 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 --lib=location
, feature.xml
or name=value
arguments for a feature and all its dependencies.
Modules also use their dependencies to control the ordering of libraries and XML files.
There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations…etc.
These module files should only be edited if you are making structural changes to the way the feature will perform.
For more information, refer to the section on managing startup modules later in this chapter.The simplest way to start Jetty is via the start.jar
mechanism using the following Java command line:
[user]$ cd jetty-distribution-9.4.5.v20170502 [jetty-distribution-9.4.5.v20170502]$ java -jar start.jar --module=http jetty.http.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.4.5.v20170502]$ cat modules/http.mod [depend] server [xml] etc/jetty-http.xml [ini-template] jetty.http.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.http.port
and http.timeout
parameters.
The INI-template section is not actually used by the command above, so the jetty.http.port
must still be defined on the command line.
Following the server dependency, the ${jetty.home}/modules/server.mod
file includes:
[jetty-distribution-9.4.5.v20170502]$ 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 to 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 by appending --list-config to the command line:
[jetty-distribution-9.4.5.v20170502]$ java -jar start.jar --module=http jetty.http.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.4.5.v20170502 jetty.base=/opt/jetty/jetty-distribution-9.4.5.v20170502 jetty.version=9.4.5.v20170502 JVM Arguments: -------------- (no jvm args specified) System Properties: ------------------ jetty.home = /opt/jetty/jetty-distribution-9.4.5.v20170502 jetty.base = /opt/jetty/jetty-distribution-9.4.5.v20170502 Properties: ----------- jetty.http.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.4.5.v20170502 | ${jetty.home}/lib/jetty-http-9.4.5.v20170502.jar 3: 9.4.5.v20170502 | ${jetty.home}/lib/jetty-server-9.4.5.v20170502.jar 4: 9.4.5.v20170502 | ${jetty.home}/lib/jetty-xml-9.4.5.v20170502.jar 5: 9.4.5.v20170502 | ${jetty.home}/lib/jetty-util-9.4.5.v20170502.jar 6: 9.4.5.v20170502 | ${jetty.home}/lib/jetty-io-9.4.5.v20170502.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.4.5.v20170502 [jetty-distribution-9.4.5.v20170502]$ echo jetty.http.port=8080 > /tmp/jetty.properties [jetty-distribution-9.4.5.v20170502]$ export JETTY_HOME=`pwd` [jetty-distribution-9.4.5.v20170502]$ export JETTY_BASE=`pwd` [jetty-distribution-9.4.5.v20170502]$ export JETTY_VERSION="${project.version}" [jetty-distribution-9.4.5.v20170502]$ 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.4.5.v20170502 [jetty-distribution-9.4.5.v20170502]$ 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 $JETTY_HOME/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 $JETTY_HOME/start.jar