* Updated README files.
* Updated the Getting Started sections. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
0bab243389
commit
9567ade30f
110
README.md
110
README.md
|
|
@ -1,7 +1,6 @@
|
|||
Eclipse Jetty Canonical Repository
|
||||
==================================
|
||||
# Eclipse Jetty Canonical Repository
|
||||
|
||||
This is the canonical repository for the Jetty project, feel free to fork and contribute now!
|
||||
This is the canonical repository for the Eclipse Jetty project, feel free to fork and contribute now!
|
||||
|
||||
Submitting a patch or pull request?
|
||||
|
||||
|
|
@ -9,17 +8,16 @@ Make sure you have an Eclipse Contributor Agreement (ECA) on file.
|
|||
|
||||
- [eclipse.org/legal/ecafaq](https://www.eclipse.org/legal/ecafaq.php)
|
||||
|
||||
Project description
|
||||
-------------------
|
||||
## Project description
|
||||
|
||||
Jetty is a lightweight highly scalable java based web server and servlet engine.
|
||||
Our goal is to support web protocols like HTTP, HTTP/2 and WebSocket in a high volume low latency way that provides maximum performance while retaining the ease of use and compatibility with years of servlet development.
|
||||
Jetty is a modern fully async web server that has a long history as a component oriented technology easily embedded into applications while still offering a solid traditional distribution for webapp deployment.
|
||||
Eclipse Jetty is a lightweight, highly scalable, Java-based web server and Servlet engine.
|
||||
Jetty's goal is to support web protocols (HTTP/1, HTTP/2, HTTP/3, WebSocket, etc.) in a high volume low latency way that provides maximum performance while retaining the ease of use and compatibility with years of Servlet development.
|
||||
Jetty is a modern fully asynchronous web server that has a long history as a component oriented technology, and can be easily embedded into applications while still offering a solid traditional distribution for webapp deployment.
|
||||
|
||||
- [https://projects.eclipse.org/projects/rt.jetty](https://projects.eclipse.org/projects/rt.jetty)
|
||||
|
||||
Webapp Example
|
||||
--------------
|
||||
## Webapp Example
|
||||
|
||||
```shell
|
||||
$ mkdir base && cd base
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=http,ee10-deploy
|
||||
|
|
@ -27,8 +25,8 @@ $ cp ~/src/myproj/target/mywebapp.war webapps
|
|||
$ java -jar $JETTY_HOME/start.jar
|
||||
```
|
||||
|
||||
Multiple Versions Webapp Example
|
||||
--------------------------------
|
||||
## Multiple Versions Webapp Example
|
||||
|
||||
```shell
|
||||
$ mkdir base && cd base
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=http,ee10-deploy,ee8-deploy
|
||||
|
|
@ -38,8 +36,8 @@ $ echo environment: ee8 > webapps/mywebapp8.properties
|
|||
$ java -jar $JETTY_HOME/start.jar
|
||||
```
|
||||
|
||||
Embedded Example
|
||||
----------------
|
||||
## Embedded Example
|
||||
|
||||
```java
|
||||
Server server = new Server(port);
|
||||
ServletContextHandler context = new ServletContextHandler(server, "/");
|
||||
|
|
@ -47,70 +45,74 @@ context.addServlet(MyServlet.class, "/*");
|
|||
server.start();
|
||||
```
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
## Documentation
|
||||
|
||||
Project documentation is available on the Jetty Eclipse website.
|
||||
Project documentation is available on the Eclipse Jetty website.
|
||||
|
||||
- [https://www.eclipse.org/jetty/documentation](https://www.eclipse.org/jetty/documentation)
|
||||
|
||||
Building
|
||||
========
|
||||
# Building
|
||||
|
||||
[Apache Maven 3.8.0](https://maven.apache.org/) and [OpenJDK](https://adoptium.net/) requirements:
|
||||
[Apache Maven](https://maven.apache.org/) and [OpenJDK](https://adoptium.net/) requirements:
|
||||
|
||||
Branch | Maven Version | Minimum JDK | Recommended JDK
|
||||
---------------|---------------|-------------| ---------------
|
||||
`jetty-10.0.x` | Maven 3.8.6+ | OpenJDK 11 | OpenJDK 17 (for optional loom and http/3 support)
|
||||
`jetty-11.0.x` | Maven 3.8.6+ | OpenJDK 11 | OpenJDK 17 (for optional loom and http/3 support)
|
||||
`jetty-12.0.x` | Maven 3.8.6+ | OpenJDK 17 | OpenJDK 17
|
||||
| Branch | Maven Version | Minimum JDK | Recommended JDK |
|
||||
|----------------|---------------|-------------|--------------------------------------------------------------|
|
||||
| `jetty-10.0.x` | Maven 3.8.6+ | OpenJDK 11 | OpenJDK 17 (for optional virtual threads and HTTP/3 support) |
|
||||
| `jetty-11.0.x` | Maven 3.8.6+ | OpenJDK 11 | OpenJDK 17 (for optional virtual threads and HTTP/3 support) |
|
||||
| `jetty-12.0.x` | Maven 3.8.6+ | OpenJDK 17 | OpenJDK 17 |
|
||||
|
||||
Full Build with All Tests:
|
||||
## Full Build
|
||||
|
||||
If you want to build Jetty and run all the tests, which may takes quite some time, use the following command:
|
||||
|
||||
``` shell
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
Fast Build if you need jars and distribution (not running tests, checkstyle, enforcer, license check):
|
||||
|
||||
``` shell
|
||||
mvn -Pfast clean install
|
||||
```
|
||||
Optional build tools:
|
||||
|
||||
* [`graphviz`](https://graphviz.org/) - used by asciidoctor in the jetty-documentation build to produce various graphs
|
||||
* [`Docker`](https://www.docker.com/) - used to run some integration tests for testing third party integrations
|
||||
|
||||
Once the build is complete, you can find the built Jetty Maven artifacts in your Maven local repository.
|
||||
Along with the following locations of note:
|
||||
|
||||
Branches | Location | Description
|
||||
---------------|-------------------------------------------------------------------|---------
|
||||
all | `jetty-home/target/jetty-home-<ver>.tar.gz` | The Jetty Home standalone tarball
|
||||
`jetty-10.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner uber jar
|
||||
`jetty-11.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner uber jar
|
||||
`jetty-12.0.x` | `jetty-ee10/jetty-ee10-runner/target/jetty-ee10-runner-<ver>.jar` | The Jetty Runner uber jar for ee10/Servlet 6 (jakarta.servlet) webapps
|
||||
`jetty-12.0.x` | `jetty-ee9/jetty-ee9-runner/target/jetty-ee9-runner-<ver>.jar` | The Jetty Runner uber jar for ee9/Servlet 5 (jakarta.servlet) webapps
|
||||
`jetty-12.0.x` | `jetty-ee8/jetty-ee8-runner/target/jetty-ee8-runner-<ver>.jar` | The Jetty Runner uber jar for ee8/Servlet 4 (javax.servlet) webapps
|
||||
|
||||
Note: The build tests do a lot of stress testing, and on some machines it is necessary to set the
|
||||
file descriptor limit to greater than 2048 for the tests to all pass successfully (check your `ulimit -n` value).
|
||||
Note: There are stress tests that on some hardware or operative system require to set the file descriptor limit to a value greater than 2048 to pass successfully (check your `ulimit -n` value).
|
||||
|
||||
Note: The tests are running in parallel using [Junit5 parallel execution](https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution).
|
||||
This is configurable using the following properties:
|
||||
|
||||
```
|
||||
# to enable/disable the parallel execution
|
||||
-Djunit.jupiter.execution.parallel.enabled=true/false
|
||||
# number of tests executed in parallel
|
||||
-Djunit.jupiter.execution.parallel.config.fixed.parallelism=2
|
||||
```
|
||||
If a test cannot be runned in parallel because accessing/modifying some static fields or for any other reasons, the test should be marked with the annotation
|
||||
|
||||
If a test cannot be run in parallel because it accesses/modifies some `static` fields or for any other reasons, the test should be marked with the annotation:
|
||||
|
||||
```java
|
||||
@Isolated("Access static field of Configurations")
|
||||
```
|
||||
|
||||
## Fast Build
|
||||
|
||||
Professional Services
|
||||
---------------------
|
||||
If you just need the Jetty module jars and the Jetty Home distribution, you can run a fast build that does not run tests and other checks with the following command:
|
||||
|
||||
Expert advice and production support are available through [Webtide.com](https://webtide.com).
|
||||
``` shell
|
||||
mvn -Pfast clean install
|
||||
```
|
||||
|
||||
## Optional Build Tools
|
||||
|
||||
* [`graphviz`](https://graphviz.org/) - used by asciidoctor in the jetty-documentation module to produce various graphs
|
||||
* [`Docker`](https://www.docker.com/) - used to run some integration tests for testing third party integrations
|
||||
|
||||
## Build Artifacts
|
||||
|
||||
Once the build is complete, you can find the built Jetty Maven artifacts in your Maven local repository, along with the following locations of note:
|
||||
|
||||
| Branches | Location | Description |
|
||||
|----------------|-------------------------------------------------------------------|------------------------------------------------------------------------------|
|
||||
| all | `jetty-home/target/jetty-home-<ver>.tar.gz` | The Jetty Home distribution |
|
||||
| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution |
|
||||
| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution |
|
||||
| `jetty-12.0.x` | `jetty-ee10/jetty-ee10-runner/target/jetty-ee10-runner-<ver>.jar` | The Jetty Runner distribution for EE10/Servlet 6 (`jakarta.servlet`) webapps |
|
||||
| `jetty-12.0.x` | `jetty-ee9/jetty-ee9-runner/target/jetty-ee9-runner-<ver>.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps |
|
||||
| `jetty-12.0.x` | `jetty-ee8/jetty-ee8-runner/target/jetty-ee8-runner-<ver>.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps |
|
||||
|
||||
# Commercial Support
|
||||
|
||||
Expert advice and production support of Jetty are provided by [Webtide](https://webtide.com).
|
||||
|
|
|
|||
|
|
@ -16,19 +16,19 @@
|
|||
|
||||
You can deploy two types of web application resources with Jetty:
|
||||
|
||||
* *Standard Web Application Archives*, in the form of `+*.war+` files or web application directories, defined by the link:https://www.oracle.com/java/technologies/java-servlet-tec.html[Servlet specification].
|
||||
* *Standard Web Application Archives*, in the form of `+*.war+` files or web application directories, defined by the link:https://jakarta.ee/specifications/servlet/[Servlet specification].
|
||||
Their deployment is described in xref:og-begin-deploy-war[this section].
|
||||
* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you to use Jetty components -- and possibly custom components written by you -- to assemble your web applications.
|
||||
* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you to use Jetty components -- and possibly custom components written by you -- to assemble and deploy your web applications.
|
||||
Their deployment is described in xref:og-deploy[this section].
|
||||
|
||||
Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific _environment_.
|
||||
Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific EE _environment_, such as the old Java EE 8, or Jakarta EE 9, or Jakarta {ee-current-caps}.
|
||||
|
||||
In the following sections you can find simple examples of deployments of Jakarta {ee-current-caps} web applications.
|
||||
|
||||
However, Jetty supports simultaneous deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta {ee-current-caps} web application.
|
||||
Jetty supports _simultaneous_ deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta {ee-current-caps} web application.
|
||||
|
||||
Refer to the section about xref:og-deploy[deployment] for further information about how to deploy to different environments.
|
||||
|
||||
In the following sections you can find simple examples of deployments of Jakarta {ee-current-caps} web applications.
|
||||
|
||||
[[og-begin-deploy-war]]
|
||||
===== Deploying +*.war+ Files
|
||||
|
||||
|
|
@ -50,7 +50,7 @@ mywebapp.war
|
|||
<1> Publicly accessible resources such as `+*.html+`, `+*.jsp+`, `+*.css+`, `+*.js+` files, etc. are placed in `+*.war+` or in sub-directories of the `+*.war+`.
|
||||
<2> `WEB-INF` is a special directory used to store anything related to the web application that must not be publicly accessible, but may be accessed by other resources.
|
||||
<3> `WEB-INF/classes` stores the web application's compiled `+*.class+` files
|
||||
<4> `WEB-INF/classes` stores the web application's `+*.jar+` files
|
||||
<4> `WEB-INF/lib` stores the web application's `+*.jar+` files
|
||||
<5> `WEB-INF/web.xml` is the web application deployment descriptor, which defines the components and the configuration of your web application.
|
||||
====
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ include::jetty[setupArgs="--add-module=http",args="--add-module={ee-current}-dep
|
|||
The `{ee-current}-deploy` module creates `$JETTY_BASE/webapps`, which is the directory where Jetty looks for any `+*.war+` files or web application directories to deploy.
|
||||
|
||||
Activating one of Jetty's `{ee-all}-deploy` modules enables web application deployment.
|
||||
Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on if the correspondent Jetty modules have been enabled.
|
||||
Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on whether the correspondent Jetty protocol modules have been enabled.
|
||||
Refer to the xref:og-protocols[section about protocols] for further information.
|
||||
|
||||
Now you're ready to copy a web application to the `$JETTY_BASE/webapps` directory.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,6 @@
|
|||
[[og-begin-download]]
|
||||
==== Downloading Jetty
|
||||
|
||||
The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[]
|
||||
|
||||
The Eclipse Jetty distribution is available in both `zip` and `gzip` formats; download the one most appropriate for your system, typically `zip` for Windows and `gzip` for other operating systems.
|
||||
The Jetty distribution is a file of the form `jetty-home-<version>.<ext>`, available for download from link:https://eclipse.dev/jetty/download.html[]
|
||||
|
||||
The Jetty distribution is available in both `zip` and `gzip` formats; download the one most appropriate for your system, typically `zip` for Windows and `gzip` for other operating systems.
|
||||
|
|
|
|||
|
|
@ -14,13 +14,13 @@
|
|||
[[og-begin-install]]
|
||||
==== Installing Jetty
|
||||
|
||||
After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version of Jetty that you downloaded.
|
||||
After the download, unpacking Jetty will extract the files into a directory called `jetty-home-<version>`, where `<version>` is the version of Jetty that you downloaded.
|
||||
For example, installing Jetty {version} will create a directory called `jetty-home-{version}`.
|
||||
|
||||
IMPORTANT: It is important that *only* stable release versions are used in production environments.
|
||||
Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
|
||||
|
||||
Unpack Eclipse Jetty file into a convenient location, such as `/opt`.
|
||||
Unpack Jetty file into a convenient location, such as `/opt`.
|
||||
The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`.
|
||||
|
||||
CAUTION: For Windows users, you should unpack Jetty to a path that does not contain spaces.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
[[og-begin-start]]
|
||||
==== Starting Jetty
|
||||
|
||||
Eclipse Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line.
|
||||
Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line.
|
||||
|
||||
First, create a `$JETTY_BASE` directory.
|
||||
|
||||
|
|
@ -93,7 +93,7 @@ $JETTY_BASE
|
|||
|
||||
[NOTE]
|
||||
====
|
||||
By default, Jetty does not generate `+*.ini+` configuration files in `start.d/` for modules activated as transitive dependencies.
|
||||
By default, Jetty does *not* generate `+*.ini+` configuration files in `start.d/` for modules activated as transitive dependencies.
|
||||
To manually configure such modules, you should activate them directly via Jetty's `--add-modules` flag.
|
||||
====
|
||||
|
||||
|
|
|
|||
|
|
@ -2,11 +2,11 @@
|
|||
|
||||
The link:https://www.eclipse.org/jetty/[Eclipse Jetty] Project provides a:
|
||||
|
||||
* Java HTTP & WebSocket Server
|
||||
* Servlet Container
|
||||
* Java HTTP & WebSocket Client
|
||||
* Java HTTP (HTTP/1.1, HTTP/2 and HTTP/3) Server and Client
|
||||
* Jakarta EE Servlet Container
|
||||
* Java WebSocket Server and Client
|
||||
|
||||
Jetty is available under an open source link:LICENSE.txt[LICENSE], and the full source code is available at link:https://github.com/eclipse/jetty.project[GitHub].
|
||||
Jetty is available under an open source link:LICENSE.txt[license], and the full source code is available at link:https://github.com/eclipse/jetty.project[GitHub].
|
||||
|
||||
The Jetty documentation is available at link:https://www.eclipse.org/jetty/documentation[].
|
||||
|
||||
|
|
@ -18,16 +18,18 @@ Jetty is distributed in an artifact that expands in a directory called `$JETTY_H
|
|||
Configuration for Jetty is typically done in a directory called `$JETTY_BASE`.
|
||||
There may be more than one `$JETTY_BASE` directories with different configurations.
|
||||
|
||||
The following commands can be used to set up a `$JETTY_BASE` directory that supports deployment of `+*.war+` files and a clear-text HTTP connector:
|
||||
Jetty supports the deployment of EE8, EE9 and EE10 standard web applications, as well as the deployment of Jetty-specific web applications.
|
||||
|
||||
For example, the following commands can be used to set up a `$JETTY_BASE` directory that supports deployment of EE10 `+*.war+` files and a clear-text HTTP connector:
|
||||
|
||||
----
|
||||
$ export JETTY_HOME=/path/to/jetty-home
|
||||
$ mkdir /path/to/jetty-base
|
||||
$ cd /path/to/jetty-base
|
||||
$ java -jar $JETTY_HOME/start.jar --add-module=server,http,deploy
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,ee10-deploy
|
||||
----
|
||||
|
||||
The last command creates a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard `+*.war+` files can be deployed.
|
||||
The last command creates a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard EE10 `+*.war+` files can be deployed.
|
||||
|
||||
To deploy Jetty's demo web applications, run this command:
|
||||
|
||||
|
|
@ -46,7 +48,7 @@ Point your browser at `+http://localhost:8080+` to see the demo web applications
|
|||
The Jetty server can be stopped with `ctrl+c` in the terminal window.
|
||||
// end::quick[]
|
||||
|
||||
For more information about how to start Jetty, run this command (or go to the link:https://www.eclipse.org/jetty/documentation[documentation]):
|
||||
For more information about how to start Jetty, you can read the link:https://www.eclipse.org/jetty/documentation[documentation], or run this command:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --help
|
||||
|
|
|
|||
Loading…
Reference in New Issue