Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty/Reference/Dependencies"
m (Jetty/Reference/dependencies moved to Jetty/Reference/Dependencies: title case) |
|||
| (8 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Jetty Reference | {{Jetty Reference | ||
|introduction = | |introduction = | ||
| − | The | + | |
| + | {{Jetty TODO}} | ||
| + | |||
| + | 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. | ||
=== Maven Dependency === | === Maven Dependency === | ||
| − | When working out | + | When working out dependencies, the Maven dependency:tree plugin is your friend. For example, to find out the dependencies of the jetty-servlet module: |
<pre> | <pre> | ||
| Line 25: | Line 28: | ||
[INFO] \- org.eclipse.jetty:jetty-util:jar:7.0.0.RC2-SNAPSHOT:compile | [INFO] \- org.eclipse.jetty:jetty-util:jar:7.0.0.RC2-SNAPSHOT:compile | ||
</pre> | </pre> | ||
| − | + | ||
| − | === Types of | + | === Types of Dependencies === |
| − | Jetty | + | Jetty uses three types of Maven dependencies: |
| − | + | <div class='wide-list'> | |
| − | + | ; compile: 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. | |
| − | + | ; provided | |
| − | + | : (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 [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-util/src/main/java/org/eclipse/jetty/util/log/Slf4jLog.java 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 [http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/test-jetty-webapp/pom.xml 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. | ||
| + | ; test : 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). | ||
| + | </div> | ||
|body = | |body = | ||
== Dependency Tree == | == Dependency Tree == | ||
| − | [[Image: | + | [[Image:dependencies.jpg]] |
| − | This diagram shows the compile dependencies for the | + | 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: |
=== HTTP === | === HTTP === | ||
| − | 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 | + | 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''' |
=== Server === | === 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 | + | 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 === | === 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 | + | 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 [[Jetty/Reference/jetty.xml_syntax|web.xml]] configuration. The '''jetty-deploy''' module then adds the ability to discover and deploy WAR files in application server style. |
=== Plus === | === Plus === | ||
| − | The jetty-jndi, jetty-plus and jetty-annotation modules together add more J2EE-like capabilities that are often collectively called "Jetty Plus" | + | The '''jetty-jndi''', '''jetty-plus''' and '''jetty-annotation''' modules together add more J2EE-like capabilities that are often collectively called "Jetty Plus" |
== External Dependencies == | == External Dependencies == | ||
| − | The main Jetty external dependencies are shown in the dependency diagram above. | + | 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 | + | Jetty does have some run-time optional dependencies. For example, the log mechanism contained in the jetty-util jar looks for an [http://www.slf4j.org SLF4J] jar on the classpath. If it finds one, SLF4J is used for Jetty logging; otherwise a simple stderr logger is used. |
== start.jar == | == start.jar == | ||
| − | The start.jar is a generic and portable way to assemble a classpath and run a | + | The start.jar is a generic and portable way to assemble a classpath and run a Java program. The default [http://dev.eclipse.org/svnroot/rt/org.eclipse.jetty/jetty/trunk/jetty-start/src/main/resources/org/eclipse/jetty/start/start.config 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 | + | 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 | |
| − | + | ||
| − | java -jar start.jar --help | + | 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 [[Jetty/Reference/Start_Options|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: | 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 | java -jar start.jar lib=/usr/share/java path=$HOME/src/myproject/classes | ||
| − | |||
| − | == Classpath | + | |
| − | There is no requirement to start | + | == Classpath Execution == |
| − | + | 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 | + | 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: | ||
<pre> | <pre> | ||
/usr/lib/jvm/java-1.5.0-sun-1.5.0.19/jre/bin/java \ | /usr/lib/jvm/java-1.5.0-sun-1.5.0.19/jre/bin/java \ | ||
| Line 107: | Line 112: | ||
</pre> | </pre> | ||
| − | == | + | == Aggregate JARs == |
| + | |||
| + | 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 | + | The aggregate Jars available are: |
* jetty-all | * jetty-all | ||
* jetty-all-server | * jetty-all-server | ||
Latest revision as of 15:38, 23 April 2013
Contents
Introduction
Some or all of this content remains to be ported to Jetty 9 Documentation.
If you are interested in migrating this content see our contribution guide or contact us.
If you are interested in migrating this content see our contribution guide or contact us.
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.
Maven Dependency
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:
- compile
- 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.
- provided
- (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.
- test
- 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).
Dependency Tree
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:
HTTP
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
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.
Plus
The jetty-jndi, jetty-plus and jetty-annotation modules together add more J2EE-like capabilities that are often collectively called "Jetty Plus"
External Dependencies
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.
start.jar
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
Classpath Execution
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-1.5.0.19/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
Aggregate JARs
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:
- jetty-all
- jetty-all-server
- jetty-client
- jetty-plus
- jetty-server
- jetty-servlet
- jetty-webapp