Chapter 2 and 3 updates.
Signed-off-by: WalkerWatch <ctwalker@gmail.com>
This commit is contained in:
WalkerWatch
parent
afcec96a23
commit
c96e58fa37
|
|
@ -55,7 +55,7 @@ For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.w
|
|||
____
|
||||
[NOTE]
|
||||
Both `SystemProperty` and `Property` elements can be used in the descriptor file.
|
||||
For example, if the system property is set tp `myapp.home=/opt/myapp`, the previous example can be rewritten as:
|
||||
For example, if the system property is set to `myapp.home=/opt/myapp`, the previous example can be rewritten as:
|
||||
____
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
|
|||
|
|
@ -17,11 +17,11 @@
|
|||
[[configuring-webapps]]
|
||||
=== Deployment Processing of WebAppContexts
|
||||
|
||||
Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, web.xml and web-fragment.xml descriptors processed, and classes scanned for annotations amongst many other things.
|
||||
As web applications have become more complex, Jetty gas added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
|
||||
Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, `web.xml` and `web-fragment.xml` descriptors processed, and classes scanned for annotations amongst other things.
|
||||
As web applications have become more complex, Jetty has added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
|
||||
This section will examine this processing and it can be tailored to fit individual needs.
|
||||
|
||||
If instead you're looking for information on how to configure a specific WebAppContext - such as its context path, whether it should be unpacked or not - then you can find that in the section entitled link:#configuring-specific-webapp-deployment[Configuring a Specific WebApp Deployment].
|
||||
If instead you're looking for information on how to configure a specific `WebAppContext` - such as its context path, whether it should be unpacked or not - then you can find that in the section entitled link:#configuring-specific-webapp-deployment[Configuring a Specific WebApp Deployment].
|
||||
|
||||
[[webapp-configurations]]
|
||||
==== Configuration Classes
|
||||
|
|
@ -52,7 +52,7 @@ META-INF/web-fragment.xml
|
|||
|
||||
===== Anatomy of a Configuration Class
|
||||
|
||||
A Configuration class is called 5 times in different phases of the `WebAppContext's` lifecycle:
|
||||
A Configuration class is called 5 times in different phases of the link:http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext's`] lifecycle:
|
||||
|
||||
preConfigure::
|
||||
As the `WebAppContext` is starting up this phase is executed.
|
||||
|
|
@ -75,9 +75,9 @@ The cycle is repeated _in reverse order_ for the `deconfigure()` and eventually
|
|||
|
||||
===== Extending Container Support by Creating Extra Configurations
|
||||
|
||||
As shows, there is a default set of Configurations that support basic deployment of a webapp.
|
||||
JavaEE features such as JNDI, nor advanced servlet spec features such as annotations have not been mentioned.
|
||||
That is because Jetty's philosophy is to allow the user to tailor the container exactly to their needs.
|
||||
As shown, there is a default set of Configurations that support basic deployment of a webapp.
|
||||
JavaEE features such as JNDI and advanced servlet spec features such as annotations have not been mentioned.
|
||||
Jetty's philosophy is to allow the user to tailor the container exactly to their needs.
|
||||
If these features are not needed, then Jetty does not pay the price for them - an important consideration because features such as annotations require extensive and time-consuming scanning of `WEB-INF/lib` jars.
|
||||
As modern webapps may have scores of these jars, it can be a source of significant deployment delay.
|
||||
We will see in the section link:#webapp-context-attributes[Other Configuration] another helpful webapp facility that Jetty provides for cutting down the time spent analyzing jars.
|
||||
|
|
@ -103,7 +103,7 @@ To achieve that, we use 2 extra Configurations:
|
|||
|=======================================================================
|
||||
|
||||
These configurations must be added in _exactly_ the order shown above and should be inserted _immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
|
||||
To fully support JNDI, you need to do a couple of other things, full details of which can be found link:#jndi[here].
|
||||
To fully support JNDI additional configuration is required, full details of which can be found link:#jndi[here].
|
||||
|
||||
====== Example: Annotation Configurations
|
||||
|
||||
|
|
@ -118,7 +118,7 @@ We need just one extra Configuration class to help provide servlet annotation sc
|
|||
|=======================================================================
|
||||
|
||||
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.webapp.JettyWebXmlConfiguration] class in the list of configurations.
|
||||
To fully support annotations, you need to do a couple of other things, details of which can be found below.
|
||||
To fully support annotations additional configuration is require, details of which can be found link:#webapp-context-attributes[below.]
|
||||
|
||||
===== How to Set the List of Configurations
|
||||
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@
|
|||
// ========================================================================
|
||||
|
||||
[[quick-start-configure]]
|
||||
== Jetty Configuration Introduction
|
||||
== An Introduction to Jetty Configuration
|
||||
|
||||
include::how-to-configure.adoc[]
|
||||
include::what-to-configure.adoc[]
|
||||
|
|
|
|||
|
|
@ -23,10 +23,12 @@ The link:#quickstart-config-what[next section] gives an overview of the action c
|
|||
|
||||
==== Jetty POJO Configuration
|
||||
|
||||
The core components of Jetty are Plain Old Java Objects (http://en.wikipedia.org/wiki/Plain_Old_Java_Object[POJOs]); the process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs.
|
||||
The core components of Jetty are Plain Old Java Objects (http://en.wikipedia.org/wiki/Plain_Old_Java_Object[POJOs])
|
||||
The process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs.
|
||||
This can be achieved by:
|
||||
|
||||
* Writing Java code to directly instantiate and assemble Jetty objects. This is referred to as xref:embedding-jetty[].
|
||||
* Writing Java code to directly instantiate and assemble Jetty objects.
|
||||
This is referred to as xref:embedding-jetty[].
|
||||
* Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects.
|
||||
The `etc/jetty.xml` file is the main Jetty XML configuration file, but there are many other `etc/jetty-__feature__.xml` files included in the Jetty distribution.
|
||||
* Using a third party http://en.wikipedia.org/wiki/Inversion_of_Control[IoC] framework like http://en.wikipedia.org/wiki/Spring_Framework[Spring], to instantiate and assemble Jetty objects as Spring beans.
|
||||
|
|
@ -35,20 +37,25 @@ Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API
|
|||
|
||||
==== Jetty Start Configuration Files
|
||||
|
||||
The Jetty distribution uses the following configuration files to instantiate, inject and start server via the start.jar mechanism.
|
||||
The Jetty distribution uses the following configuration files to instantiate, inject and start server via the `start.jar` mechanism.
|
||||
|
||||
`ini` files::
|
||||
The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments.
|
||||
Arguments may be:
|
||||
|
||||
* XML files in Jetty IoC (or Spring) XML format
|
||||
* Module activations in the form `--module=name`
|
||||
* Property in the form of `name=value`, used to parameterize Jetty IoC XML
|
||||
* Properties in the form of `name=value`, used to parameterize Jetty IoC XML
|
||||
* XML files in Jetty IoC (or Spring) XML format
|
||||
* A standard http://en.wikipedia.org/wiki/Java_properties[Java property file] containing additional start properties
|
||||
* Other start.jar options (see `java -jar start.jar --help`)
|
||||
* Some JVM options in combination with `--exec`, such as `-Xbootclasspath`.
|
||||
+
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
--
|
||||
As of Jetty 9 it is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
|
||||
--
|
||||
____
|
||||
|
||||
`mod` files::
|
||||
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
|
||||
|
|
@ -69,7 +76,7 @@ XML files::
|
|||
The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts.
|
||||
Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding `ini` files.
|
||||
XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`.
|
||||
If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified.
|
||||
*Note* If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified.
|
||||
|
||||
Below is an illustration of how the various Jetty configuration files (`ini`, `mod` and XML) are related:
|
||||
|
||||
|
|
@ -83,7 +90,7 @@ Context XML files::
|
|||
Any XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format that is discovered in the `/webapps` directory are used by the deploy module to instantiate and inject `HttpContext` instances to create a specific context.
|
||||
These may be standard web applications or bespoke contexts created from special purpose handlers.
|
||||
|
||||
`web.xml`::
|
||||
web.xml::
|
||||
The http://en.wikipedia.org/wiki/Servlet[Servlet] Specification defines the http://en.wikipedia.org/wiki/Web.xml[`web.xml`] deployment descriptor that defines and configures the filters, servlets and resources a http://en.wikipedia.org/wiki/Web_application[web application] uses.
|
||||
The Jetty `WebAppContext` component uses this XML format to:
|
||||
|
||||
|
|
@ -117,5 +124,5 @@ link:#jetty-xml-syntax[Jetty IoC XML format] allows you to instantiate and confi
|
|||
include::{SRCDIR}/examples/embedded/src/main/resources/exampleserver.xml[]
|
||||
----
|
||||
|
||||
In practice, most commonly used Jetty features have XML files that are included in the standard distribution in the `etc` directory.
|
||||
Thus configuring Jetty is often a matter of just editing existing XML files and altering the property values injected into them.
|
||||
//In practice, most commonly used Jetty features have XML files that are included in the standard distribution in the `/etc` directory.
|
||||
//Thus configuring Jetty is often a matter of just editing existing XML files and altering the property values injected into them.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ In the standard Jetty distribution, the core server configuration is in `etc/jet
|
|||
|
||||
ThreadPool::
|
||||
The Server instance provides a ThreadPool instance that is the default Executor service other Jetty server components use.
|
||||
The prime configuration of the thread pool is the maximum and minimum size and is set in `start.ini`.
|
||||
The prime configuration of the thread pool is the maximum and minimum size and is set in `start.ini` or `start.d/server.ini`.
|
||||
Handlers::
|
||||
A Jetty server can have only a single Handler instance to handle incoming HTTP requests.
|
||||
However a handler may be a container or wrapper of other handlers forming a tree of handlers that typically
|
||||
|
|
@ -42,7 +42,7 @@ Server Attributes::
|
|||
The server holds a generic attribute map of strings to objects so that other Jetty components can associate named objects with the server, and if the value objects implement the LifeCycle interface, they are started and stopped with the server.
|
||||
Typically server attributes hold server-wide default values.
|
||||
Server fields::
|
||||
The server also has some specific configuration fields that you set in `start.ini` for controlling among other things, the sending of dates and versions in HTTP responses.
|
||||
The server also has some specific configuration fields that you set in `start.ini` or `start.d/server.ini` for controlling, among other things, the sending of dates and versions in HTTP responses.
|
||||
Connectors::
|
||||
The server holds a collection of connectors that receive connections for HTTP and the other protocols that Jetty supports.
|
||||
The next section, xref:intro-jetty-configuration-connectors[] describes configuration of the connectors themselves.
|
||||
|
|
@ -81,7 +81,7 @@ ____
|
|||
____
|
||||
[NOTE]
|
||||
Prior to Jetty 9, the type of the connector reflected both the protocol supported (HTTP, HTTPS, AJP, SPDY), and the nature of the implementation (NIO or BIO).
|
||||
From Jetty 9 onwards there is only one prime Connector type (ServerConnector), which is NIO based and uses Connection Factories to handle one or more protocols.
|
||||
From Jetty 9 onwards there is only one prime Connector type (`ServerConnector`), which is NIO based and uses Connection Factories to handle one or more protocols.
|
||||
____
|
||||
|
||||
[[intro-jetty-configuration-contexts]]
|
||||
|
|
@ -173,29 +173,29 @@ The deployer discovers and hot deploys context IoC descriptors like the followin
|
|||
The servlet specification defines a web application, which when packaged as a zip is called WAR file (Web application ARchive).
|
||||
Jetty implements both WAR files and unpacked web applications as a specialized context that is configured by means of:
|
||||
|
||||
* A standard layout which sets the location of the resourceBase (the root of the WAR) and initializes the classpath from jars found in WEB-INF/lib and classes found in WEB-INF/classes.
|
||||
* A standard layout which sets the location of the resourceBase (the root of the WAR) and initializes the classpath from jars found in `WEB-INF/lib` and classes found in `WEB-INF/classes`.
|
||||
* The standard `WEB-INF/web.xml` deployment descriptor which is parsed to define and configure init parameters, filters, servlets, listeners, security constraints, welcome files and resources to be injected.
|
||||
* A default `web.xml` format deployment descriptor provided either by Jetty or in configuration configures the JSP servlet and the default servlet for handling static content.
|
||||
The standard `web.xml` may override the default `web.xml`.
|
||||
* Annotations discovered on classes in Jars contained in `WEB-INF/lib` can declare additional filters, servlets and listeners.
|
||||
* Standard deployment descriptor fragments discovered in Jars contained in ` WEB-INF/lib` can declare additional init parameters, filters, servlets, listeners, security constraints, welcome files and resources to be injected.
|
||||
* Standard deployment descriptor fragments discovered in Jars contained in `WEB-INF/lib` can declare additional init parameters, filters, servlets, listeners, security constraints, welcome files and resources to be injected.
|
||||
* An optional `WEB-INF/jetty-web.xml` file may contain Jetty IoC configuration to configure the Jetty specific APIs of the context and handlers.
|
||||
|
||||
Because these configuration mechanisms are contained within the WAR file (or unpacked web application), typically a web application contains much of its own configuration and deploying a WAR is often just a matter of dropping the WAR file in to the webapps directory that is scanned by the link:#quickstart-config-deployer[jetty deployer].
|
||||
Because these configuration mechanisms are contained within the WAR file (or unpacked web application), typically a web application contains much of its own configuration and deploying a WAR is often just a matter of dropping the WAR file in to the webapps directory that is scanned by the link:#quickstart-config-deployer[Jetty deployer].
|
||||
|
||||
If you need to configure something within a web application, often you do so by unpacking the WAR file and editing the `web.xml` and other configuration files.
|
||||
However, both the servlet standard and some Jetty features allow for other configuration to be applied to a web
|
||||
application externally from the WAR:
|
||||
However, both the servlet standard and some Jetty features allow for other configuration to be applied to a web application externally from the WAR:
|
||||
|
||||
* You configure data sources and security realms in the server and inject them into a web application either explicitly or by name matching.
|
||||
* Configured data sources and security realms in the server can be injected into a web application either explicitly or by name matching.
|
||||
* Jetty allows one or more override deployment descriptors, in `web.xml` format, to be set on a context (via code or IoC XML) to amend the configuration set by the default and standard `web.xml`.
|
||||
* The normal Jetty Java API may be called by code or IoC XML to amend the configuration of a web application.
|
||||
|
||||
===== Setting the Context Path
|
||||
|
||||
The web application standard provides no configuration mechanism for a web application or WAR file to set its own contextPath.
|
||||
The web application standard provides no configuration mechanism for a web application or WAR file to set its own `contextPath`.
|
||||
By default the deployer uses conventions to set the context path:
|
||||
If you deploy a WAR file called `foobar.WAR`, the context path is `/foobar`; if you deploy a WAR file called `ROOT.WAR` the context path is /.
|
||||
If you deploy a WAR file called `foobar.WAR`, the context path is `/foobar`; if you deploy a WAR file called `ROOT.WAR` the context path is `/`.
|
||||
|
||||
However, it is often desirable to explicitly set the context path so that information (for example, version numbers) may be included in the filename of the WAR.
|
||||
Jetty allows the context Path of a WAR file to be set internally (by the WAR itself) or externally (by the deployer of the WAR).
|
||||
|
||||
|
|
@ -213,7 +213,8 @@ To set the contextPath from within the WAR file, you can include a `WEB-INF/jett
|
|||
</Configure>
|
||||
----
|
||||
|
||||
Alternately, to configure the classpath externally without the need to modify the WAR file itself, instead of allowing the WAR file to be discovered by the deployer, an IoC XML file may be deployed that both sets the context path and declares the WAR file that it applies to:
|
||||
Alternately, you can configure the classpath externally without the need to modify the WAR file itself.
|
||||
Instead of allowing the WAR file to be discovered by the deployer, an IoC XML file may be deployed that both sets the context path and declares the WAR file that it applies to:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -230,39 +231,11 @@ Alternately, to configure the classpath externally without the need to modify th
|
|||
|
||||
An example of setting the context path is included with the Jetty distribution in `$JETTY_HOME/webapps/test.xml`.
|
||||
|
||||
===== Setting an Authentication Realm
|
||||
|
||||
The authentication method and realm name for a standard web application may be set in the `web.xml` deployment descriptor with elements like:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
...
|
||||
<login-config>
|
||||
<auth-method>BASIC</auth-method>
|
||||
<realm-name>Test Realm</realm-name>
|
||||
</login-config>
|
||||
...
|
||||
----
|
||||
|
||||
This example declares that the BASIC authentication mechanism will be used with credentials validated against a realm called "Test Realm."
|
||||
However the standard does not describe how the realm itself is implemented or configured.
|
||||
In Jetty, there are several realm implementations (called LoginServices) and the simplest of these is the HashLoginService, which can read usernames and credentials from a Java properties file.
|
||||
|
||||
To configure an instance of HashLoginService that matches the "Test Realm" configured above, the following `$JETTY_HOME/etc/test-realm.xml` IoC XML file should be passed on the command line or set in `start.ini`.
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/test-realm.xml[]
|
||||
----
|
||||
|
||||
This creates and configures the LoginService as an aggregate bean on the server.
|
||||
When a web application is deployed that declares a realm called "Test Realm," the server beans are searched for a matching Login Service.
|
||||
|
||||
[[quickstart-config-deployer]]
|
||||
===== Web Application Deployment
|
||||
|
||||
Jetty is capable of deploying a variety of Web Application formats.
|
||||
This is accomplished via scans of the `${jetty.home}/webapps` directory for contexts to deploy.
|
||||
This is accomplished via scans of the `${jetty.base}/webapps` directory for contexts to deploy.
|
||||
|
||||
A Context can be any of the following:
|
||||
|
||||
|
|
@ -282,10 +255,36 @@ The new WebAppProvider will attempt to avoid double deployments during the direc
|
|||
|
||||
____
|
||||
[NOTE]
|
||||
In prior versions of Jetty there was a separate ContextDeployer that provided the XML based deployment, the ContextDeployer no longer exists starting in Jetty9 and its functionality has been merged with the new link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] to avoid several double deployment scenarios that are possible.
|
||||
In prior versions of Jetty there was a separate ContextDeployer that provided XML-based deployment. As of Jetty 9 the ContextDeployer no longer exists and its functionality has been merged with the new link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] to avoid double deployment scenarios.
|
||||
____
|
||||
|
||||
A Context is an instance of ContextHandler that aggregates other handlers with common resources for handling HTTP requests (such as resource base, class loader, configuration attributes).
|
||||
A standard web application is a specialized instance of a context (called a WebAppContext) that uses standard layouts and `web.xml` deployment descriptors to configure the context.
|
||||
//A Context is an instance of ContextHandler that aggregates other handlers with common resources for handling HTTP requests (such as resource base, class loader, configuration attributes).
|
||||
//A standard web application is a specialized instance of a context (called a WebAppContext) that uses standard layouts and `web.xml` deployment descriptors to configure the context.
|
||||
|
||||
===== Setting an Authentication Realm
|
||||
|
||||
The authentication method and realm name for a standard web application may be set in the `web.xml` deployment descriptor with elements like:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
...
|
||||
<login-config>
|
||||
<auth-method>BASIC</auth-method>
|
||||
<realm-name>Test Realm</realm-name>
|
||||
</login-config>
|
||||
...
|
||||
----
|
||||
|
||||
This example declares that the BASIC authentication mechanism will be used with credentials validated against a realm called "Test Realm."
|
||||
However the standard does not describe how the realm itself is implemented or configured.
|
||||
In Jetty, there are several realm implementations (called LoginServices) and the simplest of these is the HashLoginService, which can read usernames and credentials from a Java properties file.
|
||||
|
||||
To configure an instance of HashLoginService that matches the "Test Realm" configured above, the following `$JETTY_BASE/etc/test-realm.xml` IoC XML file should be passed on the command line or set in `start.ini` or `start.d/server.ini`.
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/test-realm.xml[]
|
||||
----
|
||||
|
||||
This creates and configures the LoginService as an aggregate bean on the server.
|
||||
When a web application is deployed that declares a realm called "Test Realm," the server beans are searched for a matching Login Service.
|
||||
|
|
|
|||
|
|
@ -15,9 +15,9 @@
|
|||
// ========================================================================
|
||||
|
||||
[[quick-start-getting-started]]
|
||||
== Using Jetty Introduction
|
||||
== Using Jetty
|
||||
|
||||
You can use Jetty in many different ways, ranging from embedding Jetty in applications, launching it from different build systems, from different JVM-based languages, or as a standalone distribution.
|
||||
You can use Jetty in many different ways ranging from embedding Jetty in applications, launching it from different build systems, from different JVM-based languages, or as a standalone distribution.
|
||||
This guide covers the latter, a standalone distribution suitable for deploying web applications.
|
||||
|
||||
include::jetty-installing.adoc[]
|
||||
|
|
|
|||
|
|
@ -17,22 +17,21 @@
|
|||
[[quickstart-deploying-webapps]]
|
||||
=== Deploying Web Applications
|
||||
|
||||
Jetty server instances that configure the deploy module will have a web application deployer that hot deploys files found in the `webapps` directory.
|
||||
Standard WAR files and jetty configuration files that you place in the `webapps` directory are hot deployed to the server with the following conventions:
|
||||
Jetty server instances that configure the deploy module will have a web application deployer that link:#hot-deployment[hot deploys] files found in the `webapps` directory.
|
||||
Standard WAR files and Jetty configuration files that are placed in the `webapps` directory are hot deployed to the server with the following conventions:
|
||||
|
||||
* A directory called `example/` is deployed as a standard web application if it contains a `WEB-INF/` subdirectory, otherwise it is deployed as context of static content.
|
||||
The context path is `/example` (that is, `http://localhost:8080/example/`) unless the base name is ROOT (case insensitive), in which case the context path is /.
|
||||
If the directory name ends with ".d" it is ignored (but may be used by explicit configuration).
|
||||
* A file called `example.war` is deployed as a standard web application with the context path `/example` (that is,
|
||||
`http://localhost:8080/example/`).
|
||||
If the base name is `ROOT` (case insensitive), the context path is /.
|
||||
If ` example.war` and `example/` exist, only the WAR is deployed (which may use the directory as an
|
||||
unpack location).
|
||||
If the base name is `ROOT` (case insensitive), the context path is `/`.
|
||||
If `example.war` and `example/` exist, only the WAR is deployed (which may use the directory as an unpack location).
|
||||
* An XML file like `example.xml` is deployed as a context whose configuration is defined by the XML.
|
||||
The configuration itself must set the context path.
|
||||
If `example.xml` and `example.war` exist, only the XML is deployed (which may use the WAR in its configuration).
|
||||
If `example.xml` and `example.war` exists, only the XML is deployed (which may use the WAR in its configuration).
|
||||
|
||||
If you have a standard web application, you can hot deploy it into Jetty by copying it into the ` webapps` directory.
|
||||
If you have a standard web application, you can hot deploy it into Jetty by copying it into the `webapps` directory.
|
||||
|
||||
==== Jetty Demonstration Web Applications
|
||||
|
||||
|
|
@ -41,14 +40,13 @@ The demo-base/webapps directory contains the following deployable and auxiliary
|
|||
`ROOT/`::
|
||||
A directory of static content that is deployed to the root context / due to it's name.
|
||||
Contains the Jetty demo welcome page.
|
||||
`test.d`::
|
||||
A directory containing additional configuration files used by `test.xml` to inject extra configuration into `test.war`.
|
||||
`test.xml`::
|
||||
A context configuration file that configures and deploys `test.war.`
|
||||
The additional configuration includes the context path as well as setting additional descriptors found in the test.d directory.
|
||||
The additional configuration includes the context path as well as setting additional descriptors found in the `test.d` directory.
|
||||
`test.war`::
|
||||
The demonstration web application that `is` configured and deployed by
|
||||
test.xml.
|
||||
`test.d`::
|
||||
A directory containing additional configuration files used by `test.xml` to inject extra configuration into `test.war`.
|
||||
The demonstration web application that is configured and deployed by `test.xml`.
|
||||
`async-rest.war`::
|
||||
A web application demonstration of asynchronous REST to eBay, automatically deployed to /async-rest based on the file name.
|
||||
`test-jaas.war`::
|
||||
|
|
@ -62,12 +60,11 @@ The demo-base/webapps directory contains the following deployable and auxiliary
|
|||
A context configuration file that configures `test-jndi.war`.
|
||||
Additional configuration includes defining objects in the naming space that can be referenced from the webapp.
|
||||
`test-spec.war`::
|
||||
A demonstration web application that shows the use of annotations, fragments, ServletContainerInitializers and other Servlet Specification 3.0/3.1 features.
|
||||
A demonstration web application that shows the use of annotations, fragments, `ServletContainerInitializers` and other Servlet Specification 3.0/3.1 features.
|
||||
`test-spec.xml`::
|
||||
A context configuration file that configures `test-spec.war`.
|
||||
Additional configuration includes setting up some objects in the naming space that can be referenced by
|
||||
annotations.
|
||||
Additional configuration includes setting up some objects in the naming space that can be referenced by annotations.
|
||||
`xref-proxy.war`::
|
||||
A demonstration web application that uses a transparent proxy to serve the Jetty src link:{JXURL}/[xref] from the Eclipse Jetty http://www.eclipse.org/jetty[website].
|
||||
A demonstration web application that uses a transparent proxy to serve the Jetty source link:{JXURL}/[xref] from the http://www.eclipse.org/jetty[Eclipse Jetty website].
|
||||
`example-moved.xml`::
|
||||
A demonstration context configuration file that shows how to use the link:#moved-context-handler[MovedContextHandler] to redirect from one path to another.
|
||||
A demonstration context configuration file that shows how to use the link:#moved-context-handler[`MovedContextHandler`] to redirect from one path to another.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,6 @@
|
|||
==== Downloading the Jetty Distribution
|
||||
|
||||
The standalone Jetty distribution is available for download from the Eclipse Foundation:
|
||||
|
||||
____
|
||||
*Jetty*
|
||||
http://download.eclipse.org/jetty
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ To start Jetty on the default port of 8080, run the following command:
|
|||
----
|
||||
> cd $JETTY_HOME
|
||||
> java -jar start.jar
|
||||
|
||||
2015-06-04 10:50:44.806:INFO::main: Logging initialized @334ms
|
||||
2015-06-04 10:50:44.858:WARN:oejs.HomeBaseWarning:main: This instance of Jetty is not running from a separate {jetty.base} directory, this is not recommended. See documentation at http://www.eclipse.org/jetty/documentation/current/startup.html
|
||||
2015-06-04 10:50:44.995:INFO:oejs.Server:main: jetty-9.3.0.v20150601
|
||||
|
|
@ -45,6 +46,7 @@ Within the standard jetty distribution there is the `demo-base` directory, which
|
|||
----
|
||||
> cd $JETTY_HOME/demo-base/
|
||||
> java -jar $JETTY_HOME/start.jar
|
||||
|
||||
2015-06-04 10:55:24.161:INFO::main: Logging initialized @308ms
|
||||
2015-06-04 10:55:24.431:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
|
||||
2015-06-04 10:55:24.434:INFO:oejs.Server:main: jetty-9.3.0.v20150601
|
||||
|
|
@ -68,7 +70,7 @@ Within the standard jetty distribution there is the `demo-base` directory, which
|
|||
2015-06-04 10:55:26.270:INFO:oejs.Server:main: Started @2417ms
|
||||
----
|
||||
|
||||
You can see this demo server by pointing a browser at link:http://localhost:8080[], will now show a welcome page and several demo/test web applications.
|
||||
You can visit this demo server by pointing a browser at link:http://localhost:8080[], which will now show a welcome page and several demo/test web applications.
|
||||
|
||||
____
|
||||
[WARNING]
|
||||
|
|
@ -82,15 +84,20 @@ You can see the configuration of the demo-base by using the following commands:
|
|||
> cd $JETTY_HOME/demo-base/
|
||||
> java -jar $JETTY_HOME/start.jar --list-modules
|
||||
...
|
||||
|
||||
> java -jar %JETTY_HOME/start.jar --list-config
|
||||
...
|
||||
----
|
||||
|
||||
The `--list-modules` command will return a complete list of available and enabled modules for the server.
|
||||
It will also display the location of the modules, how and in what order they are implemented, dependent modules, and associated jar files.
|
||||
The `--list-config` command displays a trove of information about the server including the Java and Jetty environments, the configuration order, any JVM arguments or System Properties set, general server properties, a full listing of the Jetty server class path, and active Jetty XML files.
|
||||
|
||||
[[creating-jetty-base]]
|
||||
==== Creating a new Jetty Base
|
||||
|
||||
The `demo-base` directory described above is an example of the link:#startup-base-and-home[jetty.base] mechanism added in Jetty 9.1.
|
||||
A jetty base allows the configuration and web applications of a server instance to be stored separately from the jetty distribution, so that upgrades can be done with minimal disruption.
|
||||
A Jetty base directory allows the configuration and web applications of a server instance to be stored separately from the Jetty distribution, so that upgrades can be done with minimal disruption.
|
||||
Jetty's default configuration is based on two properties:
|
||||
|
||||
jetty.home::
|
||||
|
|
@ -106,7 +113,7 @@ The `jetty.home` and `jetty.base` properties may be explicitly set on the comman
|
|||
> java -jar $JETTY_HOME/start.jar
|
||||
----
|
||||
|
||||
The following commands: create a new base directory; enables a HTTP connector and the web application deployer; copies a demo webapp to be deployed:
|
||||
The following commands create a new base directory, enables both the HTTP connector and the web application deployer modules, and copies a demo webapp to be deployed:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -114,12 +121,14 @@ The following commands: create a new base directory; enables a HTTP connector an
|
|||
> mkdir $JETTY_BASE
|
||||
> cd $JETTY_BASE
|
||||
> java -jar $JETTY_HOME/start.jar
|
||||
|
||||
WARNING: Nothing to start, exiting ...
|
||||
|
||||
Usage: java -jar start.jar [options] [properties] [configs]
|
||||
java -jar start.jar --help # for more information
|
||||
|
||||
> java -jar $JETTY_HOME/start.jar --add-to-startd=http,deploy
|
||||
|
||||
INFO: server initialised (transitively) in ${jetty.base}/start.d/server.ini
|
||||
INFO: http initialised in ${jetty.base}/start.d/http.ini
|
||||
INFO: security initialised (transitively) in ${jetty.base}/start.d/security.ini
|
||||
|
|
@ -128,8 +137,10 @@ INFO: webapp initialised (transitively) in ${jetty.base}/start.d/webapp
|
|||
INFO: deploy initialised in ${jetty.base}/start.d/deploy.ini
|
||||
MKDIR: ${jetty.base}/webapps
|
||||
INFO: Base directory was modified
|
||||
|
||||
> cp $JETTY_HOME/demo-base/webapps/async-rest.war webapps/ROOT.war
|
||||
> java -jar $JETTY_HOME/start.jar
|
||||
|
||||
2015-06-04 11:10:16.286:INFO::main: Logging initialized @274ms
|
||||
2015-06-04 11:10:16.440:INFO:oejs.Server:main: jetty-9.3.0.v20150601
|
||||
2015-06-04 11:10:16.460:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/mybase/webapps/] at interval 1
|
||||
|
|
@ -153,7 +164,7 @@ You can configure Jetty to run on a different port by setting the `jetty.http.po
|
|||
----
|
||||
|
||||
Alternatively, property values can be added to the effective command line built from either the `start.ini` file or `start.d/http.ini` files.
|
||||
By default, the jetty distribution defines the jetty.http.port property in the `start.d/http.ini` file, which may be edited to set another value.
|
||||
By default, the Jetty distribution defines the `jetty.http.port` property in the `start.d/http.ini` file, which may be edited to set another value.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
|
|
@ -164,26 +175,28 @@ The configuration by properties works via the following chain:
|
|||
* The modules/http.mod file defines the http module which specifies the etc/jetty-http.xml configuration file and the template ini properties it uses.
|
||||
* The jetty.http.port property is used by the Property XML element in etc/jetty.http.xml to inject the ServerConnector instance with the port.
|
||||
|
||||
For more information see the link:#quickstart-config[Quickstart Configuration Guide] and link:#configuring-connectors[Configuring Connectors].
|
||||
For more information see the link:#quick-start-configure[Quickstart Configuration Guide] and link:#configuring-connectors[Configuring Connectors].
|
||||
--
|
||||
____
|
||||
|
||||
[[quickstart-starting-https]]
|
||||
==== Adding SSL for HTTPS & HTTP2
|
||||
|
||||
To add the HTTPS connector to a jetty configuration, the https module can be activated by the following command:
|
||||
To add HTTPS and HTTP2 connectors to a Jetty configuration, the modules can be activated by the following command:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
> java -jar $JETTY_HOME/start.jar --add-to-startd=https,http2
|
||||
[...]
|
||||
|
||||
> java -jar $JETTY_HOME/start.jar
|
||||
[...]
|
||||
|
||||
2015-06-04 13:52:01.933:INFO:oejs.ServerConnector:main: Started ServerConnector@6f1fba17{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
|
||||
[...]
|
||||
----
|
||||
|
||||
The --add-to-startd command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:
|
||||
The `--add-to-startd` command sets up the effective command line in the ini files to run an ssl connection that supports the HTTPS and HTTP2 protocols as follows:
|
||||
|
||||
* creates `start.d/ssl.ini` that configures an SSL connector (eg port, keystore etc.) by adding `etc/jetty-ssl.xml` and `etc/jetty-ssl-context.xml` to the effective command line.
|
||||
* creates `start.d/alpn.ini` that configures protocol negotiation on the SSL connector by adding `etc/jetty-alpn.xml` to the effective command line.
|
||||
|
|
@ -193,7 +206,7 @@ The --add-to-startd command sets up the effective command line in the ini files
|
|||
|
||||
____
|
||||
[NOTE]
|
||||
If a single start.ini file is preferred over individual `start.d/*.ini` files, then the option --add-to-start=module may be used to append the module activation to the start.ini file rather than create a file in start.d
|
||||
If a single `start.ini` file is preferred over individual `start.d/*.ini` files, then the option --add-to-start=module may be used to append the module activation to the start.ini file rather than create a file in start.d
|
||||
____
|
||||
|
||||
[[quickstart-changing-https-port]]
|
||||
|
|
@ -208,12 +221,12 @@ You can configure the SSL connector to run on a different port by setting the `j
|
|||
----
|
||||
|
||||
Alternatively, property values can be added to the effective command line built from the `start.ini` file and `start.d/*.ini` files.
|
||||
If you used the --add-to-startd command to enable https, then you can edit this property in the `start.d/https.ini` file.
|
||||
If you used --add-to-start command, then you can edit this property in the start.ini file.
|
||||
If you used the `--add-to-startd` command to enable HTTPS , then you can edit this property in the `start.d/https.ini` file.
|
||||
If you used `--add-to-start` command, then you can edit this property in the `start.ini` file.
|
||||
|
||||
==== More start.jar options
|
||||
|
||||
The job of the `start.jar` is to interpret the command line, `start.ini` and `start.d` to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism.
|
||||
The job of the `start.jar` is to interpret the command line, `start.ini` and `start.d` directory (and associated .ini files) to build a Java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism.
|
||||
The `start.jar` mechanism has many options which are documented in the xref:startup[] administration section and you can see them in summary by using the command:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
|
|||
Loading…
Reference in New Issue