The Jetty classes are organized into almost fifty JARs, so it is crucial to understand the organization and dependencies (internal or external) when creating classpaths for Jetty.
When working out dependencies, the Maven dependency:tree plugin is your friend. For example, to find out the dependencies of the jetty-servlet module:
# mvn -f jetty-servlet/pom.xml dependency:tree [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'dependency'. [INFO] ------------------------------------------------------------------------ [INFO] Building Jetty :: Servlet Handling [INFO] task-segment: [dependency:tree] [INFO] ------------------------------------------------------------------------ [INFO] [dependency:tree] [INFO] org.eclipse.jetty:jetty-servlet:jar:7.0.0.RC2-SNAPSHOT [INFO] +- junit:junit:jar:3.8.2:test [INFO] \- org.eclipse.jetty:jetty-security:jar:7.0.0.RC2-SNAPSHOT:compile [INFO] \- org.eclipse.jetty:jetty-server:jar:7.0.0.RC2-SNAPSHOT:compile [INFO] +- javax.servlet:servlet-api:jar:2.5:compile [INFO] +- org.eclipse.jetty:jetty-continuation:jar:7.0.0.RC2-SNAPSHOT:compile [INFO] \- org.eclipse.jetty:jetty-http:jar:7.0.0.RC2-SNAPSHOT:compile [INFO] \- org.eclipse.jetty:jetty-io:jar:7.0.0.RC2-SNAPSHOT:compile [INFO] \- org.eclipse.jetty:jetty-util:jar:7.0.0.RC2-SNAPSHOT:compile
Types of Dependencies
Jetty uses three types of Maven dependencies:
- Real, hard dependencies that you need to compile and run the code. In the example above, you can see that jetty-servlet has a single hard dependency on jetty-security, which has transitive dependencies on jetty-server, servlet-api, jetty-continuation, jetty-http, jetty-io, jetty-util.
- (Optional) Used for optional dependencies needed to compile the code, but are not necessary at runtime. For example jetty-util provide-depends on org.slf4j:slf4j-api so that it can compile the Slf4jLog. However, slf4j is optional at runtime, so that if the dependency is not on the classpath, then the Slf4J logger is not used.
- (Environmental) Also used for dependencies that are expected to be present in a runtime environment. For example the test-jetty-webapp provide-depends on the servlet-api so that it can be compiled against the API, but the servlet container is expected to provide the servlet API, so the servlet-api JAR is not included in the WEB-INF/lib of the assembled WAR file.
- Used for unit tests (note that some integration tests are in modules with test-foo names, and use normal compile dependencies to access common test resources).
This diagram shows the compile dependencies for the Jetty project. The external dependencies are listed on the right hand side and all other modules shown are part of the project. The dependencies are best understood in the following groups:
The jetty-util, jetty-io and jetty-http jars form the core of the jetty HTTP handler (generation and parsing) that is used for both the jetty-client and the jetty-server
Together with the HTTP jars, the jetty-server, jetty-continuation and server-api jars make up the minimal dependencies needed to run a HTTP server. Note that while the servlet-api is used for requests and responses, this is not a servlet server and Jetty handlers must be used to generate responses.
Servlets and Webapps
If the jetty-security and jetty-servlet modules are added to the server dependencies, then you have the capability to run standard Servlets and Filters, but these must be configured programmatically. If the jetty-xml and jetty-webapp modules are included, then standard web applications and WAR files may be run using web.xml configuration. The jetty-deploy module then adds the ability to discover and deploy WAR files in application server style.
The jetty-jndi, jetty-plus and jetty-annotation modules together add more J2EE-like capabilities that are often collectively called "Jetty Plus"
The main Jetty external dependencies are shown in the dependency diagram above. You can see that other than JSP, annotations, plus and JNDI, the only other compile dependency on Jetty is the servlet-api. This means that for a standard web application without JSP, the only non-jetty jar required to run is the servlet-api jar.
Jetty does have some run-time optional dependencies. For example, the log mechanism contained in the jetty-util jar looks for an SLF4J jar on the classpath. If it finds one, SLF4J is used for Jetty logging; otherwise a simple stderr logger is used.
The start.jar is a generic and portable way to assemble a classpath and run a Java program. The default start.config file baked into the start.jar is for Jetty, but it could be modified for any application.
The start.jar mechanism uses the options defined in the config file to define the JARs required to run. The default configuration, which supports the core Jetty server with web applications, but no JSPs, is run with:
java -jar start.jar etc/myjetty.xml
If the core server jars are needed plus JSP and JMX, then specify these options, for example:
java -jar start.jar OPTIONS=Server,jsp,jmx
By convention, options starting with a capital letter refer to a set of Jetty modules, while those starting with lowercase refer to a specific module (e.g., "jsp" for jetty-jsp and its dependencies, "jmx" for jetty-jmx).
You can view the available start parameters and options with:
java -jar start.jar --help
You can see details of the jars each OPTION provides here or listed with:
java -jar start.jar --list-options
In addition to OPTIONS, the default configuration start.jar allows the classpath to be expanded by setting options for "lib" (to a directory containing jars) or "path" to a specific classpath. For example:
java -jar start.jar lib=/usr/share/java path=$HOME/src/myproject/classes
There is no requirement to start Jetty with the start.jar mechanism. A normal shell or bat script can be used to assemble a classpath to run a Jetty server from a direct invocation of the java command. Note that the start.jar mechanism has the --exec-print options to assist with creation of java command lines. For example, executing:
cd /usr/local/jetty-7 java -jar start.jar OPTIONS=server path=/usr/share/java/junit4.jar --dry-run
produces the following command line on the stdout:
/usr/lib/jvm/java-1.5.0-sun-188.8.131.52/jre/bin/java \ -cp /usr/share/java/junit4-4.3.1.jar:\ /usr/local/jetty-7/lib/servlet-api-2.5.jar:\ /usr/local/jetty-7/lib/jetty-http-7.0.0.RC2-SNAPSHOT.jar:\ /usr/local/jetty-7/lib/jetty-continuation-7.0.0.RC2-SNAPSHOT.jar:\ /usr/local/jetty-7/lib/jetty-server-7.0.0.RC2-SNAPSHOT.jar:\ /usr/local/jetty-7/lib/jetty-util-7.0.0.RC2-SNAPSHOT.jar:\ /usr/local/jetty-7/lib/jetty-io-7.0.0.RC2-SNAPSHOT.jar \ -Djetty.home=/usr/local/jetty-7 \ org.eclipse.jetty.xml.XmlConfiguration \ /usr/local/jetty-7/etc/jetty.xml
When embedding Jetty in other applications, it might be inconvenient and/or verbose to include the many small Jars that comprise Jetty. Thus there are several aggregate Jars available, which combine many smaller Jars into a single Jar.
Aggregate Jars are available as a Maven artifact under the org.eclipse.jetty.aggregate group ID.
The aggregate Jars available are: