The jetty classes are are organized into almost 50 jars, so it is crucial to understand the organization and dependencies (internal or external) when creating classpaths for Jetty.
When working out dependency, 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 dependency
Jetty makes use of three types of maven dependency:
- compile - these are real hard dependencies that you need to compile and run the code. In the above example, you can see that jetty-servlet has a single hard dependency on jetty-security, which has transitive dependencies on jetty-server, servlet-api, jetty-http, jetty-io, jetty-util.
- provided (optional) - these are used for optional dependencies that are 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 Slf4jLogger, but slf4j is optional at runtime, so that if the dependency is not on the classpath, then the Slf4J logger is not used.
- provided (environmental) - these dependencies are 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 API is expected to be provided by the servlet container, so the servlet-api JAR is not included in the WEB-INF/lib of the assembled war file.
- test - These dependencies are used for unit tests (but some integration tests are in modules with test-foo names and used 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 run standard Servlets and Filters, but these must be configured programatically. 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. It can be seen that other that for 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 will look for an [www.slf4j.org SLF4J] jar on the class path. If one is found, then 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 webapplications, 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 options need to be used like:
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 (eg jsp for jetty-jsp and it's dependencies, jmx for jetty-jmx).
The available start parameters and options can seen with
java -jar start.jar --help
The detail of the jars provided by each OPTION can been see Jetty/Reference/Start_Options here or listed withL
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
Will produce the following command line on the stdout:
/usr/lib/jvm/java-1.5.0-sun-220.127.116.11/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 may 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 (available as a maven artefact under the org.eclipse.jetty.aggregate group ID).
The aggregate jars available are: