Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Now the documentation has been migrated to Antora, so there is no need for the Java Asciidoctor plugin, and the directories that previously held the documentation using the Asciidoctor Maven plugin. 

Renamed the `version` attribute to `jetty-version`, and now using the POM value, rather than a hard-coded one.

Removed references to Asciidoctor from the main POM.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2024-08-03 14:43:53 +02:00
parent 84d0574ab6
commit e1d03b4c68
401 changed files with 85 additions and 45333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
documentation/jetty-asciidoctor-extensions/pom.xml
View File

@ -1,44 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.jetty.documentation</groupId>
<artifactId>documentation</artifactId>
<version>12.0.13-SNAPSHOT</version>
</parent>
<artifactId>jetty-asciidoctor-extensions</artifactId>
<packaging>jar</packaging>
<name>Documentation :: AsciiDoctor Extensions</name>
<properties>
<bundle-symbolic-name>${project.groupId}.asciidoctor.extensions</bundle-symbolic-name>
</properties>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<exclusions>
<exclusion>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
</exclusion>
<!--
the pom of this dependencies has an unknown repository protocol
https://issues.apache.org/jira/browse/MENFORCER-393
it fail enforcer plugin
-->
<exclusion>
<groupId>org.jruby</groupId>
<artifactId>jruby-stdlib</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.tests</groupId>
<artifactId>jetty-testers</artifactId>
<scope>compile</scope>
</dependency>
</dependencies>
</project>

235
documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JavadocIncludeExtension.java
View File

@ -1,235 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
package org.eclipse.jetty.docs;
import java.io.StringReader;
import java.io.StringWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Deque;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.ast.Document;
import org.asciidoctor.extension.IncludeProcessor;
import org.asciidoctor.extension.PreprocessorReader;
import org.asciidoctor.jruby.extension.spi.ExtensionRegistry;
import org.xml.sax.InputSource;
/**
* <p>Asciidoctor <em>include</em> extension that includes into
* the document the output produced by an XSL transformation of
* parts of the javadoc of a file.</p>
* <p>Example usage in an Asciidoc page:</p>
* <pre>
* include::javadoc[file=Source.java,xsl=source.xsl,tags=docs]
* </pre>
* <p>Available configuration parameters are:</p>
* <dl>
* <dt>file</dt>
* <dd>Mandatory, specifies the file to read the javadoc from, relative to the root of the Jetty Project source.</dd>
* <dt>xsl</dt>
* <dd>Mandatory, specifies the XSL file to use to transform the javadoc, relative to the root of the documentation source.</dd>
* <dt>tags</dt>
* <dd>Optional, specifies the name of the tagged regions of the javadoc to include.</dd>
* <dt>replace</dt>
* <dd>Optional, specifies a comma-separated pair where the first element is a regular
* expression and the second is the string replacement, applied to each included line.</dd>
* </dl>
* <p>An example javadoc could be:</p>
* <pre>
* &#47;**
* * &lt;p&gt;Class description.&lt;/p&gt;
* * &lt;!-- tag::docs --&gt;
* * &lt;p&gt;Parameters&lt;/p&gt;
* * &lt;table&gt;
* * &lt;tr&gt;
* * &lt;td&gt;param&lt;/td&gt;
* * &lt;td&gt;value&lt;/td&gt;
* * &lt;/tr&gt;
* * &lt;/table&gt;
* * &lt;!-- end::docs --&gt;
* *&#47;
* public class A
* {
* }
* </pre>
* <p>The javadoc lines included in the tagged region "docs" (between {@code tag::docs} and {@code end::docs})
* will be stripped of the asterisk at the beginning of the line and wrapped
* into a {@code &lt;root&gt;} element, so that it becomes a well-formed XML document.</p>
* <p>Each line of the XML document is then passed through the regular expression specified by the {@code replace}
* parameter (if any), and then transformed using the XSL file specified by the {@code xsl} parameter,
* which should produce a valid Asciidoc block which is then included in the Asciidoc documentation page.</p>
*/
public class JavadocIncludeExtension implements ExtensionRegistry
{
@Override
public void register(Asciidoctor asciidoctor)
{
asciidoctor.javaExtensionRegistry().includeProcessor(JavadocIncludeExtension.JavadocIncludeProcessor.class);
}
public static class JavadocIncludeProcessor extends IncludeProcessor
{
private static final Pattern JAVADOC_INITIAL_ASTERISK = Pattern.compile("^\\s*\\*\\s*(.*)$");
private static final Pattern JAVADOC_INLINE_CODE = Pattern.compile("\\{@code ([^\\}]+)\\}");
@Override
public boolean handles(String target)
{
return "javadoc".equals(target);
}
@Override
public void process(Document document, PreprocessorReader reader, String target, Map<String, Object> attributes)
{
try
{
// Document attributes are converted by Asciidoctor to lowercase.
Path jettyDocsPath = Path.of((String)document.getAttribute("project-basedir"));
Path jettyRoot = jettyDocsPath.resolve("../..").normalize();
String file = (String)attributes.get("file");
if (file == null)
throw new IllegalArgumentException("Missing 'file' attribute");
Path filePath = jettyRoot.resolve(file.trim());
String xsl = (String)attributes.get("xsl");
if (xsl == null)
throw new IllegalArgumentException("Missing 'xsl' attribute");
Path xslPath = jettyDocsPath.resolve(xsl.trim());
List<Tag> tagList = new ArrayList<>();
String tags = (String)attributes.get("tags");
if (tags != null)
{
for (String tag : tags.split(","))
{
tag = tag.trim();
boolean exclude = tag.startsWith("!");
if (exclude)
tag = tag.substring(1);
if (tag.isEmpty())
throw new IllegalArgumentException("Invalid tag in 'tags' attribute: " + tags);
tagList.add(new Tag(tag, exclude));
}
}
String replace = (String)attributes.get("replace");
List<String> contentLines = new ArrayList<>();
contentLines.add("<root>");
Iterator<String> lines = Files.lines(filePath, StandardCharsets.UTF_8).iterator();
Deque<Tag> tagStack = new ArrayDeque<>();
while (lines.hasNext())
{
String line = lines.next();
// Strip the initial Javadoc asterisk.
Matcher matcher = JAVADOC_INITIAL_ASTERISK.matcher(line);
if (matcher.matches())
line = matcher.group(1);
// Convert {@code X} into <code>X</code>
line = JAVADOC_INLINE_CODE.matcher(line).replaceAll("<code>$1</code>");
boolean keepLine = tagList.isEmpty() || tagList.stream().allMatch(tag -> tag.exclude);
if (tagStack.isEmpty())
{
for (Tag tag : tagList)
{
if (line.contains("tag::" + tag.name))
tagStack.push(tag);
}
}
else
{
Tag currentTag = tagStack.peek();
keepLine = !currentTag.exclude;
if (line.contains("end::" + currentTag.name))
{
tagStack.pop();
keepLine = false;
}
}
if (keepLine)
{
if (replace == null)
contentLines.add(line);
else
contentLines.addAll(replace(line, replace));
}
}
contentLines.add("</root>");
String content = String.join("\n", contentLines);
// Run the XML stylesheet over the remaining lines.
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
org.w3c.dom.Document xml = builder.parse(new InputSource(new StringReader(content)));
Transformer transformer = TransformerFactory.newInstance().newTransformer(new StreamSource(xslPath.toFile()));
StringWriter output = new StringWriter(content.length());
transformer.transform(new DOMSource(xml), new StreamResult(output));
String asciidoc = output.toString();
asciidoc = Arrays.stream(asciidoc.split("\n")).map(String::stripLeading).collect(Collectors.joining("\n"));
reader.pushInclude(asciidoc, "javadoc", target, 1, attributes);
}
catch (Throwable x)
{
reader.pushInclude(x.toString(), "javadoc", target, 1, attributes);
x.printStackTrace();
}
}
private List<String> replace(String line, String replace)
{
// Format is: (regexp,replacement).
String[] parts = replace.split(",");
String regExp = parts[0];
String replacement = parts[1].replace("\\n", "\n");
return List.of(line.replaceAll(regExp, replacement).split("\n"));
}
private static class Tag
{
private final String name;
private final boolean exclude;
private Tag(String name, boolean exclude)
{
this.name = name;
this.exclude = exclude;
}
}
}
}

270
documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java
View File

@ -1,270 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
package org.eclipse.jetty.docs;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.ast.Document;
import org.asciidoctor.extension.IncludeProcessor;
import org.asciidoctor.extension.PreprocessorReader;
import org.asciidoctor.jruby.extension.spi.ExtensionRegistry;
import org.eclipse.jetty.tests.testers.JettyHomeTester;
/**
* <p>Asciidoctor <em>include</em> extension that includes into
* the document the output produced by starting a Jetty server.</p>
* <p>Example usage in an Asciidoc page:</p>
* <pre>
* include::jetty[setupArgs="--add-modules=http,deploy,demo-simple",highlight="WebAppContext"]
* </pre>
* <p>Available configuration parameters are:</p>
* <dl>
* <dt>setupModules</dt>
* <dd>Optional, specifies a comma-separated list of files to copy to {@code $JETTY_BASE/modules}.</dd>
* <dt>setupArgs</dt>
* <dd>Optional, specifies the arguments to use in a Jetty server <em>setup</em> run.
* If missing, no Jetty server <em>setup</em> run will be executed.
* The output produced by this run is ignored.</dd>
* <dt>args</dt>
* <dd>Optional, specifies the arguments to use in a Jetty server run.
* If missing, a Jetty server run will be executed with no arguments.
* The output produced by this run is included in the Asciidoc document.</dd>
* <dt>replace</dt>
* <dd>Optional, specifies a comma-separated pair where the first element is a regular
* expression and the second is the string replacement.</dd>
* <dt>delete</dt>
* <dd>Optional, specifies a regular expression that when matched deletes the line</dd>
* <dt>highlight</dt>
* <dd>Optional, specifies a regular expression that matches lines that should be highlighted.
* If missing, no line will be highlighted.
* If the regular expression contains capturing groups, only the text matching
* the groups is highlighted, not the whole line.
* </dd>
* <dt>callouts</dt>
* <dd>Optional, specifies a comma-separated pair where the first element is a callout
* pattern, and the second element is a comma-separated list of regular expressions,
* each matching a single line, that get a callout added at the end of the line.</dd>
* </dl>
*
* @see JettyHomeTester
*/
public class JettyIncludeExtension implements ExtensionRegistry
{
public void register(Asciidoctor asciidoctor)
{
asciidoctor.javaExtensionRegistry().includeProcessor(JettyIncludeProcessor.class);
}
public static class JettyIncludeProcessor extends IncludeProcessor
{
@Override
public boolean handles(String target)
{
return "jetty".equals(target);
}
@Override
public void process(Document document, PreprocessorReader reader, String target, Map<String, Object> attributes)
{
try
{
String jettyVersion = (String)document.getAttribute("project-version");
// Document attributes are converted by Asciidoctor to lowercase.
Path jettyDocsPath = Path.of((String)document.getAttribute("project-basedir"));
Path jettyHome = jettyDocsPath.resolve("target/jetty-home-" + jettyVersion).normalize();
JettyHomeTester jetty = JettyHomeTester.Builder.newInstance()
.jettyHome(jettyHome)
.mavenLocalRepository((String)document.getAttribute("maven-local-repo"))
.build();
String setupModules = (String)attributes.get("setupModules");
if (setupModules != null)
{
Path jettyBaseModules = jetty.getJettyBase().resolve("modules");
Files.createDirectories(jettyBaseModules);
String[] modules = setupModules.split(",");
for (String module : modules)
{
Path sourcePath = jettyDocsPath.resolve(module.trim());
Files.copy(sourcePath, jettyBaseModules.resolve(sourcePath.getFileName()));
}
}
String setupArgs = (String)attributes.get("setupArgs");
if (setupArgs != null)
{
try (JettyHomeTester.Run setupRun = jetty.start(setupArgs.split(" ")))
{
setupRun.awaitFor(15, TimeUnit.SECONDS);
}
}
String args = (String)attributes.get("args");
args = args == null ? "" : args + " ";
args += jettyHome.resolve("etc/jetty-halt.xml");
try (JettyHomeTester.Run run = jetty.start(args.split(" ")))
{
run.awaitFor(15, TimeUnit.SECONDS);
String output = captureOutput(document, attributes, run);
reader.pushInclude(output, "jettyHome_run", target, 1, attributes);
}
}
catch (Throwable x)
{
reader.pushInclude(x.toString(), "jettyHome_run", target, 1, attributes);
x.printStackTrace();
}
}
private String captureOutput(Document document, Map<String, Object> attributes, JettyHomeTester.Run run)
{
Stream<String> lines = run.getLogs().stream()
.map(line -> redact(line, System.getProperty("java.home"), "/path/to/java.home"))
.map(line -> redact(line, run.getConfig().getMavenLocalRepository(), "/path/to/maven.repository"))
.map(line -> redact(line, run.getConfig().getJettyHome().toString(), "/path/to/jetty.home"))
.map(line -> redact(line, run.getConfig().getJettyBase().toString(), "/path/to/jetty.base"))
.map(line -> regexpRedact(line, "(^| )[^ ]+/etc/jetty-halt\\.xml", ""))
.map(line -> redact(line, (String)document.getAttribute("project-version"), (String)document.getAttribute("version")));
lines = replace(lines, (String)attributes.get("replace"));
lines = delete(lines, (String)attributes.get("delete"));
lines = denoteLineStart(lines);
lines = highlight(lines, (String)attributes.get("highlight"));
lines = callouts(lines, (String)attributes.get("callouts"));
return lines.collect(Collectors.joining(System.lineSeparator()));
}
private String redact(String line, String target, String replacement)
{
if (target != null && replacement != null)
return line.replace(target, replacement);
return line;
}
private String regexpRedact(String line, String regexp, String replacement)
{
if (regexp != null && replacement != null)
return line.replaceAll(regexp, replacement);
return line;
}
private Stream<String> replace(Stream<String> lines, String replace)
{
if (replace == null)
return lines;
// Format is: (regexp,replacement).
String[] parts = replace.split(",");
String regExp = parts[0];
String replacement = parts[1].replace("\\n", "\n");
return lines.flatMap(line -> Stream.of(line.replaceAll(regExp, replacement).split("\n")));
}
private Stream<String> delete(Stream<String> lines, String delete)
{
if (delete == null)
return lines;
Pattern regExp = Pattern.compile(delete);
return lines.filter(line -> !regExp.matcher(line).find());
}
private Stream<String> denoteLineStart(Stream<String> lines)
{
// Matches lines that start with a date such as "2020-01-01 00:00:00.000:".
Pattern regExp = Pattern.compile("(^\\d{4}[^:]+:[^:]+:[^:]+:)");
return lines.map(line ->
{
Matcher matcher = regExp.matcher(line);
if (!matcher.find())
return line;
return "**" + matcher.group(1) + "**" + line.substring(matcher.end(1));
});
}
private Stream<String> highlight(Stream<String> lines, String highlight)
{
if (highlight == null)
return lines;
Pattern regExp = Pattern.compile(highlight);
return lines.map(line ->
{
Matcher matcher = regExp.matcher(line);
if (!matcher.find())
return line;
int groupCount = matcher.groupCount();
// No capturing groups, highlight the whole line.
if (groupCount == 0)
return "##" + line + "##";
// Highlight the capturing groups.
StringBuilder result = new StringBuilder(line.length() + 4 * groupCount);
int start = 0;
for (int groupIndex = 1; groupIndex <= groupCount; ++groupIndex)
{
int matchBegin = matcher.start(groupIndex);
result.append(line, start, matchBegin);
result.append("##");
int matchEnd = matcher.end(groupIndex);
result.append(line, matchBegin, matchEnd);
result.append("##");
start = matchEnd;
}
result.append(line, start, line.length());
return result.toString();
});
}
private Stream<String> callouts(Stream<String> lines, String callouts)
{
if (callouts == null)
return lines;
// Format is (prefix$Nsuffix,regExp...).
String[] parts = callouts.split(",");
String calloutPattern = parts[0];
List<Pattern> regExps = Stream.of(parts)
.skip(1)
.map(Pattern::compile)
.collect(Collectors.toList());
AtomicInteger index = new AtomicInteger();
return lines.map(line ->
{
int regExpIndex = index.get();
if (regExpIndex == regExps.size())
return line;
Pattern regExp = regExps.get(regExpIndex);
if (!regExp.matcher(line).find())
return line;
int calloutIndex = index.incrementAndGet();
return line + calloutPattern.replace("$N", String.valueOf(calloutIndex));
});
}
}
}

2
documentation/jetty-asciidoctor-extensions/src/main/resources/META-INF/services/org.asciidoctor.jruby.extension.spi.ExtensionRegistry
View File

@ -1,2 +0,0 @@
org.eclipse.jetty.docs.JettyIncludeExtension
org.eclipse.jetty.docs.JavadocIncludeExtension

437
documentation/jetty-documentation/pom.xml
View File

@ -1,437 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.jetty.documentation</groupId>
<artifactId>documentation</artifactId>
<version>12.0.13-SNAPSHOT</version>
</parent>
<artifactId>jetty-documentation</artifactId>
<packaging>jar</packaging>
<name>Documentation :: Guides</name>
<properties>
<bundle-symbolic-name>${project.groupId}</bundle-symbolic-name>
<jacoco.skip>true</jacoco.skip>
<javadoc.skip>true</javadoc.skip>
<maven.deploy.skip>true</maven.deploy.skip>
<sources.skip>true</sources.skip>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-ee10-bom</artifactId>
<version>${project.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>javadoc</artifactId>
<version>${project.version}</version>
<classifier>javadoc</classifier>
<type>jar</type>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-alpn-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-client</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-infinispan-common</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-infinispan-embedded-query</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-infinispan-remote-query</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-io</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-jmx</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-nosql</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-rewrite</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-unixdomain-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-util-ajax</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-ee10-servlet</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-ee10-servlets</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.ee10</groupId>
<artifactId>jetty-ee10-webapp</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.ee10.websocket</groupId>
<artifactId>jetty-ee10-websocket-jakarta-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.fcgi</groupId>
<artifactId>jetty-fcgi-client</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.gcloud</groupId>
<artifactId>jetty-gcloud-session-manager</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.http2</groupId>
<artifactId>jetty-http2-client-transport</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.http2</groupId>
<artifactId>jetty-http2-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.http3</groupId>
<artifactId>jetty-http3-client-transport</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.http3</groupId>
<artifactId>jetty-http3-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.memcached</groupId>
<artifactId>jetty-memcached-sessions</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.websocket</groupId>
<artifactId>jetty-websocket-jetty-client</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.websocket</groupId>
<artifactId>jetty-websocket-jetty-server</artifactId>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-slf4j-impl</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
<build>
<resources>
<!-- include something so that a asciidoctor.skip won't break assembly -->
<resource>
<targetPath>${project.build.directory}/html</targetPath>
<directory>${project.basedir}/src/main/asciidoc</directory>
<includes>
<include>*.css</include>
</includes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<!-- if asciidoc generation has been skipped this will generate a assembly plugin error
so in this case just skip documentation assembly as well -->
<skipAssembly>${asciidoctor.skip}</skipAssembly>
<descriptors>
<descriptor>src/main/assembly/html.xml</descriptor>
</descriptors>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<goals>
<goal>single</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>compile-documentation-sources</id>
<goals>
<goal>compile</goal>
</goals>
<phase>compile</phase>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-javadoc-jar</id>
<goals>
<goal>copy-dependencies</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<includeGroupIds>org.eclipse.jetty</includeGroupIds>
<includeArtifactIds>javadoc</includeArtifactIds>
<classifier>javadoc</classifier>
<outputDirectory>${project.build.directory}/other-artifacts/</outputDirectory>
</configuration>
</execution>
<execution>
<id>unpack-jetty-home</id>
<goals>
<goal>unpack</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-home</artifactId>
<version>${project.version}</version>
<type>zip</type>
</artifactItem>
</artifactItems>
<outputDirectory>${project.build.directory}/</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<configuration>
<fail>false</fail>
<rules>
<requireJavaVersion>
<version>[21,)</version>
<message>[ERROR] OLD JDK [${java.version}] in use. Jetty documentation ${project.version} MUST use JDK 21 or newer</message>
</requireJavaVersion>
</rules>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<configuration>
<backend>html5</backend>
<requires>
<require>asciidoctor-diagram</require>
</requires>
<attributes>
<project-basedir>${project.basedir}</project-basedir>
<project-version>${project.version}</project-version>
<maven-local-repo>${session.repositorySession.localRepository.basedir.absolutePath}</maven-local-repo>
<version>${project.version}</version>
<prog-guide>../programming-guide/index.html</prog-guide>
<op-guide>../operations-guide/index.html</op-guide>
<javadoc-url>https://eclipse.dev/jetty/javadoc/jetty-12</javadoc-url>
</attributes>
</configuration>
<dependencies>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
<version>${apache.httpclient.version}</version>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpcore</artifactId>
<version>${apache.httpcore.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-diagram</artifactId>
<version>${asciidoctorj-diagram.version}</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.documentation</groupId>
<artifactId>jetty-asciidoctor-extensions</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
<groupId>jakarta.annotation</groupId>
<artifactId>jakarta.annotation-api</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<executions>
<execution>
<id>contribution-guide</id>
<goals>
<goal>process-asciidoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<sourceDirectory>${basedir}/src/main/asciidoc/contribution-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/contribution-guide</outputDirectory>
</configuration>
</execution>
<execution>
<id>index</id>
<goals>
<goal>process-asciidoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<sourceDirectory>src/main/asciidoc</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html</outputDirectory>
</configuration>
</execution>
<execution>
<id>old_docs</id>
<goals>
<goal>process-asciidoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<sourceDirectory>${basedir}/src/main/asciidoc/old_docs</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/old_docs</outputDirectory>
</configuration>
</execution>
<execution>
<id>operations-guide</id>
<goals>
<goal>process-asciidoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<sourceDirectory>src/main/asciidoc/operations-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/operations-guide</outputDirectory>
</configuration>
</execution>
<execution>
<id>programming-guide</id>
<goals>
<goal>process-asciidoc</goal>
</goals>
<phase>prepare-package</phase>
<configuration>
<sourceDirectory>${basedir}/src/main/asciidoc/programming-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/programming-guide</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>attach-javadoc</id>
<goals>
<goal>attach-artifact</goal>
</goals>
<phase>package</phase>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/other-artifacts/javadoc-${project.version}-javadoc.jar</file>
<type>jar</type>
<classifier>javadoc</classifier>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>jdk17-18</id>
<activation>
<jdk>[17,19)</jdk>
</activation>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<excludes>
<exclude>**/ArchitectureDocs.java</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>jdk19-20</id>
<activation>
<jdk>[19,21)</jdk>
</activation>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>${java.specification.version}</source>
<target>${java.specification.version}</target>
<release>${java.specification.version}</release>
<enablePreview>true</enablePreview>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>jdk21+</id>
<activation>
<jdk>[21,)</jdk>
</activation>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>${java.specification.version}</source>
<target>${java.specification.version}</target>
<release>${java.specification.version}</release>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

35
documentation/jetty-documentation/src/main/asciidoc/config.adoc
View File

@ -1,35 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
:author: Jetty Developers
:email: jetty-dev@eclipse.org
:revnumber: {version}
:revdate: {localdate}
:toc: left
:toclevels: 5
:idseparator: -
:sectlinks:
:sectanchors:
:source-highlighter: coderay
// Use fonts for admonitions.
:icons: font
// HTML specific directives
ifdef::backend-html5[]
:safe-mode-unsafe:
:linkcss:
endif::[]

5
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/.asciidoctorconfig
View File

@ -1,5 +0,0 @@
:ee-all: ee{8,9,10}
:ee-current: ee10
:ee-current-caps: EE 10
:experimental:
:imagesdir: images

56
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/1-introduction.adoc
View File

@ -1,56 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-intro]]
== Introduction
The Eclipse Jetty Contribution Guide targets developers and writers who want to make contributions to the Jetty project by contributing code, writing documentation, or engaging in the larger community.
[[cg-intro-mailing-lists]]
=== Mailing Lists
One of the easiest ways to get involved is via our mailing lists:
* *Jetty Users* (https://accounts.eclipse.org/mailing-list/jetty-users[jetty-users], https://www.eclipse.org/lists/jetty-users[archives]) is for discussion and questions that are of broad interest to the community of Jetty users.
* *Jetty Developers* (https://accounts.eclipse.org/mailing-list/jetty-dev[jetty-dev], https://www.eclipse.org/lists/jetty-dev[archives]) is more narrowly focused on technical topics and discussion regarding Jetty internals.
* *Jetty Announcements* (https://accounts.eclipse.org/mailing-list/jetty-announce[jetty-announce], https://www.eclipse.org/lists/jetty-announce[archives]) is for announcements about new releases and other updates from the project's maintainers.
[[cg-intro-stack-overflow]]
=== Stack Overflow
Another great resource, both for Jetty novices who need help and Jetty experts who want to contribute, is http://stackoverflow.com[StackOverflow].
In particular, the https://stackoverflow.com/questions/tagged/jetty[`jetty`] and https://stackoverflow.com/questions/tagged/embedded-jetty[`embedded-jetty`] tags see regular traffic.
[[cg-intro-filing-issues]]
=== Filing Issues
You can flag potential bugs or suggest new Jetty features on our https://github.com/jetty/jetty.project/issues[issue tracker].
Before filing a new issue, https://github.com/jetty/jetty.project/issues[check the tracker] to see if it's already been filed by someone else.
If you do file an issue, make sure to label it appropriately, as this will help the development team (and other users) find it more easily.
[[cg-intro-help-wanted]]
=== Help Wanted
If you want to contribute to Jetty but don't have a specific task or goal in mind, consider looking through our https://github.com/jetty/jetty.project/issues?q=is%3Aopen+is%3Aissue+label%3A%22Help+Wanted%22["Help Wanted" issue backlog].
These tasks range from the simple to the complex, but they're all ones we've identified as being particularly well-suited for new contributors to tackle.
[[cg-intro-commercial-support]]
=== Commercial Support
link:https://webtide.com[Webtide] is the company behind Jetty that provides services and support for the Jetty Project.
mailto:sales@webtide.com[Contact Webtide].

30
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/2-eca.adoc
View File

@ -1,30 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-eca]]
== The Eclipse Contributor Agreement
Since Jetty is a member of the Eclipse Foundation, all contributors must first sign the https://www.eclipse.org/legal/ECA.php[Eclipse Contributor Agreement (ECA)] before their code changes can be merged into source.
The Eclipse Foundation maintains an http://www.eclipse.org/legal/ecafaq.php[ECA FAQ] with more information about the ECA's provisions.
Before you set up your local development environment, we recommend creating an account at https://accounts.eclipse.org/user[eclipse.org] and submitting your signed ECA.
http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Follow the instructions on the Eclipse wiki] for details on how to create your account and sign the ECA.
[IMPORTANT]
.Make sure your emails match
====
The email address you use to sign the ECA **must be the same** as the email you use to sign your git commits.
====
Jetty's build process has a git hook that verifies each incoming pull request is signed with an email address with an active ECA.
If the git hook cannot verify your email, the Jetty committers **cannot do anything** to accept your commit.

49
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/3-source.adoc
View File

@ -1,49 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-source]]
== Getting the source code
Jetty's source is maintained on GitHub at https://github.com/jetty/jetty.project, where it is managed by the http://github.com/eclipse/[Eclipse Foundation].
You can clone a copy of the Jetty repo onto your local machine by running:
----
git clone https://github.com/jetty/jetty.project.git
----
[[cg-source-repositories]]
=== Related repositories
In addition to the https://github.com/jetty/jetty.project[Jetty code repository], we maintain a number of related repositories:
Non-Eclipse Jetty Repositories:: https://github.com/jetty-project
Build Toolchain:: https://github.com/eclipse/jetty.toolchain
[[cg-source-branches]]
=== Version branches
If you plan to work on a specific issue within Jetty, make sure to target the correct branch for your pull request.
.Active Jetty branches
[cols="4"]
|===
| https://github.com/jetty/jetty.project/tree/jetty-12.0.x[jetty-12.0.x] | Development (default branch) | Servlet 6.0 | Java 17+
| https://github.com/jetty/jetty.project/tree/jetty-11.0.x[jetty-11.0.x] | Maintenance | Servlet 5.0 | Java 11+
| https://github.com/jetty/jetty.project/tree/jetty-10.0.x[jetty-10.0.x] | Maintenance | Servlet 4.0 | Java 11+
| https://github.com/jetty/jetty.project/tree/jetty-9.4.x[jetty-9.4.x] | link:https://github.com/jetty/jetty.project/issues/7958[End of Community Support] | Servlet 3.1 | Java 8+
|===
Maintenance branches are periodically merged into active development branches.
Older branches are only updated if they get specifically targeted by a pull request.
Also, changes to older branches aren't regularly merged forward -- although an individual change may be cherry-picked forward, depending on the nature of the fix.

137
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/4-build.adoc
View File

@ -1,137 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-build]]
== Building Jetty
Jetty's uses http://maven.apache.org/[Apache Maven] for builds.
To successfully build the project, you will also need a recent version of the https://www.oracle.com/java/technologies/downloads/[Java Development Kit (JDK)].
[[cg-build-requirements]]
=== Maven and JDK requirements
Here are the minimum Maven and JDK version build requirements for each actively maintained branch.
.Build versioning requirements by branch
|===
| Branch | Maven Version | Minimum JDK | Recommended JDK
| jetty-12.0.x | Maven 3.9.2+ | OpenJDK 17+ | OpenJDK 19
| jetty-11.0.x | Maven 3.8.6+ | OpenJDK 11+ | OpenJDK 17
| jetty-10.0.x | Maven 3.8.6+ | OpenJDK 11+ | OpenJDK 17
|===
To build the Jetty documentation, OpenJDK 19+ is required due to the use of the virtual thread APIs.
[[cg-build-fast]]
=== Running a fast build
To get started with Jetty as quickly as possible, navigate to your local copy of the Jetty repo and run:
[source, shell]
----
mvn -Pfast clean install
----
The `-Pfast` flag tells Maven to bypass running tests and other checks.
[[cg-build-full]]
=== Running a full build
To build Jetty and automatically run all tests, run:
[source, shell]
----
mvn clean install
----
The full build takes substantial time and memory, as it runs hundreds of test cases -- many of which spin up embedded instances of Jetty itself.
The build also runs stress tests that may require you (depending on your hardware or operating system) to set you file descriptor limit to a value greater than 2048.
You can view or set your file descriptor limit by running:
[source, shell]
----
$ ulimit -n [new_value]
----
[TIP]
.Flagging flaky tests
====
Not all test cases are as timing independent as they should be, which can result in intermittent test failures.
You can help us track these flaky tests by opening an https://github.com/jetty/jetty.project/issues[issue] when you come across one.
====
[[cg-build-cache]]
=== Maven Build Cache
Per default, the build is using the https://maven.apache.org/extensions/maven-build-cache-extension[Maven Build Cache extension]
this means you will use your local build cache, To disable it you can use the property
[source, shell]
----
$ mvn clean install -Dmaven.build.cache.enabled=false
----
[[cg-build-parallel]]
=== Executing tests in parallel
Jetty uses https://junit.org/junit5/docs/current/user-guide/#writing-tests-parallel-execution[Junit5's parallel execution] to run test cases in parallel.
This behavior is configurable via flags passed to Maven, like so:
[source, shell]
----
mvn install -Djunit.jupiter.execution.parallel.enabled=false
----
Here are the available configuration flags:
`-Djunit.jupiter.execution.parallel.enabled=[BOOLEAN]`:: Disables parallel execution of tests.
`-Djunit.jupiter.execution.parallel.config.fixed.parallelism=[NUMBER]`:: Configures the number of tests to be executed in parallel.
[NOTE]
====
Certain tests cannot be run in parallel because they access or modify `static` fields, and are tagged in the codebase with this annotation:
[source, java]
----
@Isolated("Access static field of Configurations")
----
Maven will run these tests in isolation even when parallel execution is explicitly enabled.
====
[[cg-build-optional-tools]]
=== Optional build tools
* https://graphviz.org/[Graphviz]: used by Asciidoctor in the `jetty-documentation` module to produce various link:https://plantuml.com/[PlantUML] graphs.
* https://www.docker.com/[Docker]: used to run some integration tests for testing third party integrations.
[[cg-build-artifacts]]
=== 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:
[cols="1a,2a,2a"]
|===
| Branch(es) | Location | Description
| all | `jetty-home/target/jetty-home-<ver>.tar.gz` | The Jetty Home 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
| `jetty-11.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution for EE9/Servlet 5 (`jakarta.servlet`) webapps
| `jetty-10.0.x` | `jetty-runner/target/jetty-runner-<ver>.jar` | The Jetty Runner distribution for EE8/Servlet 4 (`javax.servlet`) webapps
|===

133
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/5-code-standards.adoc
View File

@ -1,133 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-code-standards]]
== Code Standards
This section outlines the various coding conventions and standards we use throughout the Jetty codebase.
[[cg-code-standards-ide]]
=== Configuring your IDE
IntelliJ IDE::
An IntelliJ code style XML file is available in the source repo at
https://github.com/jetty/jetty.project/blob/jetty-10.0.x/build-resources/jetty-codestyle-intellij.xml[`/build-resources/jetty-codestyle-intellij.xml`]
// TODO: The above link points to the jetty-10.0.x branch, but it doesn't look like there's a `build-resources` directory for jetty-12.0.x.
Follow https://www.jetbrains.com/help/idea/configuring-code-style.html#import-export-schemes[IntelliJ's documentation] to import these settings into your IDE.
Eclipse IDE::
An Eclipse code style XML file is available in the source repo at
https://github.com/jetty/jetty.project/blob/jetty-10.0.x/build-resources/jetty-codestyle-eclipse-ide.xml[`/build-resources/jetty-codestyle-eclipse-ide.xml`].
[[cg-code-standards-java]]
=== Java conventions
The following code sample shows some basic Java styles and conventions used throughout the Jetty codebase:
[source, java]
----
import some.exact.ClassName; // GOOD
import some.wildcard.package.*; // BAD!
package org.always.have.a.package;
/**
* All classes should have a javadoc
*/
class MyClassName
{
// Use 4 spaces to indent.
// The code must format OK with default tab size of 8.
private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS = 1;
// Prefix fields with one underscore (_). This
// convention is not mandatory, but the chosen style
// should be used consistently within a single class.
private Object _privateField;
// Use getters and setters rather than public fields.
// Braces always on new line.
public void setPrivateField(Object privateField)
{
_privateField = privateField;
}
public Object getPrivateField()
{
return _privateField;
}
public void doSomething() throws SomeException
{
Object local_variable = _privateField;
// Braces always on new line.
if (local_variable == null)
{
// do Something
}
}
}
----
[[cg-code-standards-logging]]
=== Logging conventions
When deciding when and what to log, bear in mind a few things:
* Never use `LOG.debug()` without a preceding `if (LOG.isDebugEnabled())`.
* Avoid polluting the log with very long stack traces.
* Don't routinely produce logging events in response to data sent by a user.
* Only call one `LOG` method for a given event, to avoid generating confusingly interleaved log messages.
* Never call `LOG.warn()` right before throwing an exception, as this will likely result in double logging the exception.
* Avoid calling `LOG.debug()` right before throwing an exception, as this will make debug logs verbose while adding little information.
* When interacting with a request or other client-provided data that result in an exception, use `DEBUG`-level logging:
+
[source, java]
----
catch (Throwable t)
{
if (LOG.isDebugEnabled())
LOG.debug("Something happened {} {} {}",x, y, z, t);
}
----
* When calling into application code that throws an exception, use `INFO`-level logging, and gate the log with `LOG.isDebugEnabled()` to reduce the size of logging stack traces:
+
[source, java]
----
catch (Throwable t)
{
if (LOG.isDebugEnabled())
LOG.info("Something happened {} {} {}", x, y, z, t);
else
LOG.info("Something happened {} {} {} {}", x, y, z, t.toString());
}
----
* When exceptions happen in Jetty code, and if the exception is (1) not entirely unexpected, (2) can happen relatively frequently, or (3) can potentially have a very long stack trace, you can use `LOG.isDebugEnabled()` to cut down on the size of the logging of the stacktrace:
+
[source, java]
----
catch (Throwable t)
{
if (LOG.isDebugEnabled())
LOG.warn("Something happened {} {} {}", x, y, z, t);
else
LOG.warn("Something happened {} {} {} {}", x, y, z, t.toString());
}
----
[TIP]
====
By default, Jetty's logger outputs a full stacktrace whether you call it like `LOG.warn("Something happened", t)` or `LOG.warn("Something happened {}", t)`.
If you only want the log message but not the stack trace, you need to do call `.toString()` on the caught exception, e.g., `LOG.warn("Something happened {}", t.toString())`.
====

255
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/6-documentation.adoc
View File

@ -1,255 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-documentation]]
== Writing Documentation
Another great way to contribute to Jetty is to help us write and maintain our documentation.
[[cg-documentation-guides]]
=== Documentation guides
Jetty's documentation is grouped into three guides, each written for a different target audience.
Operations Guide::
Targets sysops, devops, and developers who want to run Jetty as a standalone web server.
Programming Guide::
Targets developers who want to use the Jetty libraries in their applications.
Contribution Guide::
Targets developers and writers who want to make contributions to the Jetty project.
[[cg-documentation-toolchain]]
=== The documentation toolchain
Jetty follows a https://www.writethedocs.org/guide/docs-as-code/["docs as code"] philosophy, meaning *we use the same tools to write and build our code and docs*.
As such, the docs are maintained directly within the Jetty codebase at https://github.com/jetty/jetty.project/tree/jetty-12.0.x/documentation/jetty-documentation/src/main/asciidoc[`documentation/jetty-documentation/src/main/asciidoc/`].
[[cg-documentation-asciidoc]]
==== AsciiDoc
Our docs are written in https://asciidoc.org/[AsciiDoc], a markup language for writing technical content.
AsciiDoc supports many advanced features, such as robust linking across different documentation sets, while remaining human-readable.
Although Jetty takes advantage of many of these features, you don't need to be an AsciiDoc expert to contribute to our documentation.
If you _are_ interested in learning the ins and outs of AsciiDoc, the https://docs.asciidoctor.org/asciidoc/latest/[official language documentation] is a good place to start.
[[cg-documentation-asciidoctor]]
==== Maven and Asciidoctor
In addition to using Maven to xref:cg-build[build the Jetty codebase], we use it to build our docs.
During a build, Maven converts AsciiDoc-formatted docs into the HTML pages that you are reading right now.
https://asciidoctor.org/[Asciidoctor] is the tool that actually performs this compilation step.
Maven integrates with Asciidoctor via the https://docs.asciidoctor.org/maven-tools/latest/[`asciidoctor-maven-plugin`].
[[cg-documentation-build]]
=== Building the docs
Since Jetty's docs are maintained in `git` alongside the rest of the Jetty codebase, you'll need to xref:cg-source[check out a local copy] of the code to contribute to the docs.
The docs are maintained as a separate module within Jetty, which means you can build the docs separately from the rest of the project.
To do so, run `mvn clean install` from the `documentation/jetty-documentation` subdirectory.
[source, shell]
----
$ cd jetty.project/documentation
$ mvn install
<...snip...>
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.272 s
[INFO] Finished at: 2018-04-09T13:06:10-05:00
[INFO] Final Memory: 74M/247M
[INFO] ------------------------------------------------------------------------
----
[NOTE]
====
You'll see a lot of files getting downloaded during the build process.
This is Maven setting up the execution environment, which it uses to generate the docs.
====
When the build completes, you can view the generated docs in your preferred web browser by opening file:///path/to/jetty.project/documentation/jetty-documentation/target/html/index.html on your local filesystem.
[[cg-documentation-build-structure]]
==== Documentation project structure
The documentation root is https://github.com/jetty/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation[`documentation/jetty-documentation/`].
Within this root directory are some files and subdirectories of note:
https://github.com/jetty/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main/asciidoc[`src/main/asciidoc`]::
The primary root for all documentation content.
https://github.com/jetty/jetty.project/tree/jetty-10.0.x/documentation/jetty-documentation/src/main/asciidoc/config.adoc[`src/main/asciidoc/config.adoc`]::
This file contains metadata and global variables shared across all the xref:cg-documentation-guides[documentation guides].
This configuration is used by Asciidoctor to correctly render the final docs.
`src/main/asciidoc/*-guide`::
Secondary root directories for each individual xref:cg-documentation-guides[documentation guide].
`src/main/asciidoc/*-guide/index.adoc`::
Asciidoctor's "point of entry" for each guide.
Content is pulled into the guide via the `include::` directives in these index files.
Also, guide-specific metadata and variables that wouldn't belong in the root `config.adoc` can also be defined here.
`target/<format>`::
The final build destination for any docs generated by Maven.
By default, docs are generated into `target/html`, but other formats (e.g., `pdf` and `epub`) are available.
This directory is not checked into `git`.
[[cg-documentation-style]]
=== Style guide
The following conventions are not set in stone, but you are encouraged to follow them where possible.
Stylistically consistency helps keep the docs easy to both understand and maintain.
[[cg-documentation-style-prose]]
==== Ventilated prose
In markup, *each sentence should be on its own line with a hard return at the end of the line*.
This practice is known variously as https://writetheasciidocs.netlify.app/ventilated-prose[ventilated prose] or https://rhodesmill.org/brandon/2012/one-sentence-per-line/[semantic linefeeds].
This practice makes for more readable file diffs, and also makes it easier to comment out individual lines or to move sentences around.
[TIP]
====
AsciiDoc treats a single line breaks just like a space, so it will render ventilated prose naturally.
====
[[cg-documentation-versions]]
==== Documenting versions
[[cg-documentation-versions-multiple]]
===== Documenting multiple versions at once
Jetty 12 features many parallel modules with similar names and functionality, but which target different versions of Jakarta EE.
For instance, the `ee8-deploy`, `ee9-deploy`, and `ee10-deploy` modules all behave similarly, except they target Jakarta EE8, EE9, and EE10, respectively.
Whenever possible, *try to consolidate these types of parallel references*.
For instance, you can quickly refer to all three of the aforementioned modules as a group by writing `{ee-all}-deploy` or `eeN-deploy`.
Another approach is to write your docs targeting one specific module, and tell the reader what substitution(s) they would need to make to target a different module.
[NOTE]
====
When targeting a specific version in your docs for demonstration purposes, you should prefer to use the most recent version number.
For the example above, this would mean targeting `{ee-current}-deploy`.
====
Consolidating parallel references saves readers from having to sift through repetitive material, and helps us avoid maintaining multiple versions of nearly identical docs.
[[cg-documentation-versions-multiple-example]]
===== Dealing with multiple versions in code examples
Instead of referencing multiple versions in your code and command-line examples, it's generally better to target one specific version, typically the latest (currently `{ee-current}`):
[source,subs="verbatim,attributes"]
----
$ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-deploy
----
This will work when copy-pasted into the command line.
[NOTE]
====
You may want to remind the reader to change the `10` in the command to their preferred target version -- although doing so isn't strictly necessary for a simple example like above.
====
[[cg-documentation-license]]
=== License blocks
Each `.adoc` file should contain the license block that exists in the `index.adoc` file.
For reference, here is a standard license header:
----
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
----
[[cg-documentation-asciidoc-conventions]]
=== AsciiDoc conventions
[[cg-documentation-asciidoc-conventions-ids]]
==== Custom IDs
We rely heavily on https://docs.asciidoctor.org/asciidoc/latest/sections/custom-ids/[custom IDs] for generating stable documentation URLs and linking within docs.
At minimum, every chapter and top-level section should have its own custom ID; however, best practice is to give each subsection its own custom ID, too.
[NOTE]
====
Custom IDs share a single global namespace, which means they must be unique across all documentation guides.
To help deal with this constraint, we used different ID prefixes in each guide:
* Operations Guide: `og-`
* Programming Guide: `pg-`
* Contribution Guide: `cg-`
====
[[cg-documentation-asciidoc-conventions-images]]
==== Images
Images should live in the `images/` directory of the guide they appear in.
Use the `image::` directive to include an image, like so:
----
image::small_powered_by.gif[image,width=145]
----
image::small_powered_by.gif[image,width=145]
[[cg-documentation-asciidoc-conventions-admonitions]]
==== Admonitions
Admonitions (or "callout blocks") are useful for flagging information that doesn't belong in the natural flow of text.
Asciidoc supports five levels of admonition:
* `[NOTE]`
* `[IMPORTANT]`
* `[TIP]`
* `[CAUTION]`
* `[WARNING]`
Each admonition's visual appearance and typical usage situation are as follows:
[NOTE]
====
A note about the previous case to be aware of.
====
[IMPORTANT]
====
Important notes are marked with an icon.
====
[TIP]
====
Tips that make your life easier.
====
[CAUTION]
====
Places where you have to be careful what you are doing.
====
[WARNING]
====
Where extreme care has to be taken.
Data corruption or other nasty things may occur if these warnings are ignored.
====

67
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/7-submitting-patches.adoc
View File

@ -1,67 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-patches]]
== Submitting Patches
We wholeheartedly welcome contributions to Jetty.
While not every contribution will be accepted, our commitment is to work with interested parties on the things they care about.
[[cg-patches-git-config]]
=== Configuring `git`
The email in your git commits must match the email you used to xref:cg-eca[sign the Eclipse Contributor Agreement].
As such, you'll likely want to configure `user.email` in git accordingly.
See link:https://help.github.com/articles/setting-your-email-in-git[this guide] on GitHub for details on how to do so.
[[cg-patches-git-commit-messages]]
==== Writing commit messages
If your pull request addresses a particular issue in our repository, then the commit message should reference the issue.
Specifically, the message should follow the form *Issue #<NNN> <description of the commit>*:
[source, shell]
----
$ git commit -s -m "Issue #123 resolving the issue by adding widget"
----
Using this format will ensure that the commit will be included in `VERSIONS.txt` upon new releases of Jetty.
[[cg-patches-git-commit-signing]]
=== Signing the commit
You should sign off on every commit in your pull request using git's https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---signoff[signoff] feature (`git commit -s`).
[[cg-patches-pull-requests]]
=== Creating pull requests
Please see https://help.github.com/articles/creating-a-pull-request[GitHub's documentation for creating pull requests].
[[cg-patches-time-frames]]
=== Time frames
We do our best to process contributions in a timely fashion.
Please note that we can only handle pull requests with actively engaged parties.
We reserve the right to abandon pull requests whose authors do not respond in a timely fashion.
We will generally adhere to the following time frames for contributions:
Invalid Pull Requests - 1 week::
These pull requests do not follow the contribution requirements for some reason -- e.g., a missing contributor agreement or mismatched email signature.
We will try and follow up with the pull request author to resolve the issue.
If we do not hear from the contributor after a week we will close the pull request.
Valid Pull Requests - 2 weeks::
If the pull request can be immediately merged, we will do so.
Otherwise, we will follow up with the author in a comment to discuss what additional actions must be taken before the change can be landed.
If the original contributor does not respond within two weeks, we may close the commit, or make some variation of the commit ourselves.

32
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/8-security.adoc
View File

@ -1,32 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cg-security]]
== Security
There are a number of ways to report security issues to the Jetty project.
* If the issue is directly related to Jetty itself then you are encouraged to report to the Jetty developers directly at mailto:security@webtide.com[security@webtide.com].
link:https://webtide.com[Webtide] employs the active committers of the Jetty project, so this is the preferred reporting method.
[IMPORTANT]
====
We prefer you report any security issues directly to the Jetty developers mailto:security@webtide.com[via email] rather than via GitHub Issues, as GitHub https://github.com/isaacs/github/issues/37[does not support private issues].
====
* If the issue is related to Eclipse or its Jetty integration then we encourage you to reach out to mailto:security@eclipse.org[security@eclipse.org].
* If the issue is related to some third party integration, we are happy to work with you to identify the proper reporting entity and work with them to properly address the issue.
In this case, you are welcome to contact either of the above outreach addresses.
We are generally flexible in how we work with reporters of security issues from an attribution perspective, but reserve the right to act in the interests of the Jetty project in all circumstances.

BIN
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/images/small_powered_by.gif
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.7 KiB

29
documentation/jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc
View File

@ -1,29 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
:doctitle: link:https://eclipse.org/jetty[Eclipse Jetty]: Contribution Guide
:toc-title: Contribution Guide
:idprefix: cg-
:breadcrumb: Home:../index.html | Contribution Guide:./index.html
:toclevels: 3
include::../config.adoc[]
include::.asciidoctorconfig[]
include::1-introduction.adoc[]
include::2-eca.adoc[]
include::3-source.adoc[]
include::4-build.adoc[]
include::5-code-standards.adoc[]
include::6-documentation.adoc[]
include::7-submitting-patches.adoc[]
include::8-security.adoc[]

34
documentation/jetty-documentation/src/main/asciidoc/index.adoc
View File

@ -1,34 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
:doctitle: Eclipse Jetty Documentation
include::config.adoc[]
== xref:operations-guide/index.adoc[Jetty Operations Guide]
The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
== xref:programming-guide/index.adoc[Jetty Programming Guide]
The Eclipse Jetty Programming Guide targets developers who want to use the Eclipse Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.
== https://jetty.org/docs/contribution-guide/index.html[Jetty Contribution Guide]
The Eclipse Jetty Programming Guide targets developers that wish to contribute to the Jetty Project with code patches or documentation improvements.
== xref:old_docs/index.adoc[OLD Jetty Documentation]
The guides above are a work in progress for the current Jetty version.
The old Jetty documentation refers to old Jetty versions, and it is currently being ported to the current Jetty version.

100
documentation/jetty-documentation/src/main/asciidoc/old_docs/alpn/alpn.adoc
View File

@ -1,100 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[alpn]]
=== Introducing ALPN
Application Layer Protocol Negotiation (ALPN) is a TLS extension that allows client and server to negotiate the application protocol that they will use to communicate within the encryption provided by TLS.
Any protocol can be negotiated by ALPN within a TLS connection; the protocols that are most commonly negotiated are HTTP/2 and HTTP/1.1.
Browsers only support HTTP/2 over TLS by negotiating the HTTP/2 protocol via ALPN.
You need to configure the server to support TLS and ALPN if you want browsers to use
the HTTP/2 protocol, otherwise they will default to HTTP/1.1.
In the Jetty project, ALPN is _used_ in two artifacts: `jetty-alpn-client` and `jetty-alpn-server`, respectively for the client and for the server.
When using Jetty as a standalone server via the Jetty distribution, the `jetty-alpn-server` artifact is automatically included in the server classpath by the Jetty module system.
When using Jetty embedded, the `jetty-alpn-client` and `jetty-alpn-server` artifacts must be included in the classpath, respectively for client and server use cases.
The ALPN implementation is _provided_ to these two artifacts with the following three options:
* For JDK 8 or later, a provider based on the link:#conscrypt[Conscrypt security provider]
** Works with JDK 8 or later and provides improved performance
** Binds to the OpenSSL native library shipped by Conscrypt and is therefore only available on the platforms supported by Conscrypt
* For JDK 9 or later, a provider based on the ALPN APIs present in the JDK
** Works with JDK 9 or later, pure Java implementation
** Lower performance than Conscrypt
The first, although hosted under the umbrella of the Jetty project, is independent of Jetty (the Servlet Container); you can use it in any other Java network server.
Each provider above provides an ALPN _service_ implementation; Jetty uses the `ServiceLoader` mechanism to load these service implementations.
At least one valid provider must be present in the server classpath.
For example, using JDK 8 with the JDK 9 ALPN provider is an _invalid_ combination.
The absence of valid implementations is an error at startup (see also the link:#alpn-troubleshooting[troubleshooting section]).
There may be multiple ALPN service providers in the server classpath.
When a new connection is created, an `SSLEngine` instance is associated to it; each `SSLEngine` is passed all service implementations, until one accepts it.
It is therefore possible to have multiple providers active at the same time, for example the JDK 9 provider and the Conscrypt provider, and at runtime the correct one will be chosen by the Jetty runtime.
[[alpn-conscrypt]]
==== ALPN and Conscrypt
When using JDK 8 or later, you can use the https://conscrypt.org/[Conscrypt] security provider to provide the ALPN service implementation.
Conscrypt binds natively to BoringSSL (a fork of OpenSSL by Google), so ALPN will be supported via the support provided by BoringSSL (bundled together with Conscrypt).
When using Jetty as a standalone server via the Jetty distribution, ALPN is enabled by enabling the `conscrypt` module.
When using Jetty embedded, ALPN is enabled by the `jetty-alpn-conscrypt-client` and `jetty-alpn-conscrypt-server` artifacts, respectively for client usage and server usage.
In addition, you also need the Conscrypt artifacts, typically the `org.conscrypt:conscrypt-openjdk-uber` artifact.
All these artifacts must be added to the classpath.
[[alpn-jdk9]]
==== ALPN and JDK 9
When using JDK 9 or later and Jetty as a standalone server via the Jetty distribution, ALPN support is automatically enabled when the `http2` module is enabled.
This enables transitively the `alpn-9` module which puts the `jetty-alpn-java-server` artifact in the server classpath, providing the ALPN JDK 9 service implementation.
When using JDK 9 or later and Jetty embedded, the ALPN service implementation is provided by the `jetty-alpn-java-client` and `jetty-alpn-java-server` artifacts, respectively for client usage and server usage, and must be added to the classpath.
[[alpn-osgi]]
===== Starting in OSGi
To use ALPN in an OSGi environment, in addition to what described above, you will also need to deploy the `jetty-osgi-alpn` jar.
This jar contains a `Fragment-Host` directive that ensures the ALPN classes will be available from the system bundle.
You can download the https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/[jetty-osgi-alpn jar] from Maven Central.
____
[NOTE]
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly.
OSGi leverages http://aries.apache.org/modules/spi-fly.html[Apache Aries SPI Fly] for this functionality.
You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
____
[[alpn-troubleshooting]]
==== ALPN Troubleshooting
When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:
[source, plain, subs="{sub-order}"]
----
IllegalStateException: no ALPN processor
----
The error means that you don't have the ALPN dependencies setup correctly in your classpath.
For example, you do not have the `jetty-alpn-java-server` artifact in the classpath.

28
documentation/jetty-documentation/src/main/asciidoc/old_docs/alpn/chapter.adoc
View File

@ -1,28 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[alpn-chapter]]
== Application Layer Protocol Negotiation (ALPN)
The development of new web protocols such as HTTP/2 raised the need of protocol
negotiation within a Transport Layer Security (TLS) handshake.
A protocol negotiation called ALPN (Application Layer Protocol Negotiation -
https://tools.ietf.org/html/rfc7301[RFC7301]) has been defined to accomplish this.
ALPN has now replaced the older (and now fully deprecated) NPN in the general Web
as of 2016.
For those browsers that support HTTP/2, they all now support ALPN.
Starting with Jetty 9.3.0, only ALPN is supported by Jetty.
include::alpn.adoc[]

22
documentation/jetty-documentation/src/main/asciidoc/old_docs/annotations/chapter.adoc
View File

@ -1,22 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[annotations]]
== Annotations
Jetty supports the servlet specification annotations.
It is not enable by default, so the following sections show you how to enable it, and how to use them.
include::quick-annotations-setup.adoc[]
include::using-annotations.adoc[]
include::using-annotations-embedded.adoc[]

40
documentation/jetty-documentation/src/main/asciidoc/old_docs/annotations/quick-annotations-setup.adoc
View File

@ -1,40 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[annotations-quick-setup]]
=== Quick Setup
==== Jetty Distribution
If you are using the jetty distribution, then annotations are enabled by default.
The annotations link:#startup-modules[module] and its transitive dependencies are responsible for making annotation processing available.
Note that annotations that relate to link:#jndi[JNDI], such as @Resource and @Resources are enabled via the JNDI module, which is a transitive dependency on the annotations module.
==== Jetty Maven Plugin
Annotations and JNDI are pre-enabled for the Maven plugin.
==== Embedding
To use annotations in an embedded scenario, you will need to include the `jetty-annotations` jar and all its dependencies onto your classpath.
You will also need to include the `org.eclipse.jetty.annotations.AnnotationConfiguration` class into the list of link:#webapp-configurations[Configuration classes] applied to the `org.eclipse.jetty.ee9.webapp.WebAppContext` class representing your webapp.
Below is an example application that sets up the standard `test-spec.war` webapp from the distribution in embedded fashion.
It can also be found in the Jetty GitHub repository on the examples/embedded page as link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded[`ServerWithAnnotations.java`.]
Note that the `test-spec.war` uses not only annotations, but also link:#jndi[JNDI], so this example also enables their processing (via the link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.EnvConfiguration], link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.PlusConfiguration] and their related jars).
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ServerWithAnnotations.java[]
----

189
documentation/jetty-documentation/src/main/asciidoc/old_docs/annotations/using-annotations-embedded.adoc
View File

@ -1,189 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[using-annotations-embedded]]
=== Using Annotations with Jetty Embedded
==== Setting up the Classpath
You will need to place the following Jetty jar files onto the classpath of your application.
You can obtain them from the https://jetty.org/download.html[Jetty distribution], or the https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-annotations[Maven repository]:
....
jetty-plus.jar
jetty-annotations.jar
....
You will also need the http://asm.ow2.org/[asm] jar, which you can obtain from link:{MVNCENTRAL}/org/eclipse/jetty/orbit/org.objectweb.asm/3.3.1.v201105211655/org.objectweb.asm-3.3.1.v201105211655.jar[this link.]
==== Example
Here's an example application that sets up a Jetty server, performs some setup to ensure that annotations are scanned, and then deploys a webapp that uses annotations.
This example also uses the @Resource annotation which involves JNDI, so we would also link:#jndi-embedded[add the necessary JNDI jars to the classpath].
The example also adds in the configuration classes that are responsible for JNDI (see line 19).
The code is as follows:
[source, java, subs="{sub-order}"]
----
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.ee9.webapp.WebAppContext;
/**
* ServerWithAnnotations
*
*
*/
public class ServerWithAnnotations
{
public static final void main(String args[]) throws Exception
{
//Create the server
Server server = new Server(8080);
//Enable parsing of jndi-related parts of web.xml and jetty-env.xml
org.eclipse.jetty.ee9.webapp.Configuration.ClassList classlist = org.eclipse.jetty.ee9.webapp.Configuration.ClassList.setServerDefault(server);
classlist.addAfter("org.eclipse.jetty.ee9.webapp.FragmentConfiguration", "org.eclipse.jetty.plus.webapp.EnvConfiguration", "org.eclipse.jetty.plus.webapp.PlusConfiguration");
classlist.addBefore("org.eclipse.jetty.ee9.webapp.JettyWebXmlConfiguration", "org.eclipse.jetty.annotations.AnnotationConfiguration");
//Create a WebApp
WebAppContext webapp = new WebAppContext();
webapp.setContextPath("/");
webapp.setWar("../../tests/test-webapps/test-servlet-spec/test-spec-webapp/target/test-spec-webapp-9.0.4-SNAPSHOT.war");
server.setHandler(webapp);
//Register new transaction manager in JNDI
//At runtime, the webapp accesses this as java:comp/UserTransaction
org.eclipse.jetty.plus.jndi.Transaction transactionMgr = new org.eclipse.jetty.plus.jndi.Transaction(new com.acme.MockUserTransaction());
//Define an env entry with webapp scope.
org.eclipse.jetty.plus.jndi.EnvEntry maxAmount = new org.eclipse.jetty.plus.jndi.EnvEntry (webapp, "maxAmount", new Double(100), true);
// Register a mock DataSource scoped to the webapp
org.eclipse.jetty.plus.jndi.Resource mydatasource = new org.eclipse.jetty.plus.jndi.Resource(webapp, "jdbc/mydatasource", new com.acme.MockDataSource());
// Configure a LoginService
HashLoginService loginService = new HashLoginService();
loginService.setName("Test Realm");
loginService.setConfig("src/test/resources/realm.properties");
server.addBean(loginService);
server.start();
server.join();
}
}
----
On line 19 the configuration classes responsible for setting up JNDI and `java:comp/env` are added.
On line 20 we add in the configuration class that ensures annotations are inspected.
On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Resource annotations are configured.
With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:
[source, java, subs="{sub-order}"]
----
import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RunAs;
import jakarta.servlet.ServletConfig;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletOutputStream;
import jakarta.servlet.annotation.WebInitParam;
import jakarta.servlet.annotation.WebServlet;
import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
import javax.transaction.UserTransaction;
/**
* AnnotationTest
*
* Use servlet 3.0 annotations from within Jetty.
*
* Also uses servlet 2.5 resource injection and lifecycle callbacks
*/
@RunAs("special")
@WebServlet(urlPatterns = {"/","/test/*"}, name="AnnotationTest", initParams={@WebInitParam(name="fromAnnotation", value="xyz")})
@DeclareRoles({"user","client"})
public class AnnotationTest extends HttpServlet
{
private DataSource myDS;
@Resource(mappedName="UserTransaction")
private UserTransaction myUserTransaction;
@Resource(mappedName="maxAmount")
private Double maxAmount;
@Resource(mappedName="jdbc/mydatasource")
public void setMyDatasource(DataSource ds)
{
myDS=ds;
}
@PostConstruct
private void myPostConstructMethod ()
{
System.err.println("PostConstruct called");
}
@PreDestroy
private void myPreDestroyMethod()
{
System.err.println("PreDestroy called");
}
public void init(ServletConfig config) throws ServletException
{
super.init(config);
}
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
{
doGet(request, response);
}
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
{
try
{
response.setContentType("text/html");
ServletOutputStream out = response.getOutputStream();
out.println("<html>");
out.println("<body>");
out.println("<h1>Results</h1>");
out.println(myDS.toString());
out.println("<br/>");
out.println(maxAmount.toString());
out.println("</body>");
out.println("</html>");
out.flush();
}
catch (Exception e)
{
throw new ServletException(e);
}
}
}
----

19
documentation/jetty-documentation/src/main/asciidoc/old_docs/architecture/chapter.adoc
View File

@ -1,19 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[architecture]]
== Architecture
General items related to the architecture of jetty and how it deals with certain design decisions.
include::jetty-classloading.adoc[]

198
documentation/jetty-documentation/src/main/asciidoc/old_docs/architecture/jetty-classloading.adoc
View File

@ -1,198 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[jetty-classloading]]
=== Jetty Classloading
Class loading in a web container is slightly more complex than a normal Java application.
The normal configuration is that each web context (web application or WAR file) has its own classloader, which has the system classloader as its parent.
Such a classloader hierarchy is normal in Java, however the servlet specification complicates the hierarchy because it requires the following:
* Classes contained within `WEB-INF/lib` or `WEB-INF/classes` have priority over classes on the parent classloader.
This is the opposite of the normal behavior of a Java 2 classloader.
* System classes such as `java.lang.String` are excluded from the webapp priority, and you may not replace them with classes in `WEB-INF/lib` or `WEB-INF/` classes.
Unfortunately the specification does not clearly state what classes are _System_ classes, and it is unclear if all `javax` classes should be treated as System classes.
* Server implementation classes like link:{JDURL}/org/eclipse/jetty/server/Server.html[Server] should be hidden from the web application and should not be available in any classloader.
Unfortunately the specification does not state what classes are _Server_ classes, and it is unclear if common libraries like the Xerces parser should be treated as Implementation classes.
[[configuring-webapp-classloading]]
==== Configuring Webapp Classloading
Jetty provides configuration options to control the three webapp class loading issues identified above.
You can configure webapp classloading by several methods on the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext].
You can call these methods directly if you are working with the Jetty API, or you can inject methods from a context XML file if you are using the Context Provider (xref:using-context-provider[]).
You CANNOT set these methods from a `jetty-web.xml` file, as it executes after the classloader configuration is set.
As a note, `jetty-web.xml` uses the webapp classpath and not the classpath of the server.
[[controlling-webapp-classloader-priority]]
===== Controlling Webapp Classloader Priority
The method link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#isParentLoaderPriority()[org.eclipse.jett .webapp.WebAppContext.setParentLoaderPriority(boolean)] allows control over the priority given to webapp classes over system classes.
If you set it to false (the default), Jetty uses standard webapp classloading priority.
However, if in this mode some classes that are dependencies of other classes are loaded from the parent classloader (due to settings of system classes below), ambiguities might arise as both the webapp and system classloader versions can end up being loaded.
If set to true, Jetty uses normal JavaSE classloading priority, and gives priority to the parent/system classloader.
This avoids the issues of multiple versions of a class within a webapp, but the version the parent/system loader provides must be the right version for all webapps you configure in this way.
[[configuring-webapp-caching]]
===== Configuring Webapp Classloader Caching
Introduced in Jetty 9.3.6, the link:{JDURL}/org/eclipse/jetty/webapp/CachingWebAppClassLoader.html[CachingWebAppClassLoader] can be used to cache `getResource(String)` results.
For webapps that search for classes and resources regularly, this can increase speed and performance.
This is an optional feature and it should be noted that it can conflict with several other libraries such as JSP, JSTL, JSF and CDI.
As such, this feature must be manually enabled for each webapp you want to use it in.
Below is an example of implementing this feature using Jetty IoC XML format:
[source, xml, options="header"]
----
<Configure id="mywebapp" class="org.eclipse.jetty.ee9.webapp.WebAppContext">
...
<Set name="classLoader">
<New class="org.eclipse.jetty.ee9.webapp.CachingWebAppClassLoader">
<Arg><Ref refid="mywebapp"/></Arg>
</New>
</Set>
...
</Configure>
----
[[classloading-setting-system-classes]]
===== Setting System Classes
You can call the methods
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setSystemClasses%28java.lang.String%5B%5D%29[WebAppContext.setSystemClasses(String[\])]
or
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#getSystemClasspathPattern()[WebAppContext.getSystemClasspathPattern().add(String)]
to allow fine control over which classes are considered system classes.
* A web application can see a System class.
* A WEB-INF class cannot replace a System class.
The default system classes are:
.Default System Classes
[width="100%",cols="8%,92%",options="header",]
|=======================================================================
|System Classes | Note
|java. |Java SE classes (per servlet spec v2.5 / SRV.9.7.2).
|javax. |Java SE classes (per servlet spec v2.5 / SRV.9.7.2).
|org.xml. |Needed by javax.xml.
|org.w3c. |Needed by javax.xml.
|org.eclipse.jetty.continuation. |Webapp can see and not change continuation classes.
|org.eclipse.jetty.jndi. |Webapp can see and not change naming classes.
|org.eclipse.jetty.jaas. |Webapp can see and not change JAAS classes.
|org.eclipse.jetty.websocket. |WebSocket is a Jetty extension.
|org.eclipse.jetty.ee9.servlet.DefaultServlet |Webapp can see and not change default servlet.
|=======================================================================
Absolute classname can be passed, names ending with `.` are treated as packages names, and names starting with `-` are treated as negative matches and must be listed before any enclosing packages.
[[setting-server-classes]]
===== Setting Server Classes
You can call the methods link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setServerClasses%28java.lang.String%5B%5D%29[org.eclipse.jetty.ee9.webapp.WebAppContext.setServerClasses(String Array)] or
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#addServerClass(java.lang.String)[org.eclipse.jetty.ee9.webapp.WebAppContext.addServerClass(String)] to allow fine control over which classes are considered Server classes.
* A web application cannot see a Server class.
* A WEB-INF class can replace a Server class.
The default server classes are:
.Default Server Classes
[width="100%",cols="8%,92%",options="header",]
|=======================================================================
|Server Classes
|-org.eclipse.jetty.continuation. |Don't hide continuation classes.
|-org.eclipse.jetty.jndi. |Don't hide naming classes.
|-org.eclipse.jetty.jaas. |Don't hide jaas classes.
|-org.eclipse.jetty.ee9.servlets. |Don't hide utility servlet classes if provided.
|-org.eclipse.jetty.ee9.servlet.DefaultServlet |Don't hide default servlet.
|-org.eclipse.jetty.ee9.servlet.listener. |Don't hide utility listeners
|-org.eclipse.jetty.websocket. |Don't hide websocket extension.
| org.eclipse.jetty. |Do hide all other Jetty classes.
|=======================================================================
[[adding-extra-classpaths]]
==== Adding Extra Classpaths to Jetty
You can add extra classpaths to Jetty in several ways.
[[classpaths-using-start-jar]]
===== Using `start.jar`
If you are using `start.jar` via the Jetty distribution, at startup the Jetty runtime automatically loads option Jars from the top level `$jetty.home/lib` directory. The default settings include:
* Adding Jars under `$jetty.home/lib/ext` to the system classpath.
You can place additional Jars here.
* Adding the directory `$jetty.home/resources` to the classpath (may contain classes or other resources).
* Adding a single path defined by the command line parameter __path__.
[[using-extra-classpath-method]]
===== Using the extraClasspath() method
You can add an additional classpath to a context classloader by calling link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html#setExtraClasspath(java.lang.String)[org.eclipse.jetty.ee9.webapp.WebAppContext.setExtraClasspath(String)] with a comma-separated list of paths.
You can do so directly to the API via a context XML file such as the following:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
...
<Set name="extraClasspath">../my/classes,../my/jars/special.jar,../my/jars/other.jar</Set>
...
----
[[using-custom-webappclassloader]]
==== Using a Custom WebAppClassLoader
If none of the alternatives already described meet your needs, you can always provide a custom classloader for your webapp.
We recommend, but do not require, that your custom loader subclasses link:{JDURL}/org/eclipse/jetty/webapp/WebAppClassLoader.html[WebAppClassLoader].
If you do not subclass WebAppClassLoader, we recommend that you implement the link:{JDURL}/org/eclipse/jetty/util/ClassVisibilityChecker.html[ClassVisibilityChecker] interface.
Without this interface, session persistence will be slower.
You configure the classloader for the webapp like so:
[source, java, subs="{sub-order}"]
----
MyCleverClassLoader myCleverClassLoader = new MyCleverClassLoader();
...
WebAppContext webapp = new WebAppContext();
...
webapp.setClassLoader(myCleverClassLoader);
----
You can also accomplish this in a context xml file.
[[starting-jetty-custom-classloader]]
==== Starting Jetty with a Custom ClassLoader
If you start a Jetty server using a custom class loader–consider the Jetty classes not being available to the system class loader, only your custom class loader–you may run into class loading issues when the `WebAppClassLoader` kicks in.
By default the `WebAppClassLoader` uses the system class loader as its parent, hence the problem. This is easy to fix, like so:
[source, java, subs="{sub-order}"]
----
context.setClassLoader(new WebAppClassLoader(this.getClass().getClassLoader(), context));
----
or
[source, java, subs="{sub-order}"]
----
context.setClassLoader(new WebAppClassLoader(new MyCustomClassLoader(), context));
----

19
documentation/jetty-documentation/src/main/asciidoc/old_docs/connectors/chapter.adoc
View File

@ -1,19 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[configuring-connectors]]
== Configuring Jetty Connectors
This chapter discusses various options for configuring Jetty connectors.
include::configuring-connectors.adoc[]

540
documentation/jetty-documentation/src/main/asciidoc/old_docs/connectors/configuring-connectors.adoc
View File

@ -1,540 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[jetty-connectors]]
=== Connector Configuration Overview
Connectors are the mechanism through which Jetty accepts network connections for various protocols.
Configuring a connector is a combination of configuring the following:
* Network parameters on the connector itself (for example: the listening port).
* Services the connector uses (for example: executors, schedulers).
* Connection factories that instantiate and configure the protocol for an accepted connection.
Typically connectors require very little configuration aside from setting the listening port, and enabling `X-Forwarded-For` customization when applicable.
Additional settings, including construction your own constructor Jetty XML files, are for expert configuration only.
==== Enabling Connectors
Out of the box, Jetty provides several link:#startup-modules[modules] for enabling different types of connectors, from HTTP to HTTPS, HTTP/2, and others.
If you startup Jetty with the `--list-modules=connector` command, you can see a list of all available connector modules:
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-modules=connector
Available Modules:
==================
tags: [connector]
Modules for tag 'connector':
----------------------------
Module: acceptratelimit
: Enable a server wide accept rate limit
Tags: connector
Depend: server
XML: etc/jetty-acceptratelimit.xml
Module: connectionlimit
: Enable a server wide connection limit
Tags: connector
Depend: server
XML: etc/jetty-connectionlimit.xml
Module: http
: Enables a HTTP connector on the server.
: By default HTTP/1 is support, but HTTP2C can
: be added to the connector with the http2c module.
Tags: connector, http
Depend: server
XML: etc/jetty-http.xml
Module: http-forwarded
: Adds a forwarded request customizer to the HTTP Connector
: to process forwarded-for style headers from a proxy.
Tags: connector
Depend: http
XML: etc/jetty-http-forwarded.xml
Module: http2
: Enables HTTP2 protocol support on the TLS(SSL) Connector,
: using the ALPN extension to select which protocol to use.
Tags: connector, http2, http, ssl
Depend: ssl, alpn
LIB: lib/http2/*.jar
XML: etc/jetty-http2.xml
Module: http2c
: Enables the HTTP2C protocol on the HTTP Connector
: The connector will accept both HTTP/1 and HTTP/2 connections.
Tags: connector, http2, http
Depend: http
LIB: lib/http2/*.jar
XML: etc/jetty-http2c.xml
Module: https
: Adds HTTPS protocol support to the TLS(SSL) Connector
Tags: connector, https, http, ssl
Depend: ssl
Optional: http-forwarded, http2
XML: etc/jetty-https.xml
Module: proxy-protocol-ssl
: Enables the Proxy Protocol on the TLS(SSL) Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a Proxy operating in TCP mode to transport
: details of the proxied connection to the server.
: Both V1 and V2 versions of the protocol are supported.
Tags: connector, ssl
Depend: ssl
XML: etc/jetty-proxy-protocol-ssl.xml
Module: ssl
: Enables a TLS(SSL) Connector on the server.
: This may be used for HTTPS and/or HTTP2 by enabling
: the associated support modules.
Tags: connector, ssl
Depend: server
XML: etc/jetty-ssl.xml
XML: etc/jetty-ssl-context.xml
Module: unixsocket
: Enables a Unix Domain Socket Connector that can receive
: requests from a local proxy and/or SSL offloader (eg haproxy) in either
: HTTP or TCP mode. Unix Domain Sockets are more efficient than
: localhost TCP/IP connections as they reduce data copies, avoid
: needless fragmentation and have better dispatch behaviours.
: When enabled with corresponding support modules, the connector can
: accept HTTP, HTTPS or HTTP2C traffic.
Tags: connector
Depend: server
LIB: lib/jetty-unixsocket-${jetty.version}.jar
LIB: lib/jnr/*.jar
XML: etc/jetty-unixsocket.xml
Module: unixsocket-forwarded
: Adds a forwarded request customizer to the HTTP configuration used
: by the Unix Domain Socket connector, for use when behind a proxy operating
: in HTTP mode that adds forwarded-for style HTTP headers. Typically this
: is an alternate to the Proxy Protocol used mostly for TCP mode.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-forwarded.xml
Module: unixsocket-http
: Adds a HTTP protocol support to the Unix Domain Socket connector.
: It should be used when a proxy is forwarding either HTTP or decrypted
: HTTPS traffic to the connector and may be used with the
: unix-socket-http2c modules to upgrade to HTTP/2.
Tags: connector, http
Depend: unixsocket
XML: etc/jetty-unixsocket-http.xml
Module: unixsocket-http2c
: Adds a HTTP2C connetion factory to the Unix Domain Socket Connector
: It can be used when either the proxy forwards direct
: HTTP/2C (unecrypted) or decrypted HTTP/2 traffic.
Tags: connector, http2
Depend: unixsocket-http
LIB: lib/http2/*.jar
XML: etc/jetty-unixsocket-http2c.xml
Module: unixsocket-proxy-protocol
: Enables the proxy protocol on the Unix Domain Socket Connector
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows information about the proxied connection to be
: efficiently forwarded as the connection is accepted.
: Both V1 and V2 versions of the protocol are supported and any
: SSL properties may be interpreted by the unixsocket-secure
: module to indicate secure HTTPS traffic. Typically this
: is an alternate to the forwarded module.
Tags: connector
Depend: unixsocket
XML: etc/jetty-unixsocket-proxy-protocol.xml
Module: unixsocket-secure
: Enable a secure request customizer on the HTTP Configuration
: used by the Unix Domain Socket Connector.
: This looks for a secure scheme transported either by the
: unixsocket-forwarded, unixsocket-proxy-protocol or in a
: HTTP2 request.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
...
....
To enable a connector, simply activate the associated module.
Below is an example of activating both the `http` and `https` modules in a fresh link:#startup-base-and-home[Jetty base] using the link:#start-vs-startd[start.d directory]:
[source, screen, subs="{sub-order}"]
....
[mybase] java -jar $JETTY_HOME/start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
[mybase] java -jar $JETTY_HOME/start.jar --add-to-start=http,https
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : https initialized in ${jetty.base}/start.d/https.ini
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO : Base directory was modified
[mybase] tree
.
├── etc
│   └── keystore
└── start.d
├── http.ini
└── https.ini
....
When the `http` and `https` modules were activated, so too were any modules they were dependent on, in this case `server` and `ssl`, as well as any dependencies for those modules, such as the `etc` and `ketystore` directories for `ssl`.
At this point the server has been configured with connectors for both HTTP and HTTPS and can be started:
[source, screen, subs="{sub-order}"]
....
[mybase] java -jar $JETTY_HOME/start.jar
2017-08-31 10:19:58.855:INFO::main: Logging initialized @372ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:19:59.076:INFO:oejs.Server:main: jetty-{VERSION}
2017-08-31 10:19:59.125:INFO:oejs.AbstractConnector:main: Started ServerConnector@421e98e0{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-08-31 10:19:59.150:INFO:oejus.SslContextFactory:main: x509=X509@5315b42e(jetty,h=[jetty.eclipse.org],w=[]) for SslContextFactory@2ef9b8bc(file:///var/my-jetty-base/etc/keystore,file:///var/my-jetty-base/etc/keystore)
2017-08-31 10:19:59.151:INFO:oejus.SslContextFactory:main: x509=X509@5d624da6(mykey,h=[],w=[]) for SslContextFactory@2ef9b8bc(file:///var/my-jetty-base/etc/keystore,file:///var/my-jetty-base/etc/keystore)
2017-08-31 10:19:59.273:INFO:oejs.AbstractConnector:main: Started ServerConnector@2b98378d{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-08-31 10:19:59.274:INFO:oejs.Server:main: Started @791ms
....
When modules are enabled, they are loaded with several default options.
These can be changed by editing the associated module ini file in the `start.d` directory (or the associated lines in `server.ini` if your implementation does not use `start.d`).
For example, if we examine the `http.ini` file in our `start.d` directory created above, we will see the following settings:
[source, screen, subs="{sub-order}"]
....
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
# jetty.http.port=8080
## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
## Number of acceptors (-1 picks default based on number of cores)
# jetty.http.acceptors=-1
## Number of selectors (-1 picks default based on number of cores)
# jetty.http.selectors=-1
## ServerSocketChannel backlog (0 picks platform default)
# jetty.http.acceptQueueSize=0
## Thread priority delta to give to acceptor threads
# jetty.http.acceptorPriorityDelta=0
## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230
....
To make a change to these settings, uncomment the line (by removing the #) and change the property to the desired value.
For example, if you wanted to change the HTTP port to 5231, you would edit the line as follows:
[source, screen, subs="{sub-order}"]
....
...
## Connector port to listen on
jetty.http.port=5231
...
....
Now when the server is started, HTTP connections will enter on port 5231:
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar
2017-08-31 10:31:32.955:INFO::main: Logging initialized @366ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:31:33.109:INFO:oejs.Server:main: jetty-{VERSION}
2017-08-31 10:31:33.146:INFO:oejs.AbstractConnector:main: Started ServerConnector@2ef9b8bc{HTTP/1.1,[http/1.1]}{0.0.0.0:5231}
...
2017-08-31 10:31:33.263:INFO:oejs.Server:main: Started @675ms
....
Every module has their own set of configuration options, and reviewing them all is recommended.
For additional information on the module system, please refer to our documentation on link:#startup-modules[Startup Modules].
____
[NOTE]
Editing these module files is the recommended way to edit the configuration of your server.
Making changes to the associated Jetty XML file for connectors is *not* recommended, and is for advanced users only.
If you do wish to edit Jetty XML, please see our section on managing link:#[Jetty Home and Jetty Base] to ensure your Jetty Home remains a standard of truth for your implementation.
____
==== Limiting Connections
Jetty also provides the means by which to limit connections to the server and/or contexts.
This is provided by two different modules in the distribution.
`connectionlimit`::
Applies a limit to the number of connections.
If this limit is exceeded, new connections are suspended for the time specified (in milliseconds).
`acceptratelimit`::
Limits the rate at which new connections are accepted.
If this limit is exceeded, new connections are suspended for the time specified (in milliseconds).
As with the modules listed above, these can be enabled by adding `--add-to-start=<module-name>` to the command line.
==== Advanced Configuration
Jetty primarily uses a single connector type called link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[ServerConnector].
Prior to Jetty 9, the type of the connector specified both the protocol and the implementation used; for example, selector-based non blocking I/O vs blocking I/O, or SSL connector vs non-SSL connector.
Jetty 9 has a single selector-based non-blocking I/O connector, and a collection of link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactories`] now configure the protocol on the connector.
The standard Jetty distribution comes with the following Jetty XML files that create and configure connectors; you should examine them as you read this section:
link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]::
Instantiates a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] that accepts HTTP connections (that may be upgraded to WebSocket connections).
link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-ssl.xml[`jetty-ssl.xml`]::
Instantiates a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] that accepts SSL/TLS connections.
On it's own, this connector is not functional and requires one or more of the following files to also be configured to add link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactories`] to make the connector functional.
link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`]::
Adds a link:{JDURL}/org/eclipse/jetty/server/HttpConnectionFactory.html[`HttpConnectionFactory`] to the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] configured by `jetty-ssl.xml` which combine to provide support for HTTPS.
link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http-forwarded.xml[`jetty-http-forwarded.xml`]::
Adds a link:{JDURL}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`]to the HTTP Connector to process forwarded-for style headers from a proxy.
link:{GITBROWSEURL}/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml[`jetty-http2.xml`]::
Adds a link:{JDURL}/org/eclipse/jetty/http2/server/HTTP2ServerConnectionFactory.html[`Http2ServerConnectionFactory`] to the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] configured by `jetty-ssl.xml` to support the http2 protocol.
link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-server/src/main/config/etc/jetty-alpn.xml[`jetty-alpn.xml`]::
Adds an link:{JDURL}/org/eclipse/jetty/alpn/server/ALPNServerConnectionFactory.html[`ALPNServerConnectionFactory`] to the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] configured by `jetty-ssl.xml` which allows the one SSL connector to support multiple protocols with the ALPN extension used to select the protocol to be used for each connection.
==== Constructing a ServerConnector
The services a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] instance uses are set by constructor injection and once instantiated cannot be changed.
Many of the services may be defaulted with null or 0 values so that a reasonable default is used, thus for most purposes only the Server and the connection factories need to be passed to the connector constructor. In Jetty XML (that is, in link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]) you can do this by:
[source, xml, subs="{sub-order}"]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="factories">
<Array type="org.eclipse.jetty.server.ConnectionFactory">
<!-- insert one or more factories here -->
</Array>
</Arg>
<!-- set connector fields here -->
</New>
----
You can see the other arguments that can be passed when constructing a `ServerConnector` in the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html#ServerConnector%28org.eclipse.jetty.server.Server,%20java.util.concurrent.Executor,%20org.eclipse.jetty.util.thread.Scheduler,%20org.eclipse.jetty.io.ByteBufferPool,%20int,%20int,%20org.eclipse.jetty.server.ConnectionFactory...%29[Javadoc].
Typically the defaults are sufficient for almost all deployments.
[[jetty-connectors-network-settings]]
==== Network Settings
You can configure connector network settings by calling setters on the connector before it is started.
For example, you can set the port with the Jetty XML:
[source, xml, subs="{sub-order}"]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="factories"><!-- insert one or more factories here --></Arg>
<Set name="port">8080</Set>
</New>
----
Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line.
Thus typically the port is set within Jetty XML, but uses the `Property` element to be customizable:
[source, xml, subs="{sub-order}"]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="factories"><!-- insert one or more factories here --></Arg>
<Set name="port"><Property name="jetty.http.port" default="8080"/></Set>
</New>
----
The network settings available for configuration on the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] include:
.Connector Configuration
[width="100%",cols="22%,78%",options="header",]
|=======================================================================
|Field |Description
|host |The network interface this connector binds to as an IP address or a hostname.
If null or 0.0.0.0, bind to all interfaces.
|port |The configured port for the connector or 0 a random available port may be used (selected port available via `getLocalPort()`).
|idleTimeout |The time in milliseconds that the connection can be idle before it is closed.
|defaultProtocol |The name of the default protocol used to select a `ConnectionFactory` instance. This defaults to the first `ConnectionFactory` added to the connector.
|stopTimeout |The time in milliseconds to wait before gently stopping a connector.
|acceptQueueSize |The size of the pending connection backlog.
The exact interpretation is JVM and operating system specific and you can ignore it.
Higher values allow more connections to wait pending an acceptor thread.
Because the exact interpretation is deployment dependent, it is best to keep this value as the default unless there is a specific connection issue for a specific OS that you need to address.
|reuseAddress |Allow the server socket to be rebound even if in http://www.ssfnet.org/Exchange/tcp/tcpTutorialNotes.html[TIME_WAIT].
For servers it is typically OK to leave this as the default true.
|=======================================================================
[[jetty-connectors-http-configuration]]
==== HTTP Configuration
The link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[`HttpConfiguration`] class holds the configuration for link:{JDURL}/org/eclipse/jetty/server/HttpChannel.html[`HttpChannel`]s, which you can create 1:1 with each HTTP connection or 1:n on a multiplexed HTTP/2 connection.
Thus a `HttpConfiguration` object is injected into both the HTTP and HTTP/2 connection factories.
To avoid duplicate configuration, the standard Jetty distribution creates the common `HttpConfiguration` instance in link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty.xml[`jetty.xml`], which is a `Ref` element then used in link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`], link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`] and in link:{GITBROWSEURL}/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml[`jetty-http2.xml`].
A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] is:
[source, xml, subs="{sub-order}"]
----
<New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="secureScheme">https</Set>
<Set name="securePort"><Property name="jetty.ssl.port" default="8443" /></Set>
<Set name="outputBufferSize">32768</Set>
<Set name="requestHeaderSize">8192</Set>
<Set name="responseHeaderSize">8192</Set>
</New>
----
This example HttpConfiguration may be used by reference to the ID "`httpConfig`":
[source, xml, subs="{sub-order}"]
----
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="factories">
<Array type="org.eclipse.jetty.server.ConnectionFactory">
<Item>
<New class="org.eclipse.jetty.server.HttpConnectionFactory">
<Arg name="config"><Ref refid="httpConfig" /></Arg>
</New>
</Item>
</Array>
</Arg>
<!-- ... -->
</New>
</Arg>
</Call>
----
This same `httpConfig` is referenced by the link:{JDURL}/org/eclipse/jetty/server/handler/SecuredRedirectHandler.html[`SecuredRedirectHandler`] when redirecting secure requests.
Please note that if your `httpConfig` does not include a `secureScheme` or `securePort` or there is no `HttpConfiguration` present these types of secured requests will be returned a `403` error.
For SSL-based connectors (in `jetty-https.xml` and `jetty-http2.xml`), the common "`httpConfig`" instance is used as the basis to create an SSL specific configuration with ID "`sslHttpConfig`":
[source, xml, subs="{sub-order}"]
----
<New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Arg><Ref refid="httpConfig"/></Arg>
<Call name="addCustomizer">
<Arg><New class="org.eclipse.jetty.server.SecureRequestCustomizer"/></Arg>
</Call>
</New>
----
This adds a `SecureRequestCustomizer` which adds SSL Session IDs and certificate information as request attributes.
==== SSL Context Configuration
The SSL/TLS connectors for HTTPS and HTTP/2 require a certificate to establish a secure connection.
Jetty holds certificates in standard JVM keystores and are configured as keystore and truststores on a link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html[`SslContextFactory.Server`] instance that is injected into an link:{JDURL}/org/eclipse/jetty/server/SslConnectionFactory.html[`SslConnectionFactory`] instance.
An example using the keystore distributed with Jetty (containing a self signed test certificate) is in link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`].
Read more about SSL keystores in link:#configuring-ssl[Configuring SSL].
==== Proxy / Load Balancer Connection Configuration
Often a Connector needs to be configured to accept connections from an intermediary such as a Reverse Proxy and/or Load Balancer deployed in front of the server.
In such environments, the TCP/IP connection terminating on the server does not originate from the client, but from the intermediary, so that the Remote IP and port number can be reported incorrectly in logs and in some circumstances the incorrect server address and port may be used.
Thus Intermediaries typically implement one of several de facto standards to communicate to the server information about the original client connection terminating on the intermediary.
Jetty supports the `X-Forwarded-For` header and the http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] mechanisms as described below.
____
[NOTE]
The XML files in the Jetty distribution contain commented out examples of both the `X-Forwarded-For` and http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] mechanisms.
When using those examples, it is recommended that the XML in the Jetty distribution is not edited.
Rather the files should be copied into a Jetty base directory and then modified.
____
===== X-Forward-for Configuration
The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
These headers can be interpreted by an instance of link:{JDURL}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] which can be added to a `HttpConfiguration` as follows:
[source, xml, subs="{sub-order}"]
----
<New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="outputBufferSize">32768</Set>
<Set name="requestHeaderSize">8192</Set>
<Set name="responseHeaderSize">8192</Set>
<Call name="addCustomizer">
<Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
</Call>
</New>
----
===== Proxy Protocol
The http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] is the _de facto_ standard created by HAProxy and used by environments such as Amazon Elastic Cloud.
This mechanism is independent of any protocol, so it can be used for HTTP2, TLS etc.
The information about the client connection is sent as a small data frame on each newly established connection.
In Jetty, this protocol can be handled by the link:{JDURL}/org/eclipse/jetty/server/ProxyConnectionFactory.html[`ProxyConnectionFactory`] which parses the data frame and then instantiates the next `ConnectionFactory` on the connection with an end point that has been customized with the data obtained about the original client connection.
The connection factory can be added to any link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] and should be the first link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactory`].
An example of adding the factory to a HTTP connector is shown below:
[source, xml, subs="{sub-order}"]
----
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="factories">
<Array type="org.eclipse.jetty.server.ConnectionFactory">
<Item>
<New class="org.eclipse.jetty.server.ProxyConnectionFactory"/>
</Item>
<Item>
<New class="org.eclipse.jetty.server.HttpConnectionFactory">
<Arg name="config"><Ref refid="httpConfig" /></Arg>
</New>
</Item>
</Array>
</Arg>
<Set name="host"><Property name="jetty.host" /></Set>
<Set name="port"><Property name="jetty.http.port" default="80" /></Set>
</New>
</Arg>
</Call>
----

22
documentation/jetty-documentation/src/main/asciidoc/old_docs/contexts/chapter.adoc
View File

@ -1,22 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[configuring-contexts]]
== Configuring Contexts
This chapter discusses various options for configuring Jetty contexts.
include::setting-context-path.adoc[]
include::temporary-directories.adoc[]
include::custom-error-pages.adoc[]
include::setting-form-size.adoc[]

168
documentation/jetty-documentation/src/main/asciidoc/old_docs/contexts/custom-error-pages.adoc
View File

@ -1,168 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[custom-error-pages]]
=== Creating Custom Error Pages
The following sections describe several ways to create custom error pages in Jetty.
==== Defining error pages in web.xml
You can use the standard webapp configuration file located in `webapp/WEB-INF/web.xml` to map errors to specific URLs with the `error-page` element.
This element creates a mapping between the error-code or exception-type to the location of a resource in the web application.
* `error-code` - an integer value
* `exception-type` - a fully qualified class name of a Java Exception type
* `location` - location of the resource in the webapp relative to the root of the web application. Value should start with `/`.
Error code example:
[source, xml, subs="{sub-order}"]
----
<error-page>
<error-code>404</error-code>
<location>/jspsnoop/ERROR/404</location>
</error-page>
----
Exception example:
[source, xml, subs="{sub-order}"]
----
<error-page>
<exception-type>java.io.IOException</exception-type>
<location>/jspsnoop/IOException</location>
</error-page>
----
The error page mappings created with the error-page element will redirect to a normal URL within the web application and will be handled as a normal request to that location and thus may be static content, a JSP or a filter and/or servlet.
When handling a request generated by an error redirection, the following request attributes are set and are available to generate dynamic content:
jakarta.servlet.error.exception::
The exception instance that caused the error (or null).
jakarta.servlet.error.exception_type::
The class name of the exception instance that caused the error (or null).
jakarta.servlet.error.message::
The error message.
jakarta.servlet.error.request_uri::
The URI of the request with an error.
jakarta.servlet.error.servlet_name::
The Servlet name of the servlet that the request was
dispatched to.
jakarta.servlet.error.status_code::
The status code of the error (e.g. 404, 500 etc.).
==== Configuring error pages context files
You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
Context files are normally located in `${jetty.base}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
<Set name="war">
<SystemProperty name="jetty.base" default="."/>/webapps/test
</Set>
<!-- by Code -->
<Get name="errorHandler">
<Call name="addErrorPage">
<Arg type="int">404</Arg>
<Arg type="String">/jspsnoop/ERROR/404</Arg>
</Call>
</Get>
<!-- by Exception -->
<Get name="errorHandler">
<Call name="addErrorPage">
<Arg>
<Call class="java.lang.Class" name="forName">
<Arg type="String">java.io.IOException</Arg>
</Call>
</Arg>
<Arg type="String">/jspsnoop/IOException</Arg>
</Call>
</Get>
<!-- by Code Range -->
<Get name="errorHandler">
<Call name="addErrorPage">
<Arg type="int">500</Arg>
<Arg type="int">599</Arg>
<Arg type="String">/dump/errorCodeRangeMapping</Arg>
</Call>
</Get>
</Configure>
----
==== Custom ErrorHandler class
If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of `ErrorProcessor` configured either the Context or the Server.
An `ErrorProcessor` may extend the `ErrorProcessor` class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:
[source, java, subs="{sub-order}"]
----
void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException
void handleErrorPage(HttpServletRequest request, Writer writer, int code, String message) throws IOException
void writeErrorPage(HttpServletRequest request, Writer writer, int code, String message, boolean showStacks) throws IOException
void writeErrorPageHead(HttpServletRequest request, Writer writer, int code, String message) throws IOException
void writeErrorPageBody(HttpServletRequest request, Writer writer, int code, String message, boolean showStacks) throws IOException
void writeErrorPageMessage(HttpServletRequest request, Writer writer, int code, String message, String uri) throws IOException
void writeErrorPageStacks(HttpServletRequest request, Writer writer) throws IOException
----
An `ErrorProcessor` instance may be set on a Context by calling the `ContextHandler.setErrorHandler` method. This can be done by embedded code or via context IoC XML.
For example:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.server.handler.ContextHandler">
...
<Set name="errorHandler">
<New class="com.acme.handler.MyErrorHandler"/>
</Set>
...
</Configure>
----
An `ErrorProcessor` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML:
[source, xml, subs="{sub-order}"]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
...
<Call name="addBean">
<Arg>
<New class="com.acme.handler.MyErrorHandler"/>
</Arg>
</Call>
...
</Configure>
----
==== Server level 404 error
It is possible to get a 'page not found' when a request is made to the server for a resource that is outside of any registered contexts.
As an example, you have a domain name pointing to your public server IP, yet no context is registered with Jetty to serve pages for that domain.
As a consequence, the server, by default, gives a listing of all contexts running on the server.
One of the quickest ways to avoid this behavior is to create a catch all context.
Create a "root" web app mapped to the "/" URI, and use the `index.html` redirect to whatever place with a header directive.

55
documentation/jetty-documentation/src/main/asciidoc/old_docs/contexts/setting-context-path.adoc
View File

@ -1,55 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[setting-context-path]]
=== Setting a Context Path
The context path is the prefix of a URL path that is used to select the context(s) to which an incoming request is passed. Typically a URL in a Java servlet server is of the format `http://hostname.com/contextPath/servletPath/pathInfo`, where each of the path elements can be zero or more / separated elements.
If there is no context path, the context is referred to as the _root_ context.
The root context must be configured as `/` but is reported as the empty string by the servlet API `getContextPath()` method.
How you set the context path depends on how you deploy the web application (or `ContextHandler`).
[[using-embedded-deployment]]
==== Using Embedded Deployment
If you run Jetty from code as an embedded server (see link:#advanced-embedding[Embedding]), setting the context path is a matter of calling the `setContextPath` method on the `ContextHandler` instance (or `WebAppContext` instance).
[[usng-the-context-provider]]
==== By naming convention
If a web application is deployed using the WebAppProvider of the DeploymentManager without an XML IoC file, then the name of the WAR file is used to set the context path:
* If the WAR file is named myapp.war, then the context will be deployed with a context path of `/myapp`
* If the WAR file is named ROOT.WAR (or any case insensitive variation), then the context will be deployed with a context path of `/`
* If the WAR file is named ROOT-foobar.war ( or any case insensitive variation), then the context will be deployed with a context path of `/` and a virtual host of "foobar"
[[using-the-webapp-provider]]
==== By Deployer configuration
If a web application is deployed using the `WebAppProvider` of the `DeploymentManager` with an XML IoC file to configure the context, then the `setContextPath` method can be called within that file.
For example:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
...
</Configure>
----
[[embedding-web-inf-jetty-web.xml-file]]
==== Embedding a WEB-INF/jetty-web.xml File
You can also set the context path for webapps by embedding a `WEB-INF/jetty-web.xml` file in the WAR, which uses the same XML IoC format as the deployer example above.
However this is not the preferred method as it requires the web application to be modified.

77
documentation/jetty-documentation/src/main/asciidoc/old_docs/contexts/setting-form-size.adoc
View File

@ -1,77 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[setting-form-size]]
=== Setting Max Form Size
When a client issues a POST request with `Content-Type: application/x-www-form-urlencoded` there are 2 configurable limits imposed to help protect the server against denial of service attacks by malicious clients sending huge amounts of data.
There is a maximum form size limit, and a maximum form keys limit.
The default maximum form size Jetty permits is 200000 bytes.
The default maximum form keys Jetty permits is 1000 keys.
You can change these defaults for a particular webapp, or all webapps within the same JVM.
==== For a Single Webapp
The methods to invoke are:
* `ContextHandler.setMaxFormContentSize(int maxSize);`
* `ContextHandler.setMaxFormKeys(int max);`
This can be done either in a context XML deployment descriptor external to the webapp, or in a `jetty-web.xml` file in the webapp's `WEB-INF` directory.
In either case the syntax of the XML file is the same:
[source,xml,subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- Max Form Size -->
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<Set name="maxFormContentSize">400000</Set>
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<!-- Max Form Keys -->
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<Set name="maxFormKeys">400</Set>
</Configure>
----
==== For All Apps in the JVM
Use the system properties:
* `org.eclipse.jetty.server.Request.maxFormContentSize` - the maximum size of Form Content allowed
* `org.eclipse.jetty.server.Request.maxFormKeys` - the maximum number of Form Keys allowed
This can be set on the command line or in the `$JETTY_BASE\start.ini` or any `$JETTY_BASE\start.d\*.ini` link:#startup-modules[module ini file.]
Using `$JETTY_BASE\start.d\server.ini` as an example:
[source,console,subs="{sub-order}"]
----
# ---------------------------------------
# Module: server
# Enables the core Jetty server on the classpath.
# ---------------------------------------
--module=server
### Common HTTP configuration
## Scheme to use to build URIs for secure redirects
# jetty.httpConfig.secureScheme=https
...
-Dorg.eclipse.jetty.server.Request.maxFormContentSize=400000
-Dorg.eclipse.jetty.server.Request.maxFormKeys=400
----

205
documentation/jetty-documentation/src/main/asciidoc/old_docs/contexts/temporary-directories.adoc
View File

@ -1,205 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[ref-temporary-directories]]
=== Temporary Directories
Jetty itself has no temporary directories, but you can assign a directory for each web application, into which the WAR is unpacked, JSPs compiled on-the-fly, etc.
If you do not assign a specific temporary directory, Jetty will create one as needed when your web application starts.
Whether you set the location of the temporary directory - or you let Jetty create one for you - you also have a choice to either keep or delete the temporary directory when the web application stops.
==== The Default Temp Directory
By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:
....
"jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"
....
For example:
....
jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir
....
Where `0.0.0.0` is the host address, `8080` is the port, `test.war` is the resourceBase, `test` is the context path (with / converted to _), `any` is the virtual host, and `randomdigits` are a string of digits guaranteed to be unique.
Once the temp directory is created, it is retrievable as the value (as a File) of the context attribute `jakarta.servlet.context.tempdir.`
===== The location of the temp directory
By default, Jetty will create this directory inside the directory named by the `java.io.tmpdir` System property.
You can instruct Jetty to use a different parent directory by setting the context attribute `org.eclipse.jetty.ee9.webapp.basetempdir` to the name of the desired parent directory.
The directory named by this attribute _must_ exist and be __writeable__.
As usual with Jetty, you can either set this attribute in a context xml file, or you can do it in code.
Here's an example of setting it in an xml file:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
<Set name="war">foo.war</Set>
<Call name="setAttribute">
<Arg>org.eclipse.jetty.ee9.webapp.basetempdir</Arg>
<Arg>/home/my/foo</Arg>
</Call>
</Configure>
----
The equivalent in code is:
[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("org.eclipse.jetty.ee9.webapp.basetempdir", "/tmp/foo");
----
==== Setting a Specific Temp Directory
There are several ways to use a particular directory as the temporary directory:
===== Call WebAppContext.setTempDirectory(String dir)
As before this can be accomplished with an XML file or directly in code.
Here is an example of setting the temp directory in XML:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
<Set name="war">foo.war</Set>
<Set name="tempDirectory">/some/dir/foo</Set>
</Configure>
----
And here is an example of doing it with java code:
[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setTempDirectory(new File("/some/dir/foo"));
----
===== Setting the jakarta.servlet.context.tempdir Context Attribute
You should set this context attribute with the name of directory you want to use as the temp directory.
Again, you can do this in XML:
[source, xml, subs="{sub-order}"]
----
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/test</Set>
<Set name="war">foo.war</Set>
<Call name="setAttribute">
<Arg>jakarta.servlet.context.tempdir</Arg>
<Arg>/some/dir/foo</Arg>
</Call>
</Configure>
----
Or in java:
[source, java, subs="{sub-order}"]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("jakarta.servlet.context.tempdir", "/some/dir/foo");
----
Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the `jakarta.servlet.context.tempdir` attribute of the web application.
____
[NOTE]
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning link:http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421[caching of jar contents.]
____
===== Setting the Temp Directory on the Command Line
You can set the location of the temp directory on the command line when Jetty starts up in two ways.
First is the most straightforward, simply add it to your command line when starting Jetty.
[source, screen, subs="{sub-order}"]
----
[my-base]$ java -jar /path/to/jetty-home/start.jar -Djava.io.tmpdir=/path/to/desired/directory
----
Alternately, this can be defined in a link:#startup-modules[module.]
The `jvm` module packaged with Jetty is set up to add additional JVM options.
After enabling the module (using the `--add-to-start=jvm` command), edit the `jvm.ini` file and add the location to the temporary directory.
You will also need verify the line including the `--exec` command is not commented out, as this is required for Jetty to start a new, forked JVM.
Below is an example of the standard `jvm.ini` file altered to include a reference to a temp directory.
[source, screen, subs="{sub-order}"]
....
# ---------------------------------------
# Module: jvm
# A noop module that creates an ini template useful for
# setting JVM arguments (eg -Xmx )
# ---------------------------------------
--module=jvm
## JVM Configuration
## If JVM args are include in an ini file then --exec is needed
## to start a new JVM from start.jar with the extra args.
##
## If you wish to avoid an extra JVM running, place JVM args
## on the normal command line and do not use --exec
--exec
# -Xmx2000m
# -Xmn512m
# -XX:+UseConcMarkSweepGC
# -XX:ParallelCMSThreads=2
# -XX:+CMSClassUnloadingEnabled
# -XX:+UseCMSCompactAtFullCollection
# -XX:CMSInitiatingOccupancyFraction=80
# -internal:gc
# -XX:+PrintGCDateStamps
# -XX:+PrintGCTimeStamps
# -XX:+PrintGCDetails
# -XX:+PrintTenuringDistribution
# -XX:+PrintCommandLineFlags
# -XX:+DisableExplicitGC
-Djava.io.tmpdir=/path/to/desired/directory
....
==== The "work" Directory
It is possible to create a directory named `work` in the `$\{jetty.base}` directory.
If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in `$\{jetty.base}`.
Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when Jetty exits (or more correctly speaking, the `temp` directory corresponding to a context is not cleaned up when that context stops).
When a `work` directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string.
This ensures the name of the directory remains consistent across context restarts.
==== Persisting the temp directory
Sometimes it is useful to keep the contents of the temporary directory between restarts of the web application.
By default, Jetty will *not* persist the temp directory.
To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
____
[NOTE]
Be aware that if you call `setPersistTempDirectory(true)`, but let Jetty create a new temp directory each time (i.e. you do NOT set an explicit temp directory), then you will accumulate temp directories in your chosen temp directory location.
____

21
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/bugs.adoc
View File

@ -1,21 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[bugs]]
=== Issues, Features, and Bugs
As with any constantly evolving software project, there will be issues, features, and bugs.
We want to know whats bugging you!
File bugs as Issues in our Github repository http://github.com/jetty/jetty.project[Issues at Github]

28
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/chapter.adoc
View File

@ -1,28 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[advanced-contributing]]
== Contributing to Jetty
There are many ways to contribute to Jetty, from hardened developers looking to sharpen their skills to neophytes interested in working with an open source project for the first time.
Here we show ways to interact with the Jetty community, give feedback to the developers and contribute patches to both core Jetty code and even this document.
include::community.adoc[]
include::documentation.adoc[]
include::source-build.adoc[]
include::coding-standards.adoc[]
include::bugs.adoc[]
include::patches.adoc[]
include::security.adoc[]
include::releasing-jetty.adoc[]
include::release-testing.adoc[]

84
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/coding-standards.adoc
View File

@ -1,84 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[coding-standards]]
=== Coding Standards
Jetty uses number of conventions for its source code.
==== Code Formatting
Jetty uses the code formatting the following project specifies.
http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/jetty-eclipse-java-format.xml[Eclipse Java Formatting]
==== Code Templates
Jetty specifies the following code templates for use by the project developers.
http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/jetty-eclipse-codetemplates.xml[Eclipse Code Templates]
==== Code Conventions
The following is an example of the Java formatting and naming styles to apply to Jetty:
[source, java, subs="{sub-order}"]
----
import some.exact.ClassName; // GOOD
import some.wildcard.package.*; // BAD!
package org.always.have.a.package;
/* --------------------------------------------------------- */
/** Always have some javadoc
*/
class MyClassName
{
// indent by 4 spaces.
// use spaced to indent
// The code must format OK with default tabsize of 8.
private static final int ALL_CAPS_FOR_PUBLIC_CONSTANTS=1;
// Field prefixed with __ for static of _ for normal fields.
// This convention is no longer mandatory, but any given
// class should either consistently use this style or not.
private static String __staticField;
private Object _privateField;
// use getters and setters rather than public fields.
public void setPrivateField(Object privateField)
{
_privateField=privateField;
}
public Object getPrivateField()
{
return _privateField;
}
public void doSomething()
throws SomeException
{
Object local_variable = _privateField;
if (local_variable==null)
{
// do Something
}
}
}
----

38
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/community.adoc
View File

@ -1,38 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[community]]
=== Community
Developers and users alike are welcome to engage the Jetty community.
We all have day jobs here so don't just ask questions and get frustrated if no one answers right away.
Stick around to hear an answer, one is likely coming at some point!
[[community-mailing-lists]]
==== Mailing Lists
We have a number of options for people that wish to subscribe to our mailing lists.
* Jetty Developers List
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-dev
** Archives - https://dev.eclipse.org/mhonarc/lists/jetty-dev/
* Jetty Users List
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-users
** Archives - https://dev.eclipse.org/mhonarc/lists/jetty-users/
* Jetty Announcements List
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-announce
** Archives - https://dev.eclipse.org/mhonarc/lists/jetty-announce/
* Jetty Commit List
** Join - https://dev.eclipse.org/mailman/listinfo/jetty-commit
** Archives - https://dev.eclipse.org/mhonarc/lists/jetty-commit/

234
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/documentation.adoc
View File

@ -1,234 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[contributing-documentation]]
=== Documentation
This document is produced using a combination of maven, git, and asciidoc.
We welcome anyone and everyone to contribute to the content of this book.
Below is the information on how to obtain the source of this book and to build it as well as information on how to contribute back to it.
Note: All contributions to this documentation are under the EPLv1 and the copyright is assigned to Mort Bay.
==== Tools
You will need:
git::
This documentation is part of the Jetty project so all contributions must be through the normal Jetty contribution process.
+
You can go one of two ways for using git, if you are familiar with SCM's and the command line interface feel free to install and use git from there.
Otherwise we would recommend you use the github client itself as it will help with some of the workflow involved with working with git.
All contributions much be signed and can be pulled into Jetty through the normal pull request process.
maven 3::
We build the documentation with maven 3 which can be found at http://maven.apache.org[Apache Maven].
==== Render Chain
The Jetty documentation is all written in asciidoc which is used as the origin format.
The maven build uses the asciidoctor-maven-plugin to process all of the .adoc files into a single docbook file which is then used to produce the final output.
We use this intermediary step in order to primarily produce chunked html which we then deploy to the Eclipse Jetty website.
However we can also use this docbook output to produce pdf files, epub books or even Eclipse Help files should we so desire.
==== Getting Started (cli)
First you need to obtain the source of the documentation project.
Clone the repository:
[source, screen, subs="{sub-order}"]
....
$ git clone https://github.com/jetty/jetty.project.git
....
You will now have a local directory with all of jetty, including the jetty-documentation.
Now we move on to building it.
[source, screen, subs="{sub-order}"]
....
$ cd jetty.project/jetty-documentation
$ mvn install
....
While maven is running you may see a lot of files being downloaded.
If you are not familiar with maven, then what you are seeing is maven setting up the execution environment for generating the documentation.
This build will first produce docbook xml and then through the docbkx-maven-plugin generate the chunked html output.
The downloads are all of the java dependencies that are required to make this build work.
After a while the downloading will stop and you should see the execution of the asciidoctor-maven-plugin followed by the docbkx-maven-plugin.
[source, screen, subs="{sub-order}"]
....
[INFO] --- asciidoctor-maven-plugin:1.5.3:process-asciidoc (output-html) @ jetty-documentation ---
[INFO] Rendered /Users/jesse/src/projects/jetty/jetty-docs/src/main/asciidoc/index.adoc
[INFO]
[INFO] Processing input file: index.xml
[INFO] Applying customization parameters
[INFO] Chunking output.
[INFO] See /Users/jesse/src/projects/jetty/jetty-docs/target/docbkx/html/index for generated file(s)
....
The build is finished once you see a message akin to this:
[source, screen, subs="{sub-order}"]
....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 7.014s
[INFO] Finished at: Tue Oct 25 14:15:37 CDT 2011
[INFO] Final Memory: 14M/229M
[INFO] ------------------------------------------------------------------------
....
You may now open your web browser and browse to the first page of the html output to see what you have produced!
Generally you can do this with File -> Open File -> which will open a file system browsing screen, navigate to your jetty-documentation directory and then further into target/docbkx/html/index/index.html which is the first page of the produced documentation.
____
[TIP]
If the build is broken, feel free to notify us.
____
==== Making Changes
Now that you have built the documentation, you want to edit it and make some changes.
We'll now have to take a bit of as step back and look at how git and github works.
In the above example you have cloned directly from our canonical documentation repository.
Obviously we can not allow anyone immediate access to this repository so you must make a fork of it for your own and then issue back pull requests to build up documentation karma.
In English that means that you would go to the url of the documentation in github:
....
https://github.com/jetty/jetty.project
....
When you are on this page you will see a little button called 'Fork' which you can click and you will be taken back to your main page on github where you have a new repository.
When you checkout this repository you are free to commit to your heart's delight all the changes you so direly wish to see in the Jetty documentation.
You can clone it to your local machine and build it the same way as above.
So let's start small with a little example.
Find some paragraph in the documentation that you think needs changed. Locate that in the local checkout and make the change.
Now follow the process to push that change back into Jetty proper.
Do make sure the change works and the build isn't broken though so make sure you run maven and check the output.
Then commit the change.
[source, screen, subs="{sub-order}"]
....
$ git commit -s -m "Tweaked the introduction to fix a horrid misspelled word." src/main/asciidoc/quickstart/introduction/topic.xml
....
____
[NOTE]
In order for us to accept your commit into the Jetty repository you must have an Eclipse CLA on file and sign your commit.
Please check out the link:#contributing-cla[patches] section for more information.
____
This will commit the change in your local repository.
You can then push the change up to your repository on github.
[source, screen, subs="{sub-order}"]
....
$ git push
....
Now you'll see some output showing that your change has been propagated to your repository on github.
In fact if you navigate to that repository at the top of the files list you should see your comment there.
Success, your change is now positioned for notifying us about it!
If you click on the commit message itself you'll be taken to a screen that shows what files were changed in that commit. In the upper right corner is a button for 'Pull Request'.
When you select this and follow the workflow we will then be notified of your contribution and will be able to apply it to our git repository upon review.
Thats it! You have successfully contributed to the documentation efforts of the Jetty project.
After enough of these sorts of contributions and building up good community karma, you may be asked to join us as a committer on the documentation.
==== Conventions
Below is list of conventions that should be followed when developing documentation within this framework.
These are not set in stone and should be updated as we learn more.
ventilated prose::
Each sentence should be on its own line with a hard return at the end of the line.
Asciidoc rendering does not treat this style as separate lines and will produce paragraphs correctly.
The primary benefit is that you can easily see changes between scm versions of files, and it makes it trivial to quickly look through a pull request.
Additional benefits are the ability to comment out a sentence mid paragraph or move sentences around within a paragraph.
Enabling Soft Line Wrap in your favorite editor can make this a bit easier to stomach.
id's::
Critically important for being able to generate url's that can be used in a persistent fashion.
Without sane id's the chapters and sections will have generated id which are rooted in some obscure location based
voodoo.
A url using these 'e12c8673' type links will not be durable across generations of the documentation.
These id's need to be used on chapters and sections two deep, and anywhere that you intend to cross link deeper.
+
The id values go into a global namespace so they must be unique across the entire document or the last example will win and any cross links will go there.
Below is an example of an id.
....
[[this-id-an-id]]
....
link vs xref::
The `link:` item should be generally used for linking around the document when you want to choose the text that will be rendered in the link itself.
However if you are linking to a section and want to use the title itself as the link text, use the `xref:` tag without the hashmark in front of the link id.
version differences::
In general differences in functionality within a release should go into nested sections and use titles like 'Prior to: ##' or 'In version: ##'.
license blocks::
Each adoc file should contain the license block that exists in the index.adoc file and a copy has been added to the bottom of this page as well for reference.
....
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
....
Some admonition examples:
______________________________________________
[NOTE]
A note about the previous case to be aware of.
______________________________________________
________________________________________
[IMPORTANT]
Important notes are marked with an icon.
________________________________________
________________________________
[TIP]
Tips that make your life easier.
________________________________
_______________________________________________________
[CAUTION]
Places where you have to be careful what you are doing.
_______________________________________________________
__________________________________________________________________________________________________________________
[WARNING]
Where extreme care has to be taken. Data corruption or other nasty
things may occur if these warnings are ignored.
__________________________________________________________________________________________________________________
==== Oddities
* If an included file ends with a list entry, it needs to have two empty lines at the end of the file in order for the section rendering to work correctly.

104
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/patches.adoc
View File

@ -1,104 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[contributing-patches]]
=== Contributing Patches
We love seeing people contribute patches to the Jetty project and the process is relatively simple.
The requirements to commit are modest but very important to the Eclipse Foundation and the intellectual property of the open source project.
The following is the general process by which we operate.
* You must have a signed Eclipse Contributor Agreement.
* This agreement must be under the _same_ email address as the Git pull request originates from.
* The commit must be signed.
* When the pull request is made, a git-hook will validate the email address.
** If the result is a green checkbox then the Jetty committers can review the pull request.
** If the result is a red X then there is absolutely nothing the Jetty committers can do to accept the commit at this point.
* This may not be the final form a commit will take, there may be some back and forth and you may be asked to re-issue a pull request.
Not everything is specifically relevant since we are at GitHub but the crux of things are detailed there.
The ECA is *critically* important to the process.
[[contributing-eca]]
==== Sign an Eclipse Contributor Agreement (ECA)
The Eclipse Foundation has a strong Intellectual Property policy which tracks contributions in detail to ensure that:
1. Did the contributor author 100% of the content?
2. Does the contributor have the rights to contribute this content to Eclipse?
3. Is the contribution under the project’s license(s) (e.g. EPL)
A contributor needs to e-sign a Eclipse Contributor Agreement (for more explanation see the http://www.eclipse.org/legal/ecafaq.php[Eclipse ECA FAQ] ) regardless of how their contribution patch is provided.
You can familiarize yourself with the Eclipse wiki page at http://wiki.eclipse.org/Development_Resources/Contributing_via_Git[Contributing via Git].
In order to have a pull request accepted by any Eclipse project you *must* complete this agreement.
____
[TIP]
Log into the https://www.eclipse.org[Eclipse home page] (you will need to create an account with the Eclipse Foundation if you have not already done so), click on "Eclipse ECA", and complete the form.
Be sure to use the _same email address_ when you create any Git commit records.
____
[[contributing-git-config]]
==== Configuring Git
GitHub has copious amounts of quality documentation on how to interact with the system and you will minimally need to configure the user.email property.
Check out the following link:https://help.github.com/articles/setting-your-email-in-git[guide on GitHub] for more information.
[[contributing-making-the-commit]]
==== Making the Commit
When making the commit for the pull request it is _vital_ that you "sign-off" on the commit using `git commit -s` option.
Without this sign-off, your patch cannot be applied to the Jetty repository because it will be rejected.
You can check out the link:https://help.github.com/articles/signing-tags-using-gpg[guide at Github] for more information.
____
[TIP]
One way to think of this is that when you sign the ECA you are indicating that you are free to contribute to eclipse, but that doesn't mean everything you ever do can be contributed.
Using the commit signing mechanism indicates that your commit is under the auspices of your agreement.
____
If a pull request is for a particular issue in our repository then the format of the commit message is important.
The message should follow the form "Issue #123 <description of the commit>".
When the Jetty project runs releases we have an automated process that scans for commits with this format for inclusion in our VERSION.txt file.
[source, screen]
----
> git commit -s -m "Issue #123 resolving the issue by adding widget"
----
[[contributing-the-pull-request]]
==== The Pull Request
Pull requests are very much a GitHub process so best link:https://help.github.com/articles/creating-a-pull-request[explained by Github].
[[contributing-our-policies]]
==== Our Policies
We wholeheartedly welcome contributions to Jetty and will do our best to process them in a timely fashion.
While not every contribution will be accepted, our commitment is to work with interested parties on the things they care about.
With that in mind, we can only handle pull requests with actively engaged parties.
We reserve the right to abandon pull requests whose authors do no respond in a timely fashion.
We will generally adhere to the following time frames for contributions:
* Invalid Pull Requests - 1 week
** These pull requests do not follow the contribution requirements for some reason, be it missing contributor agreement or the wrong email.
** We will try and follow up with the pull request author to resolve the issue but much of this is out of our hands and are between committer and the Eclipse Foundation.
** If we do not hear from the contributor after a week we will close the pull request.
* Valid Pull Requests - 2 weeks
** These pull requests have a green check mark after the commit title.
** If the pull request can be immediately applied we will do so.
** There may need to be some conversation on the issue in which case a committer will follow up with the author in the pull request.
** If the original contributor does not respond within 2 weeks we may close the commit.
** If we see value in the commit yet the author has not responded after 2 weeks we may make some variation of the commit ourselves.

225
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/release-testing.adoc
View File

@ -1,225 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[release-testing]]
=== Testing a Jetty Release
To test a Jetty release, complete the following steps for each release you want to test:
1. Download the staged release:
+
[source, screen, subs="{sub-order}"]
....
wget https://oss.sonatype.org/content/repositories/jetty-[reponumber]/org/eclipse/jetty/jetty-home/[jetty-version]/jetty-home-9.[jetty-minor-version].tar.gz
....
2. Extract to a directory of your choice.
3. Start jetty:
+
[source, screen, subs="{sub-order}"]
....
cd [installdir] ; java -jar start.jar
....
4. If there are no exceptions, proceed. Otherwise, investigate.
5. Open http://localhost:8080/ in a browser. In the examples section click "Test Jetty Webapp". You should see the `test.war` webapp.
6. Go through ALL the tests and verify that everything works as expected.
7. In the examples section click "JAAS Test" and verify that everything works as expected.
8. In the examples section click "JNDI Test" and verify that everything works as expected.
9. In the examples section click "Servlet 3.1 Test" and verify that everything works as expected.
10. Verify that hot deployment works.
+
[source, screen, subs="{sub-order}"]
....
cd [installdir] ;
touch [pathToJettyDistribution]/webapps.demo/test.xml
....
11. Verify that `test.war` gets redeployed in `STDOUT`.
12. Verify that the spdy example webapp and spdy-proxy do work
+
[source, screen, subs="{sub-order}"]
....
cd jetty_src/jetty-spdy/spdy-example-webapp
mvn jetty:run-forked
....
13. Browse to https://localhost:8443 and verify that all looks ok
14. Stop the server with CTRL+C and restart it in proxy mode:
+
[source, screen, subs="{sub-order}"]
....
mvn -Pproxy jetty:run-forked
....
15. Browse to http://localhost:8080 and https://localhost:8443 and verify that all looks ok
[[testing-cometd]]
==== Testing CometD
1. Clone CometD.
+
[source, screen, subs="{sub-order}"]
....
clone git://github.com/cometd/cometd.git
git clone git://github.com/cometd/cometd.git
....
2. Edit `pom.xml` and update `jetty-version.`
+
....
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<jetty-version>7.6.2.v20120308</jetty-version>
<jetty-plugin-version>${jetty-version}</jetty-plugin-version>
<slf4j.version>1.6.4</slf4j.version>
<spring-version>3.1.0.RELEASE</spring-version>
</properties>
<repositories>
<repository>
<id>Jetty Staging</id>
<url>https://oss.sonatype.org/content/repositories/jetty-988/</url>
</repository>
</repositories>
....
3. Build Cometd:
+
[source, screen, subs="{sub-order}"]
....
mvn clean install
....
4. Be patient.
5. Run the loadtest as it is described here: http://cometd.org/documentation/2.x/howtos/loadtesting.
Keep the default values, but make sure that you raise the clients setting to 1000.
Run the loadtest until ''JIT compilation time'' is close to a value of zero (about 10k calls).
6. Make sure that the performance results are reasonably fast.
On a MacBook Pro i7 2.6ghz dualcore produces the following:
+
[source, screen, subs="{sub-order}"]
....
========================================
Statistics Started at Fri Mar 09 13:44:35 CET 2012
Operative System: Mac OS X 10.7.3 amd64
JVM : Oracle Corporation Java HotSpot(TM) 64-Bit Server VM runtime 23.0-b16 1.7.0_04-ea-b14
Processors: 4
System Memory: 99.583336% used of 30.0 GiB
Used Heap Size: 36.490677 MiB
Max Heap Size: 1920.0 MiB
Young Generation Heap Size: 896.0 MiB
- - - - - - - - - - - - - - - - - - - -
Testing 1000 clients in 100 rooms, 10 rooms/client
Sending 1000 batches of 10x50 bytes messages every 10000 ?s
[GC [PSYoungGen: 786432K->8736K(917504K)] 823650K->45954K(1966080K), 0.0309940 secs] [Times: user=0.09 sys=0.00, real=0.03 secs]
[GC [PSYoungGen: 795168K->11424K(917504K)] 832386K->48642K(1966080K), 0.0513360 secs] [Times: user=0.13 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 797856K->14560K(917504K)] 835074K->51778K(1966080K), 0.0432940 secs] [Times: user=0.12 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 800992K->15680K(917504K)] 838210K->52898K(1966080K), 0.0491200 secs] [Times: user=0.14 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 802112K->17568K(917504K)] 839330K->54786K(1966080K), 0.0484950 secs] [Times: user=0.14 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 804000K->17600K(917504K)] 841218K->54818K(1966080K), 0.0456460 secs] [Times: user=0.14 sys=0.01, real=0.05 secs]
[GC [PSYoungGen: 804032K->19488K(917504K)] 841250K->56706K(1966080K), 0.0542000 secs] [Times: user=0.15 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 805920K->20224K(917504K)] 843138K->57442K(1966080K), 0.0486350 secs] [Times: user=0.16 sys=0.00, real=0.05 secs]
[GC [PSYoungGen: 806656K->20192K(917504K)] 843874K->57410K(1966080K), 0.0566690 secs] [Times: user=0.15 sys=0.00, real=0.06 secs]
[GC [PSYoungGen: 806624K->21152K(917504K)] 843842K->58370K(1966080K), 0.0536740 secs] [Times: user=0.16 sys=0.00, real=0.06 secs]
[GC [PSYoungGen: 807584K->21088K(917504K)] 844802K->58306K(1966080K), 0.0576060 secs] [Times: user=0.18 sys=0.00, real=0.06 secs]
[GC [PSYoungGen: 807520K->22080K(917504K)] 844738K->59298K(1966080K), 0.0663300 secs] [Times: user=0.19 sys=0.01, real=0.06 secs]
- - - - - - - - - - - - - - - - - - - -
Statistics Ended at Fri Mar 09 13:45:21 CET 2012
Elapsed time: 45826 ms
Time in JIT compilation: 52 ms
Time in Young Generation GC: 606 ms (12 collections)
Time in Old Generation GC: 0 ms (0 collections)
Garbage Generated in Young Generation: 9036.513 MiB
Garbage Generated in Survivor Generation: 21.65625 MiB
Garbage Generated in Old Generation: 0.0 MiB
Average CPU Load: 156.54865/400
----------------------------------------
Outgoing: Elapsed = 45820 ms | Rate = 218 messages/s - 21 requests/s - ~0.083 Mib/s
Waiting for messages to arrive 996960/999045
All messages arrived 999045/999045
Messages - Success/Expected = 999045/999045
Incoming - Elapsed = 45945 ms | Rate = 21743 messages/s - 9496 responses/s(43.68%) - ~8.295 Mib/s
Messages - Wall Latency Distribution Curve (X axis: Frequency, Y axis: Latency):
@ _ 24 ms (8765, 0.88%)
@ _ 45 ms (58952, 5.90%)
@ _ 67 ms (87065, 8.71%)
@ _ 88 ms (113786, 11.39%)
@ _ 109 ms (167426, 16.76%)
@ _ 131 ms (176163, 17.63%) ^50%
@ _ 152 ms (123182, 12.33%)
@ _ 174 ms (90918, 9.10%)
@ _ 195 ms (67209, 6.73%) ^85%
@ _ 216 ms (46989, 4.70%)
@ _ 238 ms (24975, 2.50%) ^95%
@ _ 259 ms (16509, 1.65%)
@ _ 281 ms (8454, 0.85%) ^99%
@ _ 302 ms (4324, 0.43%)
@ _ 323 ms (2955, 0.30%)
@ _ 345 ms (957, 0.10%) ^99.9%
@ _ 366 ms (204, 0.02%)
@ _ 388 ms (144, 0.01%)
@ _ 409 ms (25, 0.00%)
@ _ 430 ms (43, 0.00%)
Messages - Wall Latency 50th%/99th% = 117/275 ms
Messages - Wall Latency Min/Ave/Max = 2/123/430 ms
Messages - Network Latency Min/Ave/Max = 1/114/417 ms
Thread Pool - Concurrent Threads max = 239 | Queue Size max = 1002 | Queue Latency avg/max = 12/101 ms
....
7. Deploy `cometd.war` to the `webapps` directory of the jetty-home tested above.
+
[source, screen, subs="{sub-order}"]
....
cp cometd-demo/target/cometd-demo-[version].war [pathToJetty]/jetty-home-[jetty-version]/webapps/
....
8. Start jetty and make sure there are no exceptions.
+
[source, screen, subs="{sub-order}"]
....
cd [pathToJetty] && java -jar start.jar
....
9. Go through all pages of the demo and test them:
+
....
http://localhost:8080/cometd-demo-2.4.1-SNAPSHOT/
....
If all tests are green, you are done!

252
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/releasing-jetty.adoc
View File

@ -1,252 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[releasing-jetty]]
=== Releasing Jetty
There are a number of steps to releasing jetty.
It is not just limited to running a couple of maven commands and then moving onto bigger and better things.
There are a number of process related issues once the fun maven bits have been completed.
[[releasing-process]]
==== Building and Staging a Releasable Version
This release script is for jetty-9 (to release jetty-7 or jetty-8 see older documentation).
1. Pick your version identification strings.
+
These follow a strict format and will be used when prompted during step link:#prepare-release-step[listitem_title] below.
+
....
Release Version : 9.0.0.v20130322 (v[year][month][day])
Next Development Version : 9.0.1-SNAPSHOT
Tag Name : jetty-9.9.0.v20130322
....
2. We use the 'release-9' branch to avoid problems with other developers actively working on the master branch.
+
[source, screen, subs="{sub-order}"]
....
// Get all of the remotes
$ git pull origin
// Create a local tracking branch (if you haven't already)
$ git branch --track release-9 refs/remotes/origin/release-9
// Check out your local tracking branch.
$ git checkout release-9
// Merge from master into the branch (this becomes your point in time
// from master that you will be releasing from)
$ git merge --no-ff master
....
3. Update the VERSION.txt with changes from the git logs, this populates the resolves issues since the last release.
+
[source, screen, subs="{sub-order}"]
....
$ mvn -N -Pupdate-version
....
4. Edit the VERSION.txt file to set the 'Release Version' at the top alongside the Date of this release.
+
[source, screen, subs="{sub-order}"]
....
$ vi VERSION.txt
....
5. Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
[source, screen, subs="{sub-order}"]
....
$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9
....
6. Prepare the Release
+
____
[NOTE]
This step updates the <version> elements in the pom.xml files, does a test build with these new versions, and then commits the pom.xml changes to your local git repo.
The `eclipse-release` profile is required on the prepare in order to bring in the jetty aggregates as that profile defines a module which is ignored otherwise.
____
+
[source, screen, subs="{sub-order}"]
....
$ mvn release:prepare -DreleaseVersion=9.0.0.v20130322 \
-DdevelopmentVersion=9.0.1-SNAPSHOT \
-Dtag=jetty-9.0.0.v20130322 \
-Peclipse-release
....
7. Perform the Release
+
____
[NOTE]
This step performs the release and deploys it to a oss.sonatype.org staging repository.
____
+
[source, screen, subs="{sub-order}"]
....
$ mvn release:perform
....
8. Set up files for next development versions.
+
Edit `VERSION.txt` for 'Next Development Version' at the top.
Do not date this line.
+
Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
[source, screen, subs="{sub-order}"]
....
$ vi VERSION.txt
$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9
....
9. Close the staging repository on oss.sonatype.org
10. Announce stage to the mailing list for testing.
11. Once the staged repository has been approved by the rest of the committers.
+
* Release the staging repository to maven central on oss.sonatype.org
* Merge back the changes in release-9 to master
+
[source, screen, subs="{sub-order}"]
....
$ git checkout master
$ git merge --no-ff release-9
$ git push origin master
....
[[releasing-aggregates]]
==== Building and Deploying Aggregate Javadoc and Xref
Define the jetty.eclipse.website server entry in your .m2/settings.xml file.
You'll need to have access to the dev.eclipse.org machine to perform these actions.
If you don't know if you have access to this then you probably don't and will need to ask a project leader for help.
To build and deploy the aggregate javadoc and jxr bits:
[source, screen, subs="{sub-order}"]
....
$ cd target/checkout
$ mvn -Paggregate-site javadoc:aggregate jxr:jxr
$ mvn -N site:deploy
....
This will generate the aggregate docs and deploy them to the `/home/www/jetty/<project version>/jetty-project` directory on download.eclipse.org.
[[releasing-distributions]]
==== Deploying Distribution Files
Since we also provide alternative locations to download jetty distributions we need to copy these into place.
There are a couple of scripts that will take care of this although they need to be localized to your particular execution environment and you need to have authorization to put stuff where it needs to go.
These scripts are located at:
* http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/release-scripts.
To localize the scripts to your environment:
* ensure you have "curl" installed
* edit the scripts and replace all ssh login lines with your own login id
Once these are setup you can deploy a release to eclipse with the following incantation:
[source, screen, subs="{sub-order}"]
....
$ ./promote-to-eclipse.sh 9.0.0.v20130322
....
Each of these scripts will download all of the relevant files from maven central and then copy them into the correct location on eclipse infrastructure.
On the eclipse side of it they will also adjust the xref and javadoc documentation links if they remain broken as well as regenerate all of the html files on the eclipse download site.
[[releasing-stable-links]]
==== Updating Stable Links
Since we are not allowed to have symbolic links on the download site we have to log into the machine manually and remove the previous stable directory and update it with a new release.
Maintaining the conventions we use on the site will allow all 'stable' links to be stable and not needed to update to the latest major Jetty build version:
[source, screen, subs="{sub-order}"]
....
$ ssh <user>@build.eclipse.org
$ cd ~downloads/jetty/
$ rm -Rf stable-9
$ cp -r <version> stable-9
$ ./index.sh
....
This needs to be done for all Eclipse Jetty releases (regardless of version). In addition we have to work to reduce the footprint of jetty on the primary eclipse download resources so we want to move older releases to the eclipse archive site.
[source, screen, subs="{sub-order}"]
....
$ cd ~/downloads/jetty
$ mv <old release> /home/data/httpd/archive.eclipse.org/jetty/
$ ./index.sh
....
Periodically we need to do the same for the osgi P2 repositories to keep the size of our downloads directory at a reasonable size.
==== Building an OSGi P2 Repository
Most of the jetty jars are also osgi bundles, plus we release some specific bundles that link:#framework-jetty-osgi[integrate jetty closely with osgi].
To do this, we use a Hudson job on the eclipse infrastructure. You will need to have permission to access https://ci.eclipse.org/shared/view/Jetty-RT/
There are Hudson jobs that build osgi p2 repos for each of the major releases of jetty:7 (jetty-rt-bundles-7), 8 (jetty-rt-bundles-8) and 9 (jetty-rt-bundles-9).
You will need to start a manual build of the job that matches the version of jetty that you are releasing.
You will be prompted to supply some parameters to the build:
pack_and_sign::
By default, this is ticked. Leave it ticked.
jetty_release-version::
Enter the version number of the release, eg 9.2.6.v20141205
force_context_qualifier::
Leave this blank.
set_pom_version::
Enter the major.minor.point release number, eg 9.2.6
delete_tycho_meta::
This is ticked by default. Leave it ticked
BRANCH_NAME::
This is not the branch of the jetty release. Rather it refers to the branch structure of the project that drives the jetty p2 release.
It will already be set correctly for the selected job, so don't change it unless you have an extremely good reason.
Once you have supplied the necessary parameters, the build job will commence and the bundles and update site zips will generated and automatically placed in the `/home/data/httpd/downlaod.eclipse.org/jetty/updates/jetty-bundles-[MAJOR.VERSION].x`, where [MAJOR.VERSION] matches the major version number of the jetty release you are doing.
These files will then be visible from http://download.eclipse.org/jetty/updates/jetty-bundles-[MAJOR.VERSION].x, where [MAJOR.VERSION] corresponds to the major version of the jetty release you are doing.
[[releasing-documentation]]
==== Release Documentation
There are two git repositories you need to be aware of for releasing jetty-documentation.The jetty-documentation is located in our github repository and the jetty-website is located at eclipse.
jetty-documentation::
https://github.com/jetty-project/jetty-documentation
jetty-website::
http://github.com/jetty/jetty.website
Do the following steps to publish documentation for the release:
1. Checkout the jetty-documentation repository.
2. Edit the <version> of the jetty-documentation pom.xml and change it _locally_ to be the release number, eg 9.2.6.v20141205
3. Build the documentation with mvn clean install
4. Checkout the jetty-website
5. Inside the documentation/ directory, make a directory named the same as the release number, eg 9.2.6.v20141205/
6. Copy the built `documentation` from jetty-documentation/target/docbkx/html/jetty into the new directory
7. Edit the `index.html` file in the `documentation` directory and add the newly released documentation url.
Make sure you follow the other examples and include the `rel="nofollow"` attribute on the link so that search engines do not crawl newly created documentation, otherwise we are subject to duplicate content penalties in SEO.
8. Commit the changes to the jetty-website project
____
[NOTE]
There is a separate Jenkins build job that publishes documentation to https://jetty.org/docs/ triggered by a push of changed files to the jetty-documentation project.
If you commit your change to the <version> number from step 2, then these builds will use the same release version number.
It is preferable if you _don't_ commit that version number change, or better yet, ensure that it is set to the next -SNAPSHOT version number for your jetty major release number.
____

93
documentation/jetty-documentation/src/main/asciidoc/old_docs/contributing/source-build.adoc
View File

@ -1,93 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[contributing-source-build]]
=== Source Control and Building
If you want to contribute to the development of jetty, you will need to work with a handful of technologies.
[[contributing-source]]
==== Source Control
Jetty uses several development trunks for its artifacts.
They are mirrored on github through http://github.com/eclipse, or you can look through them via the Eclipse setup at the URLs below.
===== Primary Interest SCM URLs
These are the URLs to the GIT repositories for the Jetty code.
They are for people who are working on the Jetty project, as well as for people who are interested in examining or modifying the Jetty code for their own projects.
Jetty Project Repository::
https://github.com/jetty/jetty.project
===== Build and Project Infrastructure SCM URLs
These are the URLs for Jetty-related code and metadata.
These are not needed to use Jetty; these are primarily of use for people who are working with Jetty-the-project (as opposed to using Jetty-the-server in their own projects).
Administrative pom.xml file::
https://github.com/eclipse/jetty.parent
Build related artifacts that release separately, common assembly descriptors, remote resources, etc.::
https://github.com/eclipse/jetty.toolchain
Files associated with the development of Jetty -- code styles, formatting, iplogs, etc.::
http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git
==== Build
Jetty requires the use of Java 8 and the latest releases are always recommended to build.
Jetty uses http://maven.apache.org/[Apache Maven 3] for managing its build and primary project metadata.
Building Jetty should simply be a matter of changing into the relevant directory and executing the following commands:
[source, screen, subs="{sub-order}"]
....
$ git clone https://github.com/jetty/jetty.project.git
$ cd jetty.project
$ mvn install
....
All relevant dependencies will be downloaded into your local repository automatically.
____
[NOTE]
Jetty has a great many test cases that run through the course of its build.
Periodically we find some test cases to be more time dependent than they should be and this results in intermittent test failures.
You can help track these down by opening a bug report.
____
==== Import into Eclipse
Jetty is a Maven project. To develop Jetty in Eclipse, follow these directions:
===== Install m2e plugin
1. From the Eclipse menu at the top of the screen, select _Help > Eclipse Marketplace._
2. Search for __m2e__.
3. Install the _Maven Integration for Eclipse_
===== Clone the git repository
Using either the egit plugin or git on the commandline (as in the build section above), obtain the jetty source.
===== Import the Maven Projects
1. From the Eclipse menu, select _File > Import_
2. From the Maven folder, select _Existing Maven Projects._
3. Click __Next__.
4. In the Import Maven projects pane, click _Browse_ and select the top folder of the jetty source tree.
5. Click _Next/Finish_ to import all of jetty into Eclipse.
6. Wait for Eclipse and m2e to compilie and set up the project.

26
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/chapter.adoc
View File

@ -1,26 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[configuring-deployment]]
== Deploying to Jetty
This chapter discusses various ways to deploy applications with Jetty.
Topics range from deployment bindings to deploying third party products.
It also includes information about the Deployment Manager and WebApp Provider.
include::configuring-specific-webapp-deployment.adoc[]
include::deployment-processing-webapps.adoc[]
include::static-content-deployment.adoc[]
include::deployment-architecture.adoc[]
include::quickstart-webapp.adoc[]
//include::overlay-deployer.adoc[]

161
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/configuring-specific-webapp-deployment.adoc
View File

@ -1,161 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[configuring-specific-webapp-deployment]]
=== Configuring a Specific Web Application Deployment
Using the Automatic Web Application Deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application).
You can use a xref:deployable-descriptor-file[] to accomplish such tuning.
[[deployable-descriptor-file]]
==== Jetty Deployable Descriptor XML File
Jetty supports deploying Web Applications via XML files which will build an instance of a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] that Jetty can then deploy.
[[using-basic-descriptor-files]]
==== Using Basic Descriptor Files
In a default Jetty installation, Jetty scans its `$JETTY_HOME/webapps` directory for context deployment descriptor files.
To deploy a web application using such a file, simply place the file in that directory.
The deployment descriptor file itself is an xml file that configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class.
For a basic installation only two properties need configured:
war::
The filesystem path to the web application file (or directory)
contextPath::
The context path to use for the web application
For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.war` to the context path `/wiki`:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war">/opt/myapp/myapp.war</Set>
</Configure>
----
Both `SystemProperty` and `Property` elements can be used in the descriptor file.
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}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
</Configure>
----
If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.
____
[NOTE]
To ensure your `web.xml` files are validated, you will need to set the `validateXml` attribute to true as described link:#jetty-xml-dtd[here.]
____
[[configuring-advanced-descriptor-files]]
==== Configuring Advanced Descriptor Files
Official documentation for the for the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] class lists all the properties that can be set.
Here are some examples that configure advanced options in the descriptor file.
This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
<Set name="extractWAR">false</Set>
</Configure>
----
The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The `setAttribute` method can also be used to set a Servlet context attribute.
However, since the `web.xml` for the web application is processed after the deployment descriptor, the `web.xml` values overwrite identically named attributes from the deployment descriptor.
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
<Get name="ServletContext">
<Call name="setInitParameter">
<Arg>myapp.config</Arg>
<Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg>
</Call>
</Get>
</Configure>
----
The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
<Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set>
</Configure>
----
The next example configures not only the web application context, but also a database connection pool (see xref:jndi-datasource-examples[]) that the application can then use.
If the `web.xml` does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set>
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
<Arg>jdbc/DSTest</Arg>
<Arg>
<New class="org.apache.commons.dbcp.BasicDataSource">
<Set name="driverClassName">org.some.Driver</Set>
<Set name="url">jdbc.url</Set>
<Set name="username">jdbc.user</Set>
<Set name="password">jdbc.pass</Set>
</New>
</Arg>
</New>
</Configure>
----
There are many other settings that can be changed in a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`].
The link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[javadoc] for `WebAppContext` is a good source of information.
Also see the documentation on link:#troubleshooting-zip-exceptions[avoiding zip file exceptions] for a description of `WebAppContext` settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.

166
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/deployment-architecture.adoc
View File

@ -1,166 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[deployment-architecture]]
=== Deployment Architecture
Jetty is built around an extensible Deployment Manager architecture complete with formal LifeCycle for Web Applications going through it.
For Jetty to serve content (static or dynamic), a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] needs to be configured and added to Jetty in the appropriate location.
A pluggable `DeploymentManager` exists to make this process easier.
The Jetty distribution contains example `DeploymentManager` configurations to deploy WAR files found in a directory to Jetty, and to deploy Jetty context xml files into Jetty as well.
The `DeploymentManager` is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.
image:Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
[[udm-application-providers]]
==== Application Providers
Before Jetty deploys an application, an link:{JDURL}/org/eclipse/jetty/deploy/AppProvider.html[`AppProvider`] identifies the App and then provides it to the `DeploymentManager`.
The main `AppProvider` with the Jetty distribution is the link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[`WebAppProvider`.]
[[udm-application-lifecycle-graph]]
==== Application LifeCycle Graph
The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[Application LifeCycle Graph].
image:Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).
New applications enter this graph at the Undeployed node, and the link:{JDURL}/org/eclipse/jetty/deploy/DeploymentManager.html#requestAppGoal(org.eclipse.jetty.deploy.App[`java.lang.String DeploymentManager.requestAppGoal(App,String)`] method pushes them through the graph.
[[udm-lifecycle-bindings]]
==== LifeCycle Bindings
A set of default link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[`AppLifeCycle.Bindings`] defines standard behavior, and handles deploying, starting, stopping, and undeploying applications.
If desired, custom `AppLifeCycle.Bindings` can be written and assigned anywhere on the Application LifeCycle graph.
Examples of new `AppLifeCycle.Binding` implementations that can be developed include:
* Validating the incoming application.
* Preventing the deployment of known forbidden applications.
* Submitting the installation to an application auditing service in a corporate environment.
* Distributing the application to other nodes in the cluster or cloud.
* Emailing owner/admin of change of state of the application.
There are four default bindings:
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardDeployer.html[`StandardDeployer`] — Deploys the ContextHandler into Jetty in the appropriate place.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStarter.html[`StandardStarter`] — Sets the ContextHandler to started and start accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStopper.html[`StandardStopper`] — Stops the ContextHandler and stops accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html[`StandardUndeployer`] — Removes the ContextHandler from Jetty.
image:Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bindings/DebugBinding.html[DebugBinding], is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.
===== Using GlobalWebappConfigBinding
In addition to the LifeCycle bindings discussed above, there is also the `GlobalWebappConfigBinding` which, when added to the `DeploymentManager` will apply an additional configuration XML file to each webapp that it deploys.
This can useful when setting server or system classes, or when defining link:#override-web-xml[override descriptors.]
This configuration XML file will be _in addition to_ any context XML file that exists for the webapp; it will be applied _after_ any context XML files but _before_ the webapp is started.
The format for the XML file is the same as any context XML file and can be used to same parameters for a webapp.
To use this binding, you can either modify the existing `jetty-deploy.xml` which comes with the Jetty distribution (be sure to link:#startup-base-and-home[copy it to your $JETTY_BASE/etc directory first]), or by link:#custom-modules[creating a new module] file which calls to an additional XML file.
[source,xml,subs="{sub-order}"]
----
<Call name="addLifeCycleBinding">
<Arg>
<New class="org.eclipse.jetty.ee10.deployer.GlobalWebappConfigBinding" >
<Set name="jettyXml"><Property name="jetty.home" default="." />/etc/global-webapp-config.xml</Set>
</New>
</Arg>
</Call>
----
[[default-web-app-provider]]
==== Understanding the Default WebAppProvider
The link:{JDURL}/org/eclipse/jetty/deploy/providers/WebAppProvider.html[WebAppProvider] is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a xref:deployable-descriptor-file[].
It supports hot (re)deployment.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables.
In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
[source,xml,subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBean">
<Arg>
<New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager">
<Set name="contexts">
<Ref refid="Contexts" />
</Set>
<Call id="webappprovider" name="addAppProvider">
<Arg>
<New class="org.eclipse.jetty.ee10.deployer.WebAppProvider">
<Set name="monitoredDirName"><Property name="jetty.home" default="." />/webapps</Set>
<Set name="defaultsDescriptor"><Property name="jetty.home" default="." />/etc/webdefault.xml</Set>
<Set name="scanInterval">1</Set>
<Set name="extractWars">true</Set>
</New>
</Arg>
</Call>
</New>
</Arg>
</Call>
</Configure>
----
The above configuration will create a `DeploymentManager` tracked as a Server LifeCycle Bean, with the following configuration.
contexts::
A passed in reference to the HandlerContainer into which the discovered webapps are deployed.
This is normally a reference that points to the `id="Contexts"` found in the `${jetty.home}/etc/jetty.xml` file, which itself is an instance of `ContextHandlerCollection`.
monitoredDirName::
The file path or URL to the directory to scan for web applications.
Scanning follows these rules:
1. A base directory must exist.
2. Hidden Files (starting with `"."`) are ignored.
3. Directories with names ending in `".d"` are ignored.
4. Common CVS directories `"CVS"` and `"CVSROOT"` are ignored.
5. Any `*.war` files are considered link:#automatic-webapp-deployment[automatic deployables].
6. Any `*.xml` files are considered link:#deployable-descriptor-file[context descriptor deployables].
7. In the special case where both a WAR file and XML file exists for same base name, the XML file is assumed to configure and reference the WAR file (see xref:configuring-specific-webapp-deployment[]).
Since jetty-9.2.7, if either the WAR file or its corresponding XML file changes, the webapp will be redeployed.
8. A directory is considered to be deployable.
9. In the special case where both a Directory and WAR file of the same name exists, the WAR file is assumed to be an automatic deployable.
10. In the special case where both a Directory and XML file of the same name exists, the XML file is assumed to configure and reference the Directory.
11. All other directories are subject to automatic deployment.
12. If automatic deployment is used, and the special filename `root.war/ROOT.war` or directory name `root/ROOT` will result in a deployment to the `"/"` context path.
defaultsDescriptor::
Specifies the default Servlet web descriptor to use for all Web Applications.
The intent of this descriptor is to include common configuration for the Web Application before the Web Application's own `/WEB-INF/web.xml` is applied.
The `${jetty.home}/etc/webdefault.xml` that comes with the Jetty distribution controls the configuration of the JSP and Default servlets, along with MIME-types and other basic metadata.
scanInterval::
The period in seconds between sweeps of the `monitoredDirName` for changes: new contexts to deploy, changed contexts to redeploy, or removed contexts to undeploy.
extractWars::
If parameter is true, any packed WAR or zip files are first extracted to a temporary directory before being deployed.
This is advisable if there are uncompiled JSPs in the web apps.
parentLoaderPriority::
Parameter is a boolean that selects whether the standard Java link:#jetty-classloading[parent first delegation] is used or the link:#jetty-classloading[servlet specification webapp classloading priority].
The latter is the default.

297
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/deployment-processing-webapps.adoc
View File

@ -1,297 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[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 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].
[[webapp-configurations]]
==== Configuration Classes
As a webapp is being deployed, a series of link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.ee9.webapp.Configuration] classes are applied to it, each one performing a specific function.
The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations.
These are the default list, in order, of Configurations that are applied to each link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[org.eclipse.jetty.ee9.webapp.WebAppContex]t:
.Default Configuration classes
[cols=",",]
|=======================================================================
|link:{JDURL}/org/eclipse/jetty/webapp/WebInfConfiguration.html[org.eclipse.jetty.ee9.webapp.WebInfConfiguration]
|Extracts war, orders jars and defines classpath
|link:{JDURL}/org/eclipse/jetty/webapp/WebXmlConfiguration.html[org.eclipse.jetty.ee9.webapp.WebXmlConfiguration]
|Processes a WEB-INF/web.xml file
|link:{JDURL}/org/eclipse/jetty/webapp/MetaInfConfiguration.html[org.eclipse.jetty.ee9.webapp.MetaInfConfiguration]
|Looks in container and webapp jars for META-INF/resources and
META-INF/web-fragment.xml
|link:{JDURL}/org/eclipse/jetty/webapp/FragmentConfiguration.html[org.eclipse.jetty.ee9.webapp.FragmentConfiguration]
|Processes all discovered META-INF/web-fragment.xml files
|link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.ee9.webapp.JettyWebXmlConfiguration]
|Processes a WEB-INF/jetty-web.xml file
|=======================================================================
===== Anatomy of a Configuration Class
A Configuration class is called 5 times in different phases of the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext's`] lifecycle:
preConfigure::
As the `WebAppContext` is starting up this phase is executed.
The `Configuration` should discover any of the resources it will need during the subsequent phases.
configure::
This phase is where the work of the class is done, usually using the resources discovered during the `preConfigure` phase.
postConfigure::
This phase allows the `Configuration` to clear down any resources that may have been created during the previous 2 phases that are not needed for the lifetime of the `WebAppContext`.
deconfigure::
This phase occurs whenever a `WebAppContext` is being stopped and allows the Configuration to undo any resources/metadata that it created.
A `WebAppContext` should be able to be cleanly start/stopped multiple times without resources being held.
destroy::
This phase is called when a `WebAppContext` is actually removed from service.
For example, the war file associated with it is deleted from the $JETTY_HOME/webapps directory.
Each phase is called on each `Configuration` class in the order in which the `Configuration` class is listed.
Using the default `Configuration` classes as an example, `preConfigure()` will be called on `WebInfConfiguration`, `WebXmlConfiguration`, `MetaInfConfiguration`, `FragmentConfiguration` and then `JettyWebXmlConfiguration`.
The cycle begins again for the `configure()` phase and again for the `postConfigure()` phases.
The cycle is repeated _in reverse order_ for the `deconfigure()` and eventually the `destroy()` phases.
===== Extending Container Support by Creating Extra Configurations
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.
Jetty makes use of the flexibility of Configurations to make JNDI and annotation support pluggable.
Firstly, lets look at how Configurations help enable JNDI.
[[jndi-configuration-classes]]
====== Example: JNDI Configurations
JNDI lookups within web applications require the container to hookup resources defined in the container's environment to that of the web application.
To achieve that, we use 2 extra Configurations:
.JNDI Configuration classes
[cols=",",]
|=======================================================================
|link:{JDURL}/org/eclipse/jetty/plus/webapp/EnvConfiguration.html[org.eclipse.jetty.plus.webapp.EnvConfiguration]
|Creates `java:comp/env` for the webapp, applies a `WEB-INF/jetty-env.xml` file
|link:{JDURL}/org/eclipse/jetty/plus/webapp/PlusConfiguration.html[org.eclipse.jetty.plus.webapp.PlusConfiguration]
|Processes JNDI related aspects of `WEB-INF/web.xml` and hooks up naming entries
|=======================================================================
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.ee9.webapp.JettyWebXmlConfiguration] class in the list of configurations.
To fully support JNDI additional configuration is required, full details of which can be found link:#jndi[here].
====== Example: Annotation Configurations
We need just one extra Configuration class to help provide servlet annotation scanning:
.Annotation Configuration classes
[cols=",",]
|=======================================================================
|link:{JDURL}/org/eclipse/jetty/annotations.AnnotationConfiguration.html[org.eclipse.jetty.annotations.AnnotationConfiguration]
|Scan container and web app jars looking for @WebServlet, @WebFilter,
@WebListener etc
|=======================================================================
The above configuration class must be _inserted immediately before_ the link:{JDURL}/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html[org.eclipse.jetty.ee9.webapp.JettyWebXmlConfiguration] class in the list of configurations.
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
You have a number of options for how to make Jetty use a different list of Configurations.
====== Setting the list directly on the WebAppContext
If you have only one webapp that you wish to affect, this may be the easiest option.
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let's see an example of how we would add in the Configurations for both JNDI _and_ annotations:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="war"><SystemProperty name="jetty.base" default="."/>/webapps/my-cool-webapp</Set>
<Set name="configurationClasses">
<Array type="java.lang.String">
<Item>org.eclipse.jetty.ee9.webapp.WebInfConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.WebXmlConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.MetaInfConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.FragmentConfiguration</Item>
<Item>org.eclipse.jetty.plus.webapp.EnvConfiguration</Item>
<Item>org.eclipse.jetty.plus.webapp.PlusConfiguration</Item>
<Item>org.eclipse.jetty.annotations.AnnotationConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.JettyWebXmlConfiguration</Item>
</Array>
</Set>
</Configure>
----
Of course, you can also use this method to reduce the Configurations applied to a specific `WebAppContext`.
====== Setting the list for all webapps via the Deployer
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
They will then be applied to each `WebAppContext` deployed by the deployer:
[source,xml,subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBean">
<Arg>
<New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager">
<Set name="contexts">
<Ref refid="Contexts" />
</Set>
<Call id="webappprovider" name="addAppProvider">
<Arg>
<New class="org.eclipse.jetty.ee10.deployer.WebAppProvider">
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/webapps</Set>
<Set name="configurationClasses">
<Array type="java.lang.String">
<Item>org.eclipse.jetty.ee9.webapp.WebInfConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.WebXmlConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.MetaInfConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.FragmentConfiguration</Item>
<Item>org.eclipse.jetty.plus.webapp.EnvConfiguration</Item>
<Item>org.eclipse.jetty.plus.webapp.PlusConfiguration</Item>
<Item>org.eclipse.jetty.annotations.AnnotationConfiguration</Item>
<Item>org.eclipse.jetty.ee9.webapp.JettyWebXmlConfiguration</Item>
</Array>
</Set>
</New>
</Arg>
</Call>
</New>
</Arg>
</Call>
</Configure>
----
====== Adding or inserting to an existing list
Instead of having to enumerate the list in its entirety, you can simply nominate classes that you want to add, and indicate whereabouts in the list you want them inserted.
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the `$JETTY_HOME/etc/jetty-plus.xml` file from the Jetty distribution:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<!-- =========================================================== -->
<!-- Add plus Configuring classes to all webapps for this Server -->
<!-- =========================================================== -->
<Call class="org.eclipse.jetty.ee9.webapp.Configuration$ClassList" name="setServerDefault">
<Arg><Ref refid="Server" /></Arg>
<Call name="addAfter">
<Arg name="afterClass">org.eclipse.jetty.ee9.webapp.FragmentConfiguration</Arg>
<Arg>
<Array type="String">
<Item>org.eclipse.jetty.plus.webapp.EnvConfiguration</Item>
<Item>org.eclipse.jetty.plus.webapp.PlusConfiguration</Item>
</Array>
</Arg>
</Call>
</Call>
</Configure>
----
The link:{JDURL}/org/eclipse/jetty/webapp/Configuration.html[org.eclipse.jetty.ee9.webapp.Configuration.ClassList] class provides these methods for insertion:
addAfter::
Inserts the supplied list of `Configuration` class names after the given Configuration class name.
addBefore::
Inserts the supplied list of `Configuration` class names before the given Configuration class name.
[[webapp-context-attributes]]
==== Other Configuration
[[container-include-jar-pattern]]
===== org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern
This is a link:#context_attributes[context attribute] that can be set on link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[an org.eclipse.jetty.ee9.webapp.WebAppContext] to control which parts of the _container's_ classpath should be processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` inside `META-INF`.
Normally, nothing from the container classpath will be included for processing.
However, sometimes you will need to include some.
For example, you may have some libraries that are shared amongst your webapps and thus you have put them into a `$JETTY_HOME/lib` directory.
The libraries contain annotations and therefore must be scanned.
The value of this attribute is a regexp that defines which _jars_ and _class directories_ from the container's classpath should be examined.
Here's an example from a context xml file (although as always, you could have accomplished the same in code), which would match any jar whose name starts with "foo-" or "bar-", or a directory named "classes":
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Call name="setAttribute">
<Arg>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</Arg>
<Arg>.*/foo-[^/]*\.jar$|.*/bar-[^/]*\.jar$|.*/classes/.*</Arg>
</Call>
</Configure>
----
Note that the order of the patterns defines the ordering of the scanning of the jars or class directories.
[[web-inf-include-jar-pattern]]
===== org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern
Similarly to the previous link:#context_attributes[context attribute], this attribute controls which jars are processed for things like annotations, `META-INF/resources`, `META-INF/web-fragment.xml` and `tlds` in `META-INF`.
However, this attribute controls which jars from the _webapp's_ classpath (usually `WEB-INF/lib`) are processed.
This can be particularly useful when you have dozens of jars in `WEB-INF/lib`, but you know that only a few need to be scanned.
Here's an example in a xml file of a pattern that matches any jar that starts with `spring-`:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Call name="setAttribute">
<Arg>org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern</Arg>
<Arg>.*/spring-[^/]*\.jar$</Arg>
</Call>
</Configure>
----
Note that the order of the patterns defines the ordering of the scanning of jar files.

177
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/quickstart-webapp.adoc
View File

@ -1,177 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-webapp]]
=== Quickstart Webapps
The auto discovery features of the Servlet specification can make deployments slow and uncertain.
Auto discovery of Web Application configuration can be useful during the development of a webapp as it allows new features and frameworks to be enabled simply by dropping in a jar file.
However, for deployment, the need to scan the contents of many jars can have a significant impact of the start time of a webapp.
With the release of Jetty 9.2, a quickstart module was included which allows a webapp to be pre-scanned and preconfigured.
This means that all the scanning is done prior to deployment and all configuration is encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed before deploying.
Not only does the `quickstart-web.xml` contain all the discovered Servlets, Filters and Constraints, but it also encodes as context parameters all discovered:
* ServletContainerInitializers
* HandlesTypes classes
* Taglib Descriptors
With the quickstart mechanism, Jetty is able to entirely bypass all scanning and discovery modes and start a webapp in a predictable and fast way.
Tests have shown that webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.
==== Setting up Quickstart
===== Prerequisites
====== Jetty Distribution
In a standard Jetty distribution the quickstart module can be configured with the following command:
[source, screen, subs="{sub-order}"]
----
$ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
----
====== Embedded
In a Maven project you add a dependency on the artifact `jetty-quickstart`.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-quickstart</artifactId>
<version>{VERSION}</version>
</dependency>
----
===== Configuration
Webapps need to be instances of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.ee9.webapp.WebAppContext`.
`org.eclipse.jetty.quickstart.QuickStartWebApp` instances offer the same setters as the familiar `org.eclipse.jetty.ee9.webapp.WebAppContext`, with the addition of:
autoPreconfigure::
(true/false).
If true, the first time the webapp is run, the WEB-INF/quickstart-web.xml is generated BEFORE the webapp is deployed.
Subsequent runs use the previously generated quickstart file.
originAttribute::
The name of an attribute to insert into the generated elements in quickstart-web.xml that gives the origin of the element.
By default it is `origin`.
generateOrigin::
(true/false).
By default it is `false`.
If true, the origin attribute will be inserted into each element in quickstart-web.xml.
Note that origin attributes will also be generated if debug log level is enabled.
____
[NOTE]
If you are using Spring-Boot you must set `generateOrigin` to true.
____
The origin is either a descriptor eg web.xml,web-fragment.xml,override-web.xml file, or an annotation eg @WebServlet.
For xml validation each attribute must be unique, and therefore an integer counter is appended to each value.
Some examples of elements with origin attribute information are:
[source, xml, subs="{sub-order}"]
----
<listener origin="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21">
<listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22">
<servlet-class origin="FragmentDescriptor(jar:file:///path/to/base/webapps/test-spec/WEB-INF/lib/test-web-fragment.jar!/META-INF/web-fragment.xml):23">
<servlet-class origin="@WebServlet(com.acme.test.TestServlet):24">
----
====== In XML
If a web application already has a context xml file, eg `webapps/myapp.xml` file, simply change the class in the `Configure` element.
Otherwise, create a context xml file with the following information (in addition to the usual setting of contextPath, war etc):
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.quickstart.QuickStartWebApp">
<Set name="autoPreconfigure">true</Set>
</Configure>
----
====== In Code
Create an instance of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.ee9.webapp.WebAppContext`. You then use the QuickStartWebApp instance in exactly the same way that you would a WebAppContext.
Here's a snippet:
[source, java]
----
QuickStartWebApp webapp = new QuickStartWebApp();
webapp.setAutoPreconfigure(true);
----
====== Pre-generating the quickstart-web.xml file
Rather than use the `autoPreconfigure` feature of the QuickStartWebApp - which lazily generates the `quickstart-web.xml` file - you can eagerly pre-generate it for an existing war by invoking as a main class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[`org.eclipse.jetty.quickstart.PreconfigureQuickStartWar`].
Note that you will need to provide all necessary jetty jars on the command line classpath.
This will unpack the war if necessary, and create the `quickstart-web.xml` before the first deployment:
[source, screen, subs="{sub-order}"]
----
$ java -cp [jetty classpath] org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
----
Run the class with no arguments to see other runtime options.
Alternatively, you could use the link:#get-up-and-running[Jetty Maven Plugin] goal link:#jetty-effective-web-xml[`jetty:effective-web-xml`]: this will generate quickstart information, but print it to stderr.
The goal provides a configuration option to save the output to a file, which you can then copy into your webapp's WEB-INF dir.
Note that as the Jetty Maven Plugin is a general tool for running webapps, it may have more jars on its classpath than are needed by your application, and thus may generate extra quickstart information: we recommend that you use this goal only as a quick guide to the type of information that quickstart generates.
// ==== Preconfiguring the web application
//
// If the `QuickStateWebApp` method `setAutoPreconfigure(true)` is called (see example in myapp.xml above), then the first time the webapp is deployed a `WEB-INF/quickstart-web.xml` file will be generated that contains the effective `web.xml` for all the discovered configuration.
// On subsequent deployments, all the discovery steps are skipped and the `quickstart-web.xml` is used directly to configure the web application.
//
// It is also possible to preconfigure a war file manually by running the class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[org.eclipse.jetty.quickstart.PreconfigureQuickStartWar] with the jetty-all-uber (aggregate) jar:
//
//
// This will create the `quickstart-web.xml` file before the first deployment.
==== Avoiding TLD Scans with precompiled JSPs
Of course precompiling JSPs is an excellent way to improve the start time of a web application.
As of Jetty 9.2 the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
This can be done by adding a `context-param` to the `web.xml` file (this is done automatically by the Jetty Maven JSPC plugin):
[source, xml, subs="{sub-order}"]
----
<context-param>
<param-name>org.eclipse.jetty.jsp.precompiled</param-name>
<param-value>true</param-value>
</context-param>
----
==== Bypassing start.jar
The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for constructing a `classpath` and executing a configuration encoded in Jetty XML format.
However, this mechanism does take some time to build the `classpath`.
The start.jar mechanism can be bypassed by using the `–dry-run` option to generate and reuse a complete command line to start Jetty at a later time:
[source, screen, subs="{sub-order}"]
----
$ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $RUN
----
Note that `--dry-run` may create a properties file in the temp directory and include it on the generated command line.
If so, then a copy of the temporary properties file should be taken and the command line updated with it's new persistent location.

36
documentation/jetty-documentation/src/main/asciidoc/old_docs/deploying/static-content-deployment.adoc
View File

@ -1,36 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[static-content-deployment]]
=== Configuring Static Content Deployment
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.base}/webapps` directory and paste the following file contents in it.
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.server.handler.ContextHandler">
<Set name="contextPath">/scratch</Set>
<Set name="handler">
<New class="org.eclipse.jetty.server.handler.ResourceHandler">
   <Set name="resourceBase">/home/scratch</Set>
<Set name="directoriesListed">true</Set>
</New>
</Set>
</Configure>
----
This is a very basic setup for serving static files.
For advanced static file serving, use the link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[DefaultServlet].

19
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/chapter.adoc
View File

@ -1,19 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[advanced-embedding]]
== Embedding
include::jetty-helloworld.adoc[]
include::embedding-jetty.adoc[]
include::embedded-examples.adoc[]

81
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/embedded-examples.adoc
View File

@ -1,81 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-examples]]
=== Embedded Examples
Jetty has a rich history of being embedded into a wide variety of applications.
In this section we will walk you through a number of our simple examples under our embedded-jetty-examples project in our git repository.
____
[IMPORTANT]
These files are pulled directly from our git repository when this document is generated.
If the line numbers do not line up feel free to fix this documentation in github and give us a pull request, or at least open an issue to notify us of the discrepancy.
____
include::examples/embedded-file-server.adoc[]
include::examples/embedded-split-file-server.adoc[]
include::examples/embedded-many-connectors.adoc[]
include::examples/embedded-secured-hello-handler.adoc[]
include::examples/embedded-minimal-servlet.adoc[]
include::examples/embedded-one-webapp.adoc[]
[[embedded-webapp-jsp]]
==== Web Application with JSP
This example is very similar to the one in the previous section, although it enables the embedded webapp to use JSPs.
As of jetty-9.2, we use the JSP engine from Apache, which relies on a Servlet Specification 3.1 style `ServletContainerInitializer` to initialize itself.
To get this to work with Jetty, you need to enable annotations processing, as shown in this example code:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebAppWithJsp.java[]
----
===== Run it!
After you have started things up you should be able to navigate to http://localhost:8080/jsp/ and click on any of the links to jsps.
===== Maven Coordinates
To use this example in your project, you will need the following Maven dependencies declared, in addition to those from the previous section:
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-annotations</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>apache-jsp</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>apache-jstl</artifactId>
<version>${project.version}</version>
</dependency>
----
[[adding-embedded-examples]]
==== Adding Examples
If you would like to add an example to this list, fork the documentation project from github (see the blue bar at the bottom of this page) and add the new page.
Feel free to add the example contents directly as a `[source.java]` and we will take it from there.
If you feel and example is missing, feel free to open a bug to ask for it.
No guarantees, but the more helpful and demonstrative it is the better.

242
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/embedding-jetty.adoc
View File

@ -1,242 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedding-jetty]]
=== Embedding Jetty
Jetty has a slogan, "__Don't deploy your application in Jetty, deploy Jetty in your application!__"
What this means is that as an alternative to bundling your application as a standard WAR to be deployed in Jetty, Jetty is designed to be a software component that can be instantiated and used in a Java program just like any POJO.
Put another way, running Jetty in embedded mode means putting an HTTP module into your application, rather than putting your application into an HTTP server.
This tutorial takes you step-by-step from the simplest Jetty server instantiation to running multiple web applications with standards-based deployment descriptors.
The source for most of these examples is part of the standard Jetty project.
==== Overview
To embed a Jetty server the following steps are typical and are illustrated by the examples in this tutorial:
1. Create a link:{JDURL}/org/eclipse/jetty/server/Server.html[Server] instance.
2. Add/Configure link:{JDURL}/org/eclipse/jetty/server/Connector.html[Connectors].
3. Add/Configure link:{JDURL}/org/eclipse/jetty/server/Handler.html[Handlers] and/or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[Contexts] and/or http://docs.oracle.com/javaee/6/api/javax/servlet/Servlet.html[Servlets].
4. Start the Server.
5. Wait on the server or do something else with your thread.
==== Creating the Server
The following code from SimplestServer.java instantiates and runs the simplest possible Jetty server:
[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SimplestServer.java[]
----
This runs an HTTP server on port 8080. It is not a very useful server as it has no handlers, and thus returns a 404 error for every request.
==== Using Handlers
To produce a response to a request, Jetty requires that you set a link:{JDURL}/org/eclipse/jetty/server/Handler.html[Handler] on the server.
A handler may:
* Examine/modify the HTTP request.
* Generate the complete HTTP response.
* Call another Handler (see link:{JDURL}/org/eclipse/jetty/server/handler/HandlerWrapper.html[`HandlerWrapper`]).
* Select one or many Handlers to call (see link:{JDURL}/org/eclipse/jetty/server/handler/HandlerCollection.html[`HandlerCollection`]).
===== HelloWorld Handler
The following code based on HelloHandler.java shows a simple hello world handler:
[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/HelloHandler.java[]
----
The parameters passed to the handle method are:
* `target` – the target of the request, which is either a URI or a name from a named dispatcher.
* `baseRequest` – the Jetty mutable request object, which is always unwrapped.
* `request` – the immutable request object, which may have been wrapped by a filter or servlet.
* `response` – the response, which may have been wrapped by a filter or servlet.
The handler sets the response status, content-type, and marks the request as handled before it generates the body of the response using a writer.
===== Running HelloWorldHandler
To allow a Handler to handle HTTP requests, you must add it to a Server instance.
The following code from OneHandler.java shows how a Jetty server can use the HelloWorld handler:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneHandler.java[]
----
One or more handlers do all request handling in Jetty.
Some handlers select other specific handlers (for example, a `ContextHandlerCollection` uses the context path to select a `ContextHandler`); others use application logic to generate a response (for example, the `ServletHandler` passes the request to an application Servlet), while others do tasks unrelated to generating the response (for example, `RequestLogHandler` or `StatisticsHandler`).
Later sections describe how you can combine handlers like aspects.
You can see some of the handlers available in Jetty in the link:{JDURL}/org/eclipse/jetty/server/handler/package-summary.html[org.eclipse.jetty.server.handler] package.
===== Handler Collections and Wrappers
Complex request handling is typically built from multiple Handlers that you can combine in various ways.
Jetty has several implementations of the link:{JDURL}/org/eclipse/jetty/server/HandlerContainer.html[`HandlerContainer`] interface:
link:{JDURL}/org/eclipse/jetty/server/handler/HandlerCollection.html[`HandlerCollection`]::
Holds a collection of other handlers and calls each handler in order.
This is useful for combining statistics and logging handlers with the handler that generates the response.
link:{JDURL}/org/eclipse/jetty/server/handler/HandlerList.html[`HandlerList`]::
A Handler Collection that calls each handler in turn until either an exception is thrown, the response is committed or the `request.isHandled()` returns true.
You can use it to combine handlers that conditionally handle a request, such as calling multiple contexts until one matches a virtual host.
link:{JDURL}/org/eclipse/jetty/server/handler/HandlerWrapper.html[`HandlerWrapper`]::
A Handler base class that you can use to daisy chain handlers together in the style of aspect-oriented programming.
For example, a standard web application is implemented by a chain of a context, session, security and servlet handlers.
link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandlerCollection.html[`ContextHandlerCollection`]::
A specialized `HandlerCollection` that uses the longest prefix of the request URI (the `contextPath`) to select a contained `ContextHandler` to handle the request.
===== Scoped Handlers
Much of the standard Servlet container in Jetty is implemented with `HandlerWrappers` that daisy chain handlers together: `ContextHandler` to `SessionHandler` to `SecurityHandler` to `ServletHandler`.
However, because of the nature of the servlet specification, this chaining cannot be a pure nesting of handlers as the outer handlers sometimes need information that the inner handlers process.
For example, when a `ContextHandler` calls some application listeners to inform them of a request entering the context, it must already know which servlet the `ServletHandler` will dispatch the request to so that the `servletPath` method returns the correct value.
The `HandlerWrapper` is specialized to the link:{JDURL}/org/eclipse/jetty/server/handler/ScopedHandler.html[`ScopedHandler`] abstract class, which supports a daisy chain of scopes.
For example if a `ServletHandler` is nested within a `ContextHandler`, the order and nesting of execution of methods is:
....
Server.handle(...)
ContextHandler.doScope(...)
ServletHandler.doScope(...)
ContextHandler.doHandle(...)
ServletHandler.doHandle(...)
SomeServlet.service(...)
....
Thus when the `ContextHandler` handles the request, it does so within the scope the `ServletHandler` has established.
===== Resource Handler
The link:{JDURL}/org/eclipse/jetty/embedded/FileServer.html[FileServer example] shows how you can use a `ResourceHandler` to serve static content from the current working directory:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/FileServer.java[]
----
Notice that a `HandlerList` is used with the `ResourceHandler` and a `DefaultHandler`, so that the `DefaultHandler` generates a good 404 response for any requests that do not match a static resource.
==== Embedding Connectors
In the previous examples, the Server instance is passed a port number and it internally creates a default instance of a Connector that listens for requests on that port.
However, often when embedding Jetty it is desirable to explicitly instantiate and configure one or more Connectors for a Server instance.
===== One Connector
The following example, link:{JDURL}/org/eclipse/jetty/embedded/OneConnector.html[OneConnector.java],
instantiates, configures, and adds a single HTTP connector instance to the server:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneConnector.java[]
----
In this example the connector handles the HTTP protocol, as that is the default for the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] class.
===== Many Connectors
When configuring multiple connectors (for example, HTTP and HTTPS), it may be desirable to share configuration of common parameters for HTTP.
To achieve this you need to explicitly configure the `ServerConnector` class with `ConnectionFactory` instances, and provide them with common HTTP configuration.
The link:{JDURL}/org/eclipse/jetty/embedded/ManyConnectors.html[ManyConnectors example], configures a server with two `ServerConnector` instances: the http connector has a link:{JDURL}/org/eclipse/jetty/server/HttpConnectionFactory.html[`HTTPConnectionFactory`] instance; the https connector has a `SslConnectionFactory` chained to a `HttpConnectionFactory`.
Both `HttpConnectionFactory` are configured based on the same link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[`HttpConfiguration`] instance, however the HTTPS factory uses a wrapped configuration so that a link:{JDURL}/org/eclipse/jetty/server/SecureRequestCustomizer.html[`SecureRequestCustomizer`] can be added.
==== Embedding Servlets
http://en.wikipedia.org/wiki/Java_Servlet[Servlets] are the standard way to provide application logic that handles HTTP requests.
Servlets are similar to a Jetty Handler except that the request object is not mutable and thus cannot be modified.
Servlets are handled in Jetty by a link:{JDURL}/org/eclipse/jetty/embedded/MinimalServlets.html[`ServletHandler`].
It uses standard path mappings to match a Servlet to a request; sets the requests `servletPath` and `pathInfo`; passes the request to the servlet, possibly via Filters to produce a response.
The link:{JDURL}/org/eclipse/jetty/embedded/MinimalServlets.html[MinimalServlets example] creates a `ServletHandler` instance and configures a single HelloServlet:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/MinimalServlets.java[]
----
==== Embedding Contexts
A link:{JDURL}/org/eclipse/jetty/embedded/OneContext.html[`ContextHandler`] is a `ScopedHandler` that responds only to requests that have a URI prefix that matches the configured context path.
Requests that match the context path have their path methods updated accordingly and the contexts scope is available, which optionally may include:
* A `Classloader` that is set as the Thread context `classloader` while request handling is in scope.
* A set of attributes that is available via the http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html[`ServletContext`] API.
* A set of init parameters that is available via the http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html[`ServletContext`] API.
* A base Resource which is used as the document root for static resource requests via the http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContext.html[`ServletContext`] API.
* A set of virtual host names.
The following link:{JDURL}/org/eclipse/jetty/embedded/OneContext.html[OneContext example] shows a context being established that wraps the link:{JDURL}/org/eclipse/jetty/embedded/HelloHandler.html[HelloHandler]:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneContext.java[]
----
When many contexts are present, you can embed a `ContextHandlerCollection` to efficiently examine a request URI to then select the matching `ContextHandler`(s) for the request.
The link:{JDURL}/org/eclipse/jetty/embedded/ManyContexts.html[ManyContexts example] shows how many such contexts you can configure:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyContexts.java[]
----
==== Embedding ServletContexts
A link:{JDURL}/org/eclipse/jetty/servlet/ServletContextHandler.html[`ServletContextHandler`] is a specialization of `ContextHandler` with support for standard sessions and Servlets.
The following link:{JDURL}/org/eclipse/jetty/embedded/OneServletContext.html[OneServletContext example] instantiates a link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[`DefaultServlet`] to server static content from /tmp/ and a `DumpServlet` that creates a session and dumps basic details about the request:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneServletContext.java[]
----
==== Embedding Web Applications
A link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`] is an extension of a `ServletContextHandler` that uses the http://en.wikipedia.org/wiki/WAR_%28Sun_file_format%29[standard layout] and web.xml to configure the servlets, filters and other features from a web.xml and/or annotations.
The following link:{JDURL}/org/eclipse/jetty/embedded/OneWebApp.html[OneWebApp example] configures the Jetty test webapp.
Web applications can use resources the container provides, and in this case a `LoginService` is needed and also configured:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebApp.java[]
----
==== Like Jetty XML
The typical way to configure an instance of the Jetty server is via `jetty.xml` and associated configuration files.
However the Jetty XML configuration format is just a simple rendering of what you can do in code; it is very simple to write embedded code that does precisely what the jetty.xml configuration does.
The link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/LikeJettyXml.java[LikeJettyXml example] following renders in code the behavior obtained from the configuration files:
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty.xml[jetty.xml]
* link:{GITBROWSEURL}/jetty-jmx/src/main/config/etc/jetty-jmx.xml[jetty-jmx.xml]
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[jetty-http.xml]
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-https.xml[jetty-https.xml]
* link:{GITBROWSEURL}/jetty-deploy/src/main/config/etc/jetty-deploy.xml[jetty-deploy.xml]
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-stats.xml[jetty-stats.xml]
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-requestlog.xml[jetty-requestlog.xml]
* link:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-lowresources.xml[jetty-lowresources.xml]
* link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/test-realm.xml[test-realm.xml]
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/LikeJettyXml.java[]
----

44
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-file-server.adoc
View File

@ -1,44 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-file-server]]
==== Simple File Server
This example shows how to create a simple file server in Jetty.
It is perfectly suitable for test cases where you need an actual web server to obtain a file from, it could easily be configured to serve files from a directory under `src/test/resources`.
Note that this does not have any logic for caching of files, either within the server or setting the appropriate headers on the response.
It is simply a few lines that illustrate how easy it is to serve out some files.
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/FileServer.java[]
----
===== Run it!
After you have started things up you should be able to navigate to http://localhost:8080/index.html (assuming one is in the resource base directory) and you are good to go.
===== Maven Coordinates
To use this example in your project you will need the following Maven dependencies declared.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
<version>${project.version}</version>
</dependency>
----

51
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-many-connectors.adoc
View File

@ -1,51 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-many-connectors]]
==== Multiple Connectors
This example shows how to configure Jetty to use multiple connectors, specifically so it can process both http and https requests.
Since the meat of this example is the server and connector configuration it only uses a simple HelloHandler but this example should be easily merged with other examples like those deploying servlets or webapps.
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ManyConnectors.java[]
----
===== Walkthrough
Start things up!
By using the `server.join()` the server thread will join with the current thread.
See link:http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Thread.html#join()[`Thread.join()`] for more details.
===== Maven Coordinates
To use this example in your project you will need the following Maven dependencies declared.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-security</artifactId>
<version>${project.version}</version>
</dependency>
----

51
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-minimal-servlet.adoc
View File

@ -1,51 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-minimal-servlet]]
==== Minimal Servlet
This example shows the bare minimum required for deploying a servlet into Jetty.
Note that this is strictly a servlet, not a servlet in the context of a web application, that example comes later.
This is purely just a servlet deployed and mounted on a context and able to process requests.
This example is excellent for situations where you have a simple servlet that you need to unit test, just mount it on a context and issue requests using your favorite http client library (like our Jetty client found in xref:client-http[]).
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/MinimalServlets.java[]
----
===== Walkthrough
Start things up! By using the `server.join()` the server thread will join with the current thread.
See link:http://docs.oracle.com/javase/1.5.0/docs/api/java/lang/Thread.html#join()[`Thread.join()`] for more details.
It is really simple to create useful servlets for testing behaviors. Sometimes you need a http server to run a unit test against that will return test content and wiring up a servlet like this makes it trivial.
After you have started things up you should be able to navigate to http://localhost:8080/ and you are good to go.
===== Maven Coordinates
To use this example in your project you will need the following Maven dependencies declared.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-servlet</artifactId>
<version>${project.version}</version>
</dependency>
----

45
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-one-webapp.adoc
View File

@ -1,45 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-one-webapp]]
==== Web Application
This example shows how to deploy a simple webapp with an embedded instance of Jetty.
This is useful when you want to manage the lifecycle of a server programmatically, either within a production application or as a simple way to deploying and debugging a full scale application deployment.
In many ways it is easier then traditional deployment since you control the classpath yourself, making this easy to wire up in a test case in Maven and issue requests using your favorite http client library (like our Jetty client found in xref:client-http[]).
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneWebApp.java[]
----
===== Run it!
After you have started things up you should be able to navigate to http://localhost:8080/ and you are good to go.
===== Maven Coordinates
To use this example in your project you will need the following Maven dependencies declared.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-webapp</artifactId>
<version>${project.version}</version>
</dependency>
----

54
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-secured-hello-handler.adoc
View File

@ -1,54 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-secured-hello-handler]]
==== Secured Hello Handler
This example shows how to wrap one handler with another one that handles security.
We have a simple Hello Handler that just return a greeting but add on the restriction that to get this greeting you must authenticate.
Another thing to remember is that this example uses the `ConstraintSecurityHandler` which is what supports the security mappings inside of the servlet api, it could be easier to show just the `SecurityHandler` usage, but the constraint provides more configuration power.
If you don't need that you can drop the Constraint bits and use just the `SecurityHandler`.
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java[]
----
===== Run it!
After you have started things up you should be able to navigate to http://localhost:8080/index.html (assuming one is in the resource base directory) and you are good to go.
===== The Realm Properties File
[source,properties]
----
include::{SRCDIR}/examples/embedded/src/test/resources/realm.properties[]
----
===== Maven Coordinates
To use this example in your project you will need the following Maven dependencies declared.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
<version>${project.version}</version>
</dependency>
----

51
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/examples/embedded-split-file-server.adoc
View File

@ -1,51 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[embedded-split-file-server]]
==== Split File Server
This example builds on the link:#emebedded-file-server[Simple File Server] to show how chaining multiple `ResourceHandlers` together can let you aggregate multiple directories to serve content on a single path and how you can link these together with `ContextHandlers`.
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java[]
----
===== Run it!
After you have started things up you should be able to navigate to http://localhost:8090/index.html (assuming one is in the resource base directory) and you are good to go.
Any requests for files will be looked for in the first resource handler, then the second, and so on and so forth.
===== Maven Coordinates
To use this example as is in your project you will need the following maven dependencies declared.
We would recommend not using the toolchain dependency in your actual application.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-server</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.toolchain</groupId>
<artifactId>jetty-test-helper</artifactId>
<version>2.2</version>
</dependency>
----

89
documentation/jetty-documentation/src/main/asciidoc/old_docs/embedding/jetty-helloworld.adoc
View File

@ -1,89 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[jetty-helloworld]]
=== Jetty Embedded HelloWorld
This section provides a tutorial that shows how you can quickly develop embedded code against the Jetty API.
[[downloading-jars]]
==== Downloading the Jars
Jetty is decomposed into many jars and dependencies to achieve a minimal footprint by selecting the minimal set of jars.
Typically it is best to use something like link:#jetty-maven-helloworld[Maven] to manage jars, however this tutorial uses an aggregate Jar that contains all of the required Jetty classes in one Jar.
You can manually download the aggregate link:https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/{VERSION}/jetty-all-{VERSION}-uber.jar[`jetty-all.jar`] using `curl` or a browser.
____
[NOTE]
The central Maven repository has started to aggressively reject/deny access to the repository from the `wget` command line tool (due to abusive use of the tool by some groups).
The administrators of the central maven repository have stated that the recommended command line download tool is now curl.
____
____
[IMPORTANT]
The `jetty-all` jar referenced in this section is for example purposes only and should not be used outside of this context.
Please consider using link:#jetty-maven-helloworld[Maven] to manage your project dependencies.
____
Use curl as follows:
[source, screen, subs="{sub-order}"]
....
> mkdir Demo
> cd Demo
> curl -o jetty-all-uber.jar https://repo1.maven.org/maven2/org/eclipse/jetty/aggregate/jetty-all/{VERSION}/jetty-all-{VERSION}-uber.jar
....
[[writing-helloworld-example]]
==== Writing a HelloWorld Example
The link:#embedding[Embedding Jetty] section contains many examples of writing against the Jetty API.
This tutorial uses a simple HelloWorld handler with a main method to run the server.
You can either link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/HelloWorld.java[download] or create in an editor the file `HelloWorld.java` with the following content:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/HelloWorld.java[]
----
[[compiling-helloworld-example]]
==== Compiling the HelloWord example
The following command compiles the HelloWorld class:
[source, screen, subs="{sub-order}"]
....
> mkdir classes
> javac -d classes -cp jetty-all-uber.jar HelloWorld.java
....
[[running-handler-and-server]]
==== Running the Handler and Server
The following command runs the HelloWorld example:
[source, screen, subs="{sub-order}"]
....
> java -cp classes:jetty-all-uber.jar org.eclipse.jetty.demos.HelloWorld
....
You can now point your browser at http://localhost:8080/[http://localhost:8080] to see your hello world page.
[[next-steps]]
==== Next Steps
To learn more about Jetty, take these next steps:
* Follow the examples in link:#embedding-jetty[Embedding Jetty] to better understand the jetty APIs.
* Explore the complete link:{JDURL}/[Jetty javadoc]
* Consider using link:#maven-and-jetty[Jetty and Maven] to manage your Jars and dependencies.

34
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/balancer-servlet.adoc
View File

@ -1,34 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[balancer-servlet]]
=== Balancer Servlet
[[balancer-servlet-metadata]]
==== Info
* Classname: `org.eclipse.jetty.proxy.BalancerServlet`
* Maven Artifact: org.eclipse.jetty:jetty-proxy
* Javadoc: {JDURL}/org/eclipse/jetty/proxy/BalancerServlet.html
[[balancer-servlet-usage]]
==== Usage
The Balancer servlet allows for simple, sticky round robin load balancing leveraging the `ProxyServlet` that is distributed with Jetty.
In addition to the parameters for `ProxyServlet`, the following are available for the balancer servlet:
stickySessions::
True if sessions should be sticky for subsequent requests
balancerMember.<name>.proxyTo::
One of more of these are required and will be the locations that are used to proxy traffic to.

41
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/chapter.adoc
View File

@ -1,41 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[advanced-extras]]
== Provided Servlets, Filters, and Handlers
Jetty ships with a bundle of servlets that interact with the key classes.
Most are in the org.eclipse.jetty.servlets package.
These servlets and filters are among the principle elements of Jetty as a component-based infrastructure that holds and runs J2EE applications.
As described, they play a major role in running and maintaining the Jetty server.
Also included are a number of Jetty specific handlers that allow access to internals of jetty that would not normally be exposed and are very useful testing environments and many production scenarios.
include::default-servlet.adoc[]
include::proxy-servlet.adoc[]
include::balancer-servlet.adoc[]
include::qos-filter.adoc[]
include::dos-filter.adoc[]
include::header-filter.adoc[]
include::gzip-filter.adoc[]
include::cross-origin-filter.adoc[]
include::resource-handler.adoc[]
include::debug-handler.adoc[]
include::statistics-handler.adoc[]
include::inetaccess-handler.adoc[]
include::moved-context-handler.adoc[]
include::shutdown-handler.adoc[]
include::default-handler.adoc[]
include::error-handler.adoc[]
include::rewrite-handler.adoc[]

91
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/cross-origin-filter.adoc
View File

@ -1,91 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[cross-origin-filter]]
=== Cross Origin Filter
[[cross-origin-filter-metadata]]
==== Info
* Classname: `org.eclipse.jetty.ee9.servlets.CrossOriginFilter`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/servlets/CrossOriginFilter.html
[[cross-origin-filter-usage]]
==== Usage
HTTP requests made from a script are subject to well known restrictions, the most prominent being the same domain policy.
Firefox 3.5 introduced support for W3C's Access Control for Cross-Site Requests specification, which requires a compliant client (for example, Firefox 3.5) and a compliant server (via this servlet filter).
This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object.
If the client does not issue a compliant cross-domain request, this filter does nothing, and its overhead is the check of the presence of the cross-domain HTTP header.
This is extremely useful in CometD web applications where it is now possible to perform cross-domain long polling without using script injection (also known as the JSONP transport), and therefore removing all the downsides that the JSONP transport has (it's chattier, does not react quickly to failures, has a message size limit, uses GET instead of POST, etc.).
[[cross-origin-setup]]
==== Setup
You will need to put the `jetty-servlets.jar` file onto your classpath.
If you are creating a webapp, ensure that this jar is included in your webapp's `WEB-INF/lib`.
Or, if you are running Jetty embedded you will need to ensure that `jetty-servlets.jar` is on the execution classpath.
You can download the `jetty-servlets.jar` from the Maven Central Repository at https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-servlets/.
It is also available as part of the Jetty distribution in the `$JETTY_HOME/lib` directory.
[[cross-origin-config]]
==== Configuration
This is a regular servlet filter that must be configured in `web.xml`.
It supports the following configuration parameters:
allowedOrigins::
A comma separated list of origins that are allowed to access the resources.
Default value is: * (all origins)
allowedMethods::
A comma separated list of HTTP methods that are allowed to be used when accessing the resources.
Default value is: GET,POST,HEAD
allowedHeaders::
A comma separated list of HTTP headers that are allowed to be specified when accessing the resources.
Default value is: X-Requested-With,Content-Type,Accept,Origin
allowCredentials::
A boolean indicating if the resource allows requests with credentials.
Default value is: true
preflightMaxAge::
The number of seconds that preflight requests can be cached by the client.
Default value is 1800 seconds (30 minutes)
chainPreflight::
If true preflight requests are chained to their target resource for normal handling (as an OPTION request).
Otherwise the filter will response to the preflight.
Default is true.
exposedHeaders::
A comma separated list of HTTP headers that are allowed to be exposed on the client.
Default value is the empty list.
A typical configuration could be:
[source, xml, subs="{sub-order}"]
----
<web-app>
<filter>
<filter-name>cross-origin</filter-name>
<filter-class>org.eclipse.jetty.ee9.servlets.CrossOriginFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>cross-origin</filter-name>
<url-pattern>/cometd/*</url-pattern>
</filter-mapping>
</web-app>
----

63
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/debug-handler.adoc
View File

@ -1,63 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[debug-handler]]
=== Debug Handler
[[debug-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.DebugHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/DebugHandler.html
[[debug-handler-usage]]
==== Usage
A simple handler that is useful to debug incoming traffic.
It will log entry and exit points of HTTP requests as well as the response code.
==== Usage in Standard Distribution
The debug handler can be added to Jetty by activating the `debug` module.
==== Embedded usage
[source, java, subs="{sub-order}"]
----
Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10);
DebugHandler debugHandler = new DebugHandler();
debugHandler.setOutputStream(outputStream);
debugHandler.setHandler(server.getHandler());
server.setHandler(debugHandler);
server.start();
----
==== Example output
[source,bash]
----
15:14:05.838:qtp551889550-13-selector-0 OPENED HttpConnection@e910ee4{IDLE},g=HttpGenerator{s=START},p=HttpParser{s=START,0 of 0}
15:14:05.846:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/ REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:05.894:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/ RESPONSE 200 null
15:14:05.959:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/jetty.css REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:05.962:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/jetty.css RESPONSE 200 null
15:14:06.052:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/images/jetty-header.jpg REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:06.055:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/images/jetty-header.jpg RESPONSE 200 null
15:14:07.248:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:07.251:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico RESPONSE 404 text/html;charset=ISO-8859-1
15:14:09.330:qtp551889550-57 CLOSED HttpConnection@e910ee4{INTERESTED},g=HttpGenerator{s=START},p=HttpParser{s=START,0 of -1}
----

47
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/default-handler.adoc
View File

@ -1,47 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[default-handler]]
=== Default Handler
[[default-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.DefaultHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/DefaultHandler.html
[[default-handler-usage]]
==== Usage
A simple handler that is useful to terminate handler chains with a clean fashion.
As in the example below, if a resource to be served is not matched within the resource handler the `DefaultHandler` will take care of producing a 404 page.
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an link:#error-handler[Error Handler] that services errors related to the servlet api specification, so it is best to not get the two confused.
_____
[NOTE]
The `DefaultHandler` will also handle serving out the `favicon.ico` file should a request make it through all of the other handlers without being resolved.
_____
[source, java, subs="{sub-order}"]
----
Server server = new Server(8080);
ResourceHandler resourceHandler = new ResourceHandler();
resourceHandler.setBaseResource(ResourceFactory.of(resourceHandler).newResource("."));
Handler.Sequence handlers = new Handler.Sequence(
resourceHandler, new DefaultHandler()
);
server.setHandler(handlers);
server.start();
----

83
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/default-servlet.adoc
View File

@ -1,83 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[default-servlet]]
=== Default Servlet
[[default-servlet-metadata]]
==== Info
* Classname: `org.eclipse.jetty.ee9.servlet.DefaultServlet`
* Maven Artifact: org.eclipse.jetty:jetty-servlet
* Javadoc: {JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html
[[default-servlet-usage]]
==== Usage
The `DefaultServlet` implements the `ResourceFactory` interface and extends the `HttpServlet` abstract class.
It is usually mapped to "/" and provides handling for static content, `OPTION` and `TRACE` methods for the context.
The `MOVE` method is allowed if `PUT` and `DELETE` are allowed.
See the `DefaultServlet` link:{JDURL}/org/eclipse/jetty/servlet/DefaultServlet.html[javadoc].
[[default-servlet-init]]
==== Init Parameters
Jetty supports the following `initParameters`:
acceptRanges::
If `true`, range requests and responses are supported.
dirAllowed::
If `true`, directory listings are returned if no welcome file is found.
Otherwise 403 Forbidden displays.
redirectWelcome::
If `true`, welcome files are redirected rather that forwarded.
welcomeServlets::
If `true`, attempt to dispatch to welcome files that are servlets, but only after no matching static
resources could be found. If `false`, then a welcome file must exist on disk. If `exact`, then exact
servlet matches are supported without an existing file. Default is `false`. This must be `false` if you want directory listings,
but have index.jsp in your welcome file list.
precompressed::
If set to a comma separated list of encoding types (that may be listed in a requests Accept-Encoding header) to file extension mappings to look for and serve.
For example: `br=.br,gzip=.gz,bzip2=.bz`.
If set to a boolean `true`, then a default set of compressed formats will be used, otherwise no precompressed formats supported.
gzip::
Deprecated. Use `precompressed` instead. If set to `true`, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".
resourceBase::
Set to replace the context resource base.
resourceCache::
If set, this is a context attribute name, which the servlet will use to look for a shared ResourceCache instance.
relativeResourceBase::
Set with a pathname relative to the base of the servlet context root. Useful for only serving static content out of only specific subdirectories.
cacheControl::
If set, all static content will have this value set as the cache-control header.
pathInfoOnly::
If `true`, only the path info will be applied to the resourceBase
stylesheet::
Set with the location of an optional stylesheet that will be used to decorate the directory listing html.
etags::
If `true`, weak etags will be generated and handled.
maxCacheSize::
Maximum total size of the cache or 0 for no cache.
maxCachedFileSize::
Maximum size of a file to cache.
maxCachedFiles::
Maximum number of files to cache.
useFileMappedBuffer::
If set to `true`, mapped file buffer serves static content.
Setting this value to `false` means that a direct buffer is used instead of a mapped file buffer.
By default, this is set to `true`.
otherGzipFileExtensions::
A comma separated list of other file extensions that signify that a file is gzip compressed.
If you don't explicitly set this, it defaults to `.svgz`.
encodingHeaderCacheSize::
Max entries in a cache of ACCEPT-ENCODING headers

102
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/dos-filter.adoc
View File

@ -1,102 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[dos-filter]]
=== Denial of Service Filter
[[dos-filter-metadata]]
==== Info
* Classname: `org.eclipse.jetty.ee9.servlets.DoSFilter`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/servlets/DoSFilter.html
[[dos-filter-usage]]
==== Usage
The Denial of Service (DoS) filter limits exposure to request flooding, whether malicious, or as a result of a misconfigured client.
The DoS filter keeps track of the number of requests from a connection per second.
If the requests exceed the limit, Jetty rejects, delays, or throttles the request, and sends a warning message.
The filter works on the assumption that the attacker might be written in simple blocking style, so by suspending requests you are hopefully consuming the attacker's resources.
[[dos-filter-using]]
==== Using the DoS Filter
Jetty places throttled requests in a queue, and proceed only when there is capacity available.
===== Required JARs
To use the DoS Filter, these JAR files must be available in WEB-INF/lib:
* $JETTY_HOME/lib/jetty-util.jar
* $JETTY_HOME/lib/jetty-servlets.jar
===== Sample Configuration
Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:
[source, xml, subs="{sub-order}"]
----
<filter>
<filter-name>DoSFilter</filter-name>
<filter-class>org.eclipse.jetty.ee9.servlets.DoSFilter</filter-class>
<init-param>
<param-name>maxRequestsPerSec</param-name>
<param-value>30</param-value>
</init-param>
</filter>
----
[[dos-filter-init]]
===== Configuring DoS Filter Parameters
The following `init` parameters control the behavior of the filter:
maxRequestsPerSec::
Maximum number of requests from a connection per second.
Requests in excess of this are first delayed, then throttled.
Default is 25.
delayMs::
Delay imposed on all requests over the rate limit, before they are considered at all:
* 100 (ms) = Default
* -1 = Reject request
* 0 = No delay
* any other value = Delay in ms
maxWaitMs::
Length of time, in ms, to blocking wait for the throttle semaphore.
Default is 50 ms.
throttledRequests::
Number of requests over the rate limit able to be considered at once.
Default is 5.
throttleMs::
Length of time, in ms, to async wait for semaphore. Default is 30000L.
maxRequestMs::
Length of time, in ms, to allow the request to run. Default is 30000L.
maxIdleTrackerMs::
Length of time, in ms, to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
Default is 30000L.
insertHeaders::
If true, insert the DoSFilter headers into the response.
Defaults to true.
remotePort::
If true, then rate is tracked by IP and port (effectively connection).
Defaults to false.
ipWhitelist::
A comma-separated list of IP addresses that will not be rate limited.
managedAttr::
If set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via `ContextHandler.MANAGED_ATTRIBUTES`) to manage the configuration of the filter.

29
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/error-handler.adoc
View File

@ -1,29 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[error-handler]]
=== Error Handler
[[error-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.ErrorHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/ErrorHandler.html
[[error-handler-usage]]
==== Usage
A handler that is used to report errors from servlet contexts and webapp contexts to report error conditions.
Primarily handles setting the various servlet spec specific response headers for error conditions.
Can be customized by extending; for more information on this see xref:custom-error-pages[].

92
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/gzip-filter.adoc
View File

@ -1,92 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[gzip-filter]]
=== Gzip Handler
[[gzip-filter-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.gzip.GzipHandler`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/gzip/GzipHandler.html
[[gzip-filter-usage]]
==== Usage
The Jetty `GzipHandler` is a compression handler that you can apply to any dynamic resource (servlet).
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length.
Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).
The `GzipHandler` can be added to the entire server by enabling the `gzip.mod` module.
It may also be added to individual contexts in a context xml file.
____
[NOTE]
Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function.
____
[[gzip-filter-rules]]
==== Gzip Rules
`GzipHandler` will gzip the content of a response if:
* It is mapped to a matching path
* The request method is configured to support gzip
* The request is not from an excluded User-Agent
* accept-encoding header is set to gzip
* The response status code is >=200 and <300
* The content length is unknown or more than the minGzipSize initParameter or the minGzipSize is 0(default)
* The content-type does not match an excluded mime-type
* No content-encoding is specified by the resource
Compressing the content can greatly improve the network bandwidth usage, but at the cost of memory and CPU cycles.
The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed static content, which saves memory and CPU.
The `GzipHandler` installs an output interceptor which passes through to the `DefaultServlet`.
If the content served by `DefaultServlet` is already compressed, the `GzipHandler` does nothing; if it is not compressed, the content is compressed on-the-fly.
____
[NOTE]
Automatic precompression by the `DefaultServlet` can be configured.
Read more about the `DefaultServlet` link:#default-servlet[here.]
____
[[gzip-filter-init]]
==== Gzip Configuration
minGzipSize::
Content will only be compressed if content length is either unknown or greater than `minGzipSize`.
checkGzExists (Deprecated)::
False by default.
If set to true, the handler will check for pre-compressed content.
includedMethods::
List of HTTP methods to compress.
If not set, only `GET` requests are compressed.
includedMimeTypes::
List of MIME types to compress.
excludedMimeTypes::
List of MIME types not to compress.
excludedAgentPatterns::
A list of regex patterns for User-Agent names from which requests should not be compressed.
excludedPaths::
List of paths to exclude from compression.
Performs a `String.startsWith(String)` comparison to check if the path matches.
If it does match then there is no compression.
To match subpaths use excludePathPatterns instead.
includedPaths::
List of paths to consider for compression.
includePaths::
List of paths to definitely consider for compression.

112
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/header-filter.adoc
View File

@ -1,112 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[header-filter]]
=== Header Filter
[[header-filter-metadata]]
==== Info
* Classname: `org.eclipse.jetty.ee9.servlets.HeaderFilter`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/servlets/HeaderFilter.html
[[header-filter-usage]]
==== Usage
The header filter sets or adds headers to each response based on an optionally included/excluded list of path specs, mime types, and/or HTTP methods.
This filter processes its configured headers before calling `doFilter` in the filter chain. Some of the headers configured in this filter may get overwritten by other filters and/or the servlet processing the request.
===== Required JARs
To use the Header Filter, these JAR files must be available in WEB-INF/lib:
* $JETTY_HOME/lib/jetty-http.jar
* $JETTY_HOME/lib/jetty-servlets.jar
* $JETTY_HOME/lib/jetty-util.jar
===== Sample Configuration
Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
This filter will perform the following actions on each response:
* Set the X-Frame-Options header to DENY.
* Add a Cache-Control header containing no-cache, no-store, must-revalidate
* Set the Expires header to approximately one year in the future.
* Add a Date header with the current system time.
____
[NOTE]
Each action must be separated by a comma.
____
[source, xml, subs="{sub-order}"]
----
<filter>
<filter-name>HeaderFilter</filter-name>
<filter-class>org.eclipse.jetty.ee9.servlets.HeaderFilter</filter-class>
<init-param>
<param-name>headerConfig</param-name>
<param-value>
set X-Frame-Options: DENY,
"add Cache-Control: no-cache, no-store, must-revalidate",
setDate Expires: 31540000000,
addDate Date: 0
</param-value>
</init-param>
</filter>
----
[[header-filter-init]]
===== Configuring Header Filter Parameters
The following `init` parameters control the behavior of the filter:
includedPaths::
Optional. Comma separated values of included path specs.
excludedPaths::
Optional. Comma separated values of excluded path specs.
includedMimeTypes::
Optional. Comma separated values of included mime types. The mime type will be guessed from the extension at the end of the request URL if the content type has not been set on the response.
excludedMimeTypes::
Optional. Comma separated values of excluded mime types. The mime type will be guessed from the extension at the end of the request URL if the content type has not been set on the response.
includedHttpMethods::
Optional. Comma separated values of included http methods.
excludedHttpMethods::
Optional. Comma separated values of excluded http methods.
headerConfig::
Comma separated values of actions to perform on headers. The syntax for each action is `action headerName: headerValue`.
Supported header actions:
* `set` - causes set `setHeader` to be called on the response
* `add` - causes set `addHeader` to be called on the response
* `setDate` - causes `setDateHeader` to be called on the response.
* `addDate` - causes `addDateHeader` to be called on the response.
If `setDate` or `addDate` is used, `headerValue` should be the number of milliseconds to add to the current system time before writing the header value.
If a property is both included and excluded by the filter configuration, then it will be considered excluded.
Path spec rules:
* If the spec starts with `^`, the spec is assumed to be a regex based path spec and will match with normal Java regex rules.
* If the spec starts with `/`, the spec is assumed to be a Servlet url-pattern rules path spec for either an exact match or prefix based match.
* If the spec starts with `*.`, the spec is assumed to be a Servlet url-pattern rules path spec for a suffix based match.
* All other syntaxes are unsupported.

32
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/inetaccess-handler.adoc
View File

@ -1,32 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[inetaccess-handler]]
=== InetAccess Handler
[[inetaccess-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.InetAccessHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/InetAccessHandler.html
[[inetaccess-handler-usage]]
==== Usage
Controls access to the wrapped handler using the real remote IP. Control is provided by and `IncludeExcludeSet` over a `InetAddressSet`.
This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.
==== Usage in Standard Distribution
The InetAccess handler can be added to Jetty by activating the `inetaccess` module.

69
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/ipaccess-handler.adoc
View File

@ -1,69 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[ipaccess-handler]]
=== IP Access Handler
[[ipaccess-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.IPAccessHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/IPAccessHandler.html
[[ipaccess-handler-usage]]
==== Usage
Controls access to the wrapped handler by the real remote IP.
Control is provided by white/black lists that include both internet addresses and URIs.
This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.
Typically, the black/white lists will be used in one of three modes:
* Blocking a few specific IPs/URLs by specifying several black list entries.
* Allowing only some specific IPs/URLs by specifying several white lists entries.
* Allowing a general range of IPs/URLs by specifying several general white list entries, that are then further refined by several specific black list exceptions.
An empty white list is treated as match all.
If there is at least one entry in the white list, then a request *must* match a white list entry.
Black list entries are always applied, so that even if an entry matches the white list, a black list entry will override it.
Internet addresses may be specified as absolute address or as a combination of four octet wildcard specifications (a.b.c.d) that are defined as follows.
* nnn - an absolute value (0-255)
* mmm-nnn - an inclusive range of absolute values, with following shorthand notations:
** nnn- => nnn-255
** -nnn => 0-nnn
** - => 0-255
* a,b,... - a list of wildcard specifications
Internet address specification is separated from the URI pattern using the "|" (pipe) character.
URI patterns follow the servlet specification for simple * prefix and suffix wild cards (e.g. /, /foo, /foo/bar, /foo/bar/*, *.baz).
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Both of these features have been deprecated in the current version.
Examples of the entry specifications are:
* 10.10.1.2 - all requests from IP 10.10.1.2
* 10.10.1.2|/foo/bar - all requests from IP 10.10.1.2 to URI /foo/bar
* 10.10.1.2|/foo/* - all requests from IP 10.10.1.2 to URIs starting with /foo/
* 10.10.1.2|*.html - all requests from IP 10.10.1.2 to URIs ending with .html
* 10.10.0-255.0-255 - all requests from IPs within 10.10.0.0/16 subnet
* 10.10.0-.-255|/foo/bar - all requests from IPs within 10.10.0.0/16 subnet to URI /foo/bar
* 10.10.0-3,1,3,7,15|/foo/* - all requests from IPs addresses with last octet equal to 1,3,7,15 in subnet 10.10.0.0/22 to URIs starting with /foo/
Earlier versions of the handler used internet address prefix wildcard specification to define a range of the internet addresses (e.g. 127., 10.10., 172.16.1.).
They also used the first "/" character of the URI pattern to separate it from the internet address.
Both of these features have been deprecated in the current version.

65
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/moved-context-handler.adoc
View File

@ -1,65 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[moved-context-handler]]
=== Moved Context Handler
[[moved-context-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.MovedContextHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/MovedContextHandler.html
[[moved-context-handler-usage]]
==== Usage
You can use the `MovedContextHandler` to relocate or redirect a context that has changed context path and/or virtual hosts.
You can configure it to _permanently_ redirect the old URL to the new URL, in which case Jetty sends a Http Status code of 301 to the browser with the new URL.
Alternatively, you can make it non-permanent, in which case Jetty sends a 302 Http Status code along with the new URL.
In addition, as with any other context, you can configure a list of virtual hosts, meaning that this context responds only to requests to one of the listed host names.
Suppose you have a context deployed at `/foo`, but that now you want to deploy at the root context `/` instead.
* First you reconfigure and redeploy the context on Jetty.
* Next you need a way to redirect all the browsers who have bookmarked `/foo` to the new path.
You create a new xref:configuring-contexts[context xml] file in `{$jetty/.base}/webapps` and configure the `MovedContextHandler` to do the redirection from `/foo` to `/`.
Below is an example.
This is a permanent redirection, which also preserves `pathinfo` and query strings on the redirect:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.server.handler.MovedContextHandler">
<Set name="contextPath">/foo</Set>
<Set name="newContextURL">/</Set>
<Set name="permanent">true</Set>
<Set name="discardPathInfo">false</Set>
<Set name="discardQuery">false</Set>
<Set name="virtualHosts">
<Array type="String">
<Item>209.235.245.73</Item>
<Item>127.0.0.73</Item>
<Item>acme.org</Item>
<Item>www.acme.org</Item>
<Item>server.acme.org</Item>
</Array>
</Set>
</Configure>
----

73
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/proxy-servlet.adoc
View File

@ -1,73 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[proxy-servlet]]
=== Proxy Servlet
[[proxy-servlet-metadata]]
==== Info
* Classname: `org.eclipse.jetty.proxy.ProxyServlet`
* Maven Artifact: org.eclipse.jetty:jetty-proxy
* Javadoc: {JDURL}/org/eclipse/jetty/proxy/ProxyServlet.html
[[proxy-servlet-usage]]
==== Usage
An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy.
Internally it uses the async jetty-client.
To facilitate JMX monitoring, the `HttpClient` instance is set as context attribute, prefixed with the servlet's name and exposed by the mechanism provided by `ContextHandler.MANAGED_ATTRIBUTES`.
[[proxy-servlet-init]]
==== Init Parameters
The following init parameters may be used to configure the servlet:
hostHeader::
forces the host header to a particular value
viaHost::
the name to use in the Via header: Via: http/1.1 <viaHost>
whiteList::
comma-separated list of allowed proxy hosts
blackList::
comma-separated list of forbidden proxy hosts
In addition, there are a number of init parameters that can be used to configure the `HttpClient` instance used internally for the proxy.
maxThreads::
Default Value: 256
The max number of threads of HttpClient's Executor
maxConnections::
Default Value: 32768
The max number of connections per destination.
RFC 2616 suggests that 2 connections should be opened per each destination, but browsers commonly open 6 or more.
If this `HttpClient` is used for load testing, it is common to have only one destination (the server to load test), and it is recommended to set this value to a high value (at least as much as the threads present in the executor).
idleTimeout::
Default Value: 30000
The idle timeout in milliseconds that a connection can be idle, that is without traffic of bytes in either direction.
timeout::
Default Value: 60000
The total timeout in milliseconds for the request/response conversation.
requestBufferSize::
Default Value: 4096
The size of the request buffer the request is written into.
responseBufferSize::
Default Value: 4096
The size of the response buffer the response is written into.

52
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/resource-handler.adoc
View File

@ -1,52 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[resource-handler]]
=== Resource Handler
[[resource-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.ResourceHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/ResourceHandler.html
[[resource-handler-usage]]
==== Usage
This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.
____
[IMPORTANT]
There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the xref:default-servlet[].
____
____
[NOTE]
Requests for resources that do not exist are let pass (Eg no 404's).
____
==== Improving the Look and Feel
The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
The default css is called `jetty-dir.css` and is located in the `jetty-util` package, pulled as a classpath resource from the `jetty-util` jar when requested through the `ResourceHandler`.
==== Embedded Example
The following is an example of a split fileserver, able to serve static content from multiple directory locations.
Since this handler does not return 404's on content you are able to iteratively try multiple resource handlers to resolve content.
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java[]
----

140
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/rewrite-handler.adoc
View File

@ -1,140 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[rewrite-handler]]
=== Rewrite Handler
The `RewriteHandler` matches a request against a set of rules, and modifies the request accordingly for any rules that match.
The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.
[[rewrite-handler-metadata]]
==== Info
* Classname: org.eclipse.jetty.rewrite.handler.RewriteHandler
* Maven artifact: org.eclipse.jetty:jetty-rewrite
* Javadoc: {JDURL}/org/eclipse/jetty/rewrite/handler/RewriteHandler.html
The standard Jetty distribution bundle contains the `jetty-rewrite` link:#startup-modules[module], so all you need to do is to enable it using one of the link:#start-jar[module commands], eg:
[source, screen, subs="{sub-order}"]
....
$ java -jar start.jar --add-to-start=rewrite
....
_____
[NOTE]
If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at http://localhost:8080/test/rewrite/
_____
==== Usage
The rewrite module enables the following Jetty xml config file on the execution path:
[source, xml, subs="{sub-order}"]
----
include::{SRCDIR}/jetty-rewrite/src/main/config/etc/jetty-rewrite.xml[]
----
As the commented out code shows, you configure the `RewriteHandler` by adding various rules.
There is an example of link:#rewrite-rules[rules] configuration in the standard distribution in the `demo-base/etc/demo-rewrite-rules.xml` file:
[source, xml, subs="{sub-order}"]
----
include::{SRCDIR}/demos/demo-jetty-webapp/src/main/config/modules/demo.d/demo-rewrite-rules.xml[]
----
===== Embedded Example
This is an example for embedded Jetty, which does something similar to the configuration file example above:
[source, java, subs="{sub-order}"]
----
Server server = new Server();
RewriteHandler rewrite = new RewriteHandler();
rewrite.setRewriteRequestURI(true);
rewrite.setRewritePathInfo(false);
rewrite.originalPathAttribute("requestedPath");
RedirectPatternRule redirect = new RedirectPatternRule();
redirect.setPattern("/redirect/*");
redirect.setReplacement("/redirected");
rewrite.addRule(redirect);
RewritePatternRule oldToNew = new RewritePatternRule();
oldToNew.setPattern("/some/old/context");
oldToNew.setReplacement("/some/new/context");
rewrite.addRule(oldToNew);
RewriteRegexRule reverse = new RewriteRegexRule();
reverse.setRegex("/reverse/([^/]*)/(.*)");
reverse.setReplacement("/reverse/$2/$1");
rewrite.addRule(reverse);
server.setHandler(rewrite);
----
[[rewrite-rules]]
==== Rules
There are several types of rules that are written extending useful base rule classes.
===== PatternRule
Matches against the request URI using the servlet pattern syntax.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/CookiePatternRule.html[CookiePatternRule]::
Adds a cookie to the response.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/HeaderPatternRule.html[HeaderPatternRule]::
Adds/modifies a header in the response.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/RedirectPatternRule.html[RedirectPatternRule]::
Redirects the response.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/ResponsePatternRule.html[ResponsePatternRule]::
Sends the response code (status or error).
link:{JDURL}/org/eclipse/jetty/rewrite/handler/RewritePatternRule.html[RewritePatternRule]::
Rewrite the URI by replacing the matched request path with a fixed string.
===== RegexRule
Matches against the request URI using regular expressions.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/RedirectRegexRule.html[RedirectRegexRule]::
Redirect the response.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/RewriteRegexRule.html[RewriteRegexRule]::
Rewrite the URI by matching with a regular expression.
(The replacement string may use `Template:$n` to replace the nth capture group.)
===== HeaderRule
Match against request headers. Match either on a header name and specific value, or on the presence of a header (with any value).
link:{JDURL}/org/eclipse/jetty/rewrite/handler/ForwardedSchemeHeaderRule.html[ForwardedSchemaHeaderRule]::
Set the scheme on the request (defaulting to HTTPS).
===== Others
Extra rules that defy standard classification.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/MsieSslRule.html[MsieSslRule]::
Disables the keep alive for SSL from IE5 or IE6.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/LegacyRule.html[LegacyRule]::
Implements the legacy API of RewriteHandler
===== RuleContainer
Groups rules together.
The contained rules will only be processed if the conditions for the `RuleContainer` evaluate to true.
link:{JDURL}/org/eclipse/jetty/rewrite/handler/VirtualHostRuleContainer.html[VirtualHostRuleContainer]::
Groups rules that apply only to a specific virtual host or a set of virtual hosts

62
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/shutdown-handler.adoc
View File

@ -1,62 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[shutdown-handler]]
=== Shutdown Handler
[[shutdown-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.ShutdownHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/ShutdownHandler.html
[[shutdown-handler-usage]]
==== Usage
A handler that shuts the server down on a valid request.
This is used to perform "soft" restarts from Java.
If `_exitJvm` is set to true a hard `System.exit()` call is being made.
This is an example of how you can setup this handler directly with the Server.
It can also be added as a part of handler chain or collection.
[source, java, subs="{sub-order}"]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
handlers.setHandlers(new Handler[]
{ someOtherHandler, new ShutdownHandler(server,"secret password") });
server.setHandler(handlers);
server.start();
----
This is an example that you can use to call the shutdown handler from within java.
[source, java, subs="{sub-order}"]
----
public static void attemptShutdown(int port, String shutdownCookie) {
try {
URL url = new URL("http://localhost:" + port + "/shutdown?token=" + shutdownCookie);
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.getResponseCode();
logger.info("Shutting down " + url + ": " + connection.getResponseMessage());
} catch (SocketException e) {
logger.debug("Not running");
// Okay - the server is not running
} catch (IOException e) {
throw new RuntimeException(e);
}
}
----

108
documentation/jetty-documentation/src/main/asciidoc/old_docs/extras/statistics-handler.adoc
View File

@ -1,108 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[statistics-handler]]
=== Statistics Handler
[[statistics-handler-metadata]]
==== Info
* Classname: `org.eclipse.jetty.server.handler.StatisticsHandler`
* Maven Artifact: org.eclipse.jetty:jetty-server
* Javadoc: {JDURL}/org/eclipse/jetty/server/handler/StatisticsHandler.html
[[statistics-handler-usage]]
==== Usage
Jetty currently has two main statistics collection mechanisms:
* Instances of `ConnectionStatistics` can collect statistics for each connection of a connector.
* The `StatisticsHandler` class may be used to collect statistics for HTTP requests.
The `StatisticsHandler` and `ConnectionStatistics` are not included in the default Jetty configuration, these need to be configured manually or enabled using the Jetty `stats` module on the command line.
[source, screen, subs="{sub-order}"]
....
$ java -jar {$jetty.home}/start.jar --add-to-start=stats
....
In addition to these, the `SessionHandler` and `DefaultSessionCache` classes collect statistics for sessions.
These statistics are enabled by default and are accessible via JMX interface.
_____
[NOTE]
To view statistics, you have to be able to connect to Jetty using either JConsole or some other JMX agent. See xref:using-jmx[] for more information.
_____
[[request-statistics]]
==== Request Statistics
To collect request statistics a `StatisticsHandler` must be configured as one of the handlers of the server.
Typically this can be done as the top level handler, but you may choose to configure a statistics handler for just one context by creating a context configuration file.
You can enable the `StatisticsHandler` by activating the `stats` modules on the command line.
Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration.
The following fragment shows how to configure a top level statistics handler:
[source, xml, subs="{sub-order}"]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="insertHandler">
<Arg>
<New id="StatisticsHandler" class="org.eclipse.jetty.server.handler.StatisticsHandler"/>
</Arg>
</Call>
</Configure>
----
[[connection-statistics]]
==== Connection Statistics
Detailed statistics on connection duration and number of messages are only collated when a connection is closed.
The current and maximum number of connections are the only "live" statistics.
The following example shows how to turn on connection statistics in the Jetty XML format.
[source, xml, subs="{sub-order}"]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors">
<Arg>
<New class="org.eclipse.jetty.io.ConnectionStatistics"/>
</Arg>
</Call>
</Configure>
----
A special variant of `ConnectionStatistics` called `IncludeExcludeConnectionStatistics` allows you to refine which types of connection you want to collect statistics for.
The following example shows how this can be used to record statistics only for WebSocket connections.
[source, xml, subs="{sub-order}"]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors">
<Arg>
<New class="org.eclipse.jetty.io.IncludeExcludeConnectionStatistics">
<Call name="include" arg="org.eclipse.jetty.websocket.common.io.AbstractWebSocketConnection"/>
</New>
</Arg>
</Call>
</Configure>
----
[[session-statistics]]
==== Session Statistics
Session handling is built into Jetty for any servlet or webapp context.
Detailed statistics on session duration are only collated when a session is closed.
The current, minimum, and maximum number of sessions are the only "live" statistics.
The session statistics are enabled by default and do not need to be configured.

114
documentation/jetty-documentation/src/main/asciidoc/old_docs/frameworks/cdi.adoc
View File

@ -1,114 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[framework-cdi]]
=== CDI
Contexts and Dependency Injection for Java EE (http://www.cdi-spec.org/[CDI]) is a standard implemented by frameworks such as http://seamframework.org/Weld[Weld] and https://openwebbeans.apache.org/[Apache OpenWebBeans].
This is a common way to assemble and configure webapplications by a process often referred to as 'decoration'.
Jetty integration of CDI frameworks allows CDI to be used to inject the Filters, Servlets and Listeners created within a Servlet Context.
There are two approaches to integration:
* CDI implementation can integrate with Jetty.
This requires the CDI implementation to have Jetty specific code.
Since Jetty-9.4.20 a loosely bound mechanism has been available for CDI implementations to extends the Jetty `DecoratedObjectFactory` without hard API dependencies.
Prior to that, CDI implementations directly called jetty APIs that need to be explicitly exposed to the webapp.
* Alternately, Jetty can integrate with CDI implementations by using standard CDI SPIs.
==== Jetty CDI Modules
The Jetty distribution come with several CDI modules.
These modules do not provide CDI, but instead enable one of more integration mechanisms.
===== Jetty `cdi` Module
The `cdi` module supports either two modes of CDI integration which can be selected either by the "org.eclipse.jetty.ee9.cdi" context init parameter or the "org.eclipse.jetty.ee9.cdi" server attribute (which is initialised from the "jetty.cdi.mode" start property).
Supported modes are:
* `CdiSpiDecorator` Jetty will call the CDI SPI within the webapp to decorate objects (default).
* `CdiDecoratingLister` The webapp may register a decorator on the context attribute "org.eclipse.jetty.ee9.cdi.decorator".
-------------------------
cd $JETTY_BASE
java -jar $JETTY_HOME/start.jar --add-to-start=cdi
-------------------------
===== Jetty `cdi-decorate` Module
This module depends on the `cdi` module and sets the default mode to `CdiDecoratingListener`.
This is the preferred mode for Weld integration.
-------------------------
cd $JETTY_BASE
java -jar $JETTY_HOME/start.jar --add-to-start=cdi-decorate
-------------------------
===== Jetty `cdi-spi` Module
This module depends on the `cdi` module and sets the default mode to `CdiSpiDecorator`.
This is the preferred mode for Open Web Beans integration.
-------------------------
cd $JETTY_BASE
java -jar $JETTY_HOME/start.jar --add-to-start=cdi-spi
-------------------------
===== Jetty `cdi2` Module
This module supports the *deprecated* technique of exposing private Jetty decorate APIs to the CDI implementation in the webapp.
-------------------------
cd $JETTY_BASE
java -jar $JETTY_HOME/start.jar --add-to-start=cdi2
-------------------------
This module is equivalent to directly modifying the class path configuration with a `jetty-web.xml` like:
[source.XML, xml]
-------------------------------------------------------------
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Call name="prependServerClass">
<Arg>-org.eclipse.jetty.util.Decorator</Arg>
</Call>
<Call name="prependServerClass">
<Arg>-org.eclipse.jetty.util.DecoratedObjectFactory</Arg>
</Call>
<Call name="prependServerClass">
<Arg>-org.eclipse.jetty.server.handler.ContextHandler.</Arg>
</Call>
<Call name="prependServerClass">
<Arg>-org.eclipse.jetty.server.handler.ContextHandler</Arg>
</Call>
<Call name="prependServerClass">
<Arg>-org.eclipse.jetty.ee9.servlet.ServletContextHandler</Arg>
</Call>
</Configure>
-------------------------------------------------------------
____
[TIP]
The `cdi2` module or directly modifying the web application classpath will not work for Jetty 10.0.0 and later.
It should only be used for versions prior to Jetty 9.4.20 and/or Weld 3.1.2.Final
____
[[cdi-embedded]]
==== Embedded Jetty with CDI
When starting embedded Jetty programmatically from the `main` method, to use CDI it may be
necessary:
* enable a Jetty CDI integration mode
* and/or enable a CDI frame integration.
However, depending on the exact configuration of the embedded server, either or both steps may not be required as `ServletContainerInitializer`s may be discovered.
The details for embedding CDI is explained in the link:#weld-embedded[Embedded Jetty with Weld] section, which can also be adapted to other CDI frameworks.

20
documentation/jetty-documentation/src/main/asciidoc/old_docs/frameworks/chapter.adoc
View File

@ -1,20 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[frameworks]]
== Frameworks
include::cdi.adoc[]
include::weld.adoc[]
include::osgi.adoc[]
include::metro.adoc[]

57
documentation/jetty-documentation/src/main/asciidoc/old_docs/frameworks/metro.adoc
View File

@ -1,57 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[framework-metro]]
=== Metro
https://metro.java.net/[Metro] is the reference implementation for http://jcp.org/en/jsr/detail?id=109[web services].
You can easily use Metro with Jetty to integrate web services with your web applications.
[[metro-setup-distro]]
==== Metro Setup
1. https://metro.java.net/latest/download.html[Download] the Metro distribution and unpack it to your disk.
We'll refer to the unpacked location as `$metro.home`.
2. Create the directory `$jetty.home/lib/metro`
3. Copy the jars from $metro.home/lib to `$jetty.home/lib/metro`
4. Edit the start.ini file and add an OPTION line for metro near the end.
+
[source, plain, subs="{sub-order}"]
----
OPTIONS=metro
----
That's all the setup you need to do to integrate Jetty and Metro.
Now read the https://metro.java.net/discover/[Metro documentation] on https://metro.java.net/getting-started/[how to create web services].
The Metro distribution you downloaded should also contain several example web applications in the $metro.home/samples directory that you can build and deploy to Jetty (simply by copying the war file produced by the build).
Here's an example of the log output from Jetty when one of the sample Metro wars (from `$metro.home/samples/async`) is deployed to Jetty:
[source, screen, subs="{sub-order}"]
....
[2093] java -jar start.jar
2013-07-26 15:47:53.480:INFO:oejs.Server:main: jetty-9.0.4.v20130625
2013-07-26 15:47:53.549:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-home-{VERSION}/webapps/] at interval 1
Jul 26, 2013 3:47:53 PM com.sun.xml.ws.transport.http.servlet.WSServletContextListener contextInitialized
INFO: WSSERVLET12: JAX-WS context listener initializing
Jul 26, 2013 3:47:56 PM com.sun.xml.ws.server.MonitorBase createRoot
INFO: Metro monitoring rootname successfully set to: com.sun.metro:pp=/,type=WSEndpoint,name=/metro-async-AddNumbersService-AddNumbersImplPort
Jul 26, 2013 3:47:56 PM com.sun.xml.ws.transport.http.servlet.WSServletDelegate <init>
INFO: WSSERVLET14: JAX-WS servlet initializing
2013-07-26 15:47:56.800:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@75707c77{/metro-async,file:/tmp/jetty-0.0.0.0-8080-metro-async.war-_metro-async-any-/webapp/,AVAILABLE}{/metro-async.war}
2013-07-26 15:47:56.853:INFO:oejs.ServerConnector:main: Started ServerConnector@47dce809{HTTP/1.1}{0.0.0.0:8080}
....

1134
documentation/jetty-documentation/src/main/asciidoc/old_docs/frameworks/osgi.adoc
View File

File diff suppressed because one or more lines are too long

17
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/configuring/chapter.adoc
View File

@ -1,17 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quick-start-configure]]
== An Introduction to Jetty Configuration
include::what-to-configure.adoc[]

281
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/configuring/what-to-configure.adoc
View File

@ -1,281 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-config-what]]
=== What to Configure in Jetty
This section gives an overview of the components of Jetty you typically configure using the mechanisms outlined in the previous section.
xref:basic-architecture[] describes the structure of a Jetty server, which is good background reading to understand configuration, and is vital if you want to change the structure of the server as set up by the default configurations in the Jetty distribution.
However, for most purposes, configuration is a matter of identifying the correct configuration file and modifying existing configuration values.
[[intro-jetty-configuration-server]]
==== Configuring the Server
The Server instance is the central coordination object of a Jetty server; it provides services and life cycle management for all other Jetty server components.
In the standard Jetty distribution, the core server configuration is in `etc/jetty.xml` file, but you can mix in other server configurations which can include:
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` 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
handle a request as a collaboration between the handlers from a branch of the tree from root to leaf.
The default handler tree set up in the `etc/jetty.xml` file is a Handler Collection containing a Context Handler Collection and the Default Handler.
The Context Handler Collection selects the next handler by context path and is where deployed Context Handler and Web Application Contexts are added to the handler tree.
The Default Handler handles any requests not already handled and generates the standard 404 page.
Other configuration files may add handlers to this tree (for example, `jetty-rewrite.xml`, `jetty-requestlog.xml`) or configure components to hot deploy handlers (for example, `jetty-deploy.xml`).
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` 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.
For the server you can either set the collection of all connectors or add/remove individual connectors.
Services::
The server can hold additional service objects, sometimes as attributes, but often as aggregated LifeCycle beans.
Examples of services are Login Services and DataSources, which you configure at the server level and then inject into the web applications that use them.
[[intro-jetty-configuration-connectors]]
==== Configuring Connectors
A Jetty Server Connector is a network end point that accepts connections for one or more protocols which produce requests and/or messages for the Jetty server.
In the standard Jetty server distribution, several provided configuration files add connectors to the server for various protocols and combinations of protocols: `http.ini`, `https.ini` and `jetty-http2.xml`.
The configuration needed for connectors is typically:
Port::
The TCP/IP port on which the connector listens for connections is set using the the XML Property element which looks up the `jetty.http.port` (or `jetty.ssl.port`) property, and if not found defaults to 8080 (or 8443 for TLS).
Host::
You can configure a host either as a host name or IP address to identify a specific network interface on which to listen.
If not set, or set to the value of 0.0.0.0, the connector listens on all local interfaces.
The XML Property element is used to look up the host value from the `jetty.host` property.
Idle Timeout::
The time in milliseconds that a connection can be idle before the connector takes action to close the connection.
HTTP Configuration::
Connector types that accept HTTP semantics (including HTTP, HTTPS and HTTP2) are configured with a `HttpConfiguration` instance that contains common HTTP configuration that is independent of the specific wire protocol used.
Because these values are often common to multiple connector types, the standard Jetty Server distribution creates a single `HttpConfiguration` in the `jetty.xml` file which is used via the XML Ref element in the specific connector files.
SSL Context Factory::
The TLS connector types (HTTPS and HTTP2) configure an SSL Context Factory with the location of the server keystore and truststore for obtaining server certificates.
____
[NOTE]
Virtual hosts are not configured on connectors. You must configure individual contexts with the virtual hosts to which they respond.
____
____
[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.
____
[[intro-jetty-configuration-contexts]]
==== Configuring Contexts
A Jetty context is a handler that groups other handlers under a context path together with associated resources and is roughly equivalent to the standard ServletContext API.
A context may contain either standard Jetty handlers or a custom application handler.
____
[NOTE]
The servlet specification defines a web application.
In Jetty a standard web application is a specialized context that uses a standard layout and `WEB-INF/web.xml` to instantiate and configure classpath, resource base and handlers for sessions, security, and servlets, plus servlets for JSPs and static content.
Standard web applications often need little or no additional configuration, but you can also use the techniques for arbitrary contexts to refine or modify the configuration of standard web applications.
____
Configuration values that are common to all contexts are:
contextPath::
The contextPath is a URL prefix that identifies which context a HTTP request is destined for.
For example, if a context has a context path `/foo`, it handles requests to `/foo`, `/foo/index.html`,
`/foo/bar/`, and `/foo/bar/image.png` but it does not handle requests like `/`, `/other/`, or `/favicon.ico`.
A context with a context path of / is called the root context.
+
The context path can be set by default from the deployer (which uses the filename as the basis for the context path); or in code; or it can be set by a Jetty IoC XML that is either applied by the deployer or found in the `WEB-INF/jetty-web.xml` file of a standard web app context.
virtualHost::
A context may optionally have one or more virtual hosts set.
Unlike the host set on a connector (which selects the network interface on which to listen), a virtual host does not set any network parameters.
Instead a virtual host represents an alias assigned by a name service to an IP address, which may have many aliases.
To determine which virtual host a request is intended for, the HTTP client (browser) includes in the request the name used to look up the network address.
A context with a virtual host set only handles requests that have a matching virtual host in their request headers.
classPath::
A context may optionally have a classpath, so that any thread that executes a handler within the context has a thread context classloader set with the classpath.
A standard web application has the classpath initialized by the `WEB-INF/lib` and `WEB-INF/classes` directory and
has additional rules about delegating classloading to the parent classloader.
All contexts may have additional classpath entries added.
attributes::
Attributes are arbitrary named objects that are associated with a context and are frequently used to pass entities between a web application and its container.
For example the attribute `jakarta.servlet.context.tempdir` is used to pass the File instance that represents the assigned temporary directory for a web application.
resourceBase::
The resource base is a directory (or collection of directories or URL) that contains the static resources for the context.
These can be images and HTML files ready to serve or JSP source files ready to be compiled.
In traditional web servers this value is often called the docroot.
===== Context Configuration by API
In an embedded server, you configure contexts by directly calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] API as in the following example:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/OneContext.java[]
----
===== Context Configuration by IoC XML
You can create and configure a context entirely by IoC XML (either Jetty's or Spring).
The deployer discovers and hot deploys context IoC descriptors like the following which creates a context to serve the Javadoc from the Jetty distribution:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<!--
Configure a custom context for serving javadoc as static resources
-->
<Configure class="org.eclipse.jetty.server.handler.ContextHandler">
<Set name="contextPath">/javadoc</Set>
<Set name="resourceBase"><SystemProperty name="jetty.home" default="."/>/javadoc/</Set>
<Set name="handler">
<New class="org.eclipse.jetty.server.handler.ResourceHandler">
<Set name="welcomeFiles">
<Array type="String">
<Item>index.html</Item>
</Array>
</Set>
<Set name="cacheControl">max-age=3600,public</Set>
</New>
</Set>
</Configure>
----
[[intro-jetty-configuration-webapps]]
===== Configuring Web Applications
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`.
* 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.
* 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].
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:
* 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`.
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 `/`.
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).
To set the contextPath from within the WAR file, you can include a `WEB-INF/jetty-web.xml` file which contains IoC XML to set the context path:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="contextPath">/contextpath</Set>
</Configure>
----
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}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.ee9.webapp.WebAppContext">
<Set name="war"><SystemProperty name="jetty.home" default="."/>/webapps/test.war</Set>
<Set name="contextPath">/test</Set>
</Configure>
----
An example of setting the context path is included with the Jetty distribution in `$JETTY_HOME/webapps/test.xml`.
[[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.base}/webapps` directory for contexts to deploy.
A Context can be any of the following:
* A standard WAR file. (must in "`.war`").
* A directory containing an expanded WAR file. (must contain `{dir}/WEB-INF/web.xml` file).
* A directory containing static content.
* A XML descriptor in xref:jetty-xml-syntax[] that configures a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler] instance (Such as a
link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext]).
The new WebAppProvider will attempt to avoid double deployments during the directory scan with the following heuristics:
* Hidden files (starting with `"."`) are ignored
* Directories with names ending in `".d"` are ignored
* If a directory and matching WAR file exist with the same base name (eg: `foo/` and `foo.war`), then the directory is assumed to be the unpacked WAR and only the WAR is deployed (which may reuse the unpacked directory)
* If a directory and matching XML file exists (eg: `foo/` and `foo.xml`), then the directory is assumed to be an unpacked WAR and only the XML is deployed (which may use the directory in its own configuration)
* If a WAR file and matching XML file exist (eg: `foo.war` and `foo.xml`), then the WAR is assumed to be configured by the XML and only the XML is deployed.
____
[NOTE]
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.
===== 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.

22
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/getting-started/chapter.adoc
View File

@ -1,22 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quick-start-getting-started]]
== 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.
This guide covers the latter, a standalone distribution suitable for deploying web applications.
include::jetty-installing.adoc[]
include::jetty-running.adoc[]
include::jetty-common-configuration.adoc[]

184
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/getting-started/jetty-common-configuration.adoc
View File

@ -1,184 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-common-config]]
=== Common Jetty Configuration
[[creating-jetty-base]]
==== Creating a new Jetty Base
The `demo-base` directory described earlier is an example of the link:#startup-base-and-home[`jetty.base`] mechanism.
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::
The property that defines the location of the Jetty distribution, its libs, default modules and default XML files (typically start.jar, lib, etc).
jetty.base::
The property that defines the location of a specific implementation of a Jetty server, its configuration, logs and web applications (typically start.d/*.ini files, logs and webapps).
____
[IMPORTANT]
Your Jetty Home directory should be treated as a standard of truth and remain unmodified or changed.
Changes or additions to your configuration should take place in the Jetty Base directory.
____
The `jetty.home` and `jetty.base` properties may be explicitly set on the command line, or they can be inferred from the environment if used with commands like:
[source, screen, subs="{sub-order}"]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar
----
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}"]
----
> JETTY_BASE=/tmp/mybase
> 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 --create-startd
INFO : Base directory was modified
> java -jar $JETTY_HOME/start.jar --add-to-start=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
INFO: servlet initialised (transitively) in ${jetty.base}/start.d/servlet.ini
INFO: webapp initialised (transitively) in ${jetty.base}/start.d/webapp.ini
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
2015-06-04 11:10:16.581:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2015-06-04 11:10:16.589:INFO:oejw.StandardDescriptorProcessor:main: NO JSP Support for /, did not find org.eclipse.jetty.jsp.JettyJspServlet
2015-06-04 11:10:16.628:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@1a407d53{/,[file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/, jar:file:///tmp/jetty-0.0.0.0-8080-ROOT.war-_-any-4510228025526425427.dir/webapp/WEB-INF/lib/example-async-rest-jar-{VERSION}.jar!/META-INF/resources],AVAILABLE}{/ROOT.war}
2015-06-04 11:10:16.645:INFO:oejs.ServerConnector:main: Started ServerConnector@3abbfa04{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-04 11:10:16.646:INFO:oejs.Server:main: Started @634ms
----
[[quickstart-changing-jetty-port]]
==== Changing the Jetty Port
You can configure Jetty to run on a different port by setting the `jetty.http.port` property on the command line:
[source, screen, subs="{sub-order}"]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.http.port=8081
...
----
When the server starts, it will now run on port `8081`.
It is important to note that setting properties on the command line will only take affect for that instance of the server.
To change the configuration so that the server will always start on the desired port, you will need to edit the `start.d/http.ini`
____
[NOTE]
--
The configuration by properties works via the following chain:
* The `start.d/http.ini` file is part of the effective command line and contains the `--module=http` argument which activates the http module.
* 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:#quick-start-configure[Quickstart Configuration Guide] and link:#configuring-connectors[Configuring Connectors].
--
____
[[quickstart-starting-https]]
==== Adding SSL for HTTPS & HTTP2
Building on the example above, we can activate additional modules to add support HTTPS and HTTP2 for the server.
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-start=https,http2
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: alpn-impl/alpn-8
+ ALPN is a hosted at github under the GPL v2 with ClassPath Exception.
+ ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package.
+ http://github.com/jetty-project/jetty-alpn
+ http://openjdk.java.net/legal/gplv2+ce.html
Proceed (y/N)? y
INFO : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
INFO : alpn transitively enabled, ini template available with --add-to-start=alpn
INFO : alpn-impl/alpn-8 dynamic dependency of alpn
INFO : http2 initialized in ${jetty.base}/start.d/http2.ini
INFO : https initialized in ${jetty.base}/start.d/https.ini
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
MKDIR : ${jetty.base}/lib/alpn
DOWNLD: https://repo1.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO : Base directory was modified
> java -jar $JETTY_HOME/start.jar
[...]
2017-05-22 12:48:23.271:INFO:oejs.AbstractConnector:main: Started ServerConnector@134d0064{SSL,[ssl, alpn, h2, http/1.1]}{0.0.0.0:8443}
[...]
----
The `--add-to-start` 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:
* transitively enabled the `ssl` module 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.
* transitively enabled the `alpn` module that configures protocol negotiation on the SSL connector by adding `etc/jetty-alpn.xml` to the effective command line.
* creates `start.d/https.ini` that configures the HTTPS protocol on the SSL connector by adding `etc/jetty-https.xml` to the effective command line.
* creates `start.d/http2.ini` that configures the HTTP/2 protocol on the SSL connector by adding `etc/jetty-http2.xml` to the effective command line.
* checks for the existence of a `etc/keystore` file and if not present, downloads a demonstration keystore file.
[[quickstart-changing-https-port]]
===== Changing the Jetty HTTPS Port
You can configure the SSL connector to run on a different port by setting the `jetty.ssl.port` property on the command line:
[source, screen, subs="{sub-order}"]
----
> cd $JETTY_BASE
> java -jar $JETTY_HOME/start.jar jetty.ssl.port=8444
----
Alternatively, property values can be added to the effective command line built from the `start.ini` file or `start.d/*.ini` files, depending on your set up.
Please see the section on link:#start-vs-startd[Start.ini vs. Start.d] for more information.
==== More start.jar Options
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}"]
----
> java -jar $JETTY_HOME/start.jar --help
----

94
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/getting-started/jetty-installing.adoc
View File

@ -1,94 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[jetty-downloading]]
=== Downloading Jetty
==== Downloading the Jetty Distribution
The standalone Jetty distribution is available for download from the Eclipse Foundation:
____
*Jetty*
https://jetty.org/download.html
____
It is available in both zip and gzip formats; download the one most appropriate for your system.
When you download and unpack the binary, it is extracted into a directory called `jetty-home-VERSION.`
Put this directory in a convenient location.
The rest of the instructions in this documentation refer to this location as either `$JETTY_HOME` or as `$(jetty.home).`
_____
[IMPORTANT]
It is important that *only* stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
_____
[[distribution-content]]
===== Distribution Content
A summary of the distribution's contents follows.
The top-level directory contains:
.Contents
[width="80%",cols="40%,60%",options="header"]
|=======================================================================
|Location |Description |license-eplv10-aslv20.html |License file for Jetty
|README.txt |Useful getting started information
|VERSION.txt |Release information
|bin/ |Utility shell scripts to help run Jetty on Unix systems
|demo-base/ |A Jetty base directory to run a Jetty server with demonstration webapps
|etc/ |Directory for Jetty XML configuration files
|lib/ |All the JAR files necessary to run Jetty
|logs/ |Directory for request logs
|modules/ |Directory of module definitions
|notice.html |License information and exceptions
|resources/ |Directory containing additional resources for classpath, activated via configuration
|start.ini |File containing the arguments that are added to the effective command line (modules, properties and XML configuration files)
|start.jar |Jar that invokes Jetty (see also xref:quickstart-running-jetty[])
|webapps/ |Directory containing webapps that run under the default configuration of Jetty
|=======================================================================
[[jetty-home-downloading]]
==== Downloading the Jetty-Home Distribution
Jetty-Home is an alternate version of the distribution that contains only the necessary items to host a Jetty distribution.
It is intended for advanced users who are already familiar with Jetty and want to download a smaller distribution package.
Jetty-Home can be downloaded from the Maven Central repository:
____
*Jetty-Home*
https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-home/
____
Like the main Jetty distribution, Jetty-Home is available in both zip and gzip formats; download the one most appropriate for your system.
Notice that there are a number of other files with extensions of .sha or .md5 which are checksum files.
When you download and unpack the binary, it is extracted into a directory called `jetty-home-VERSION.`
Put this directory in a convenient location.
[[jetty-home-distribution-content]]
===== Distribution Content
A summary of the Jetty-Home's distribution contents follows.
The top-level directory contains:
.Contents
[width="80%",cols="40%,60%",options="header"]
|=======================================================================
|Location |Description |license-eplv10-aslv20.html |License file for Jetty
|VERSION.txt |Release information
|etc/ |Directory for Jetty XML configuration files
|lib/ |All the JAR files necessary to run Jetty
|modules/ |Directory of module definitions
|notice.html |License information and exceptions
|start.jar |Jar that invokes Jetty (see also xref:quickstart-running-jetty[])
|=======================================================================

121
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/getting-started/jetty-running.adoc
View File

@ -1,121 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-running-jetty]]
=== Running Jetty
Once you have a copy of the Jetty distribution downloaded, extract the `zip` or `tar.gz` file to a location where you have read and write access.
Jetty has no GUI (Graphical User Interface), so running the server and performing many configuration options is done from the command line.
Once you have access to your system's command line, navigate to the directory where you unpacked your copy of the Jetty distribution.
To start Jetty on the default port of 8080, run the following command:
[source,screen,subs="{sub-order}"]
----
$ java -jar start.jar
2017-09-20 15:45:11.986:INFO::main: Logging initialized @683ms to org.eclipse.jetty.util.log.StdErrLog
2017-09-20 15:45:12.197:WARN:oejs.HomeBaseWarning:main: This instance of Jetty is not running from a separate {jetty.base} directory, this is not recommended. See documentation at https://jetty.org/docs/
2017-09-20 15:45:12.243:INFO:oejs.Server:main: {VERSION}
2017-09-20 15:45:12.266:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///installs/repository/jetty/webapps/] at interval 1
2017-09-20 15:45:12.298:INFO:oejs.AbstractConnector:main: Started ServerConnector@39c0f4a{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-09-20 15:45:12.298:INFO:oejs.Server:main: Started @995ms
----
You can point a browser at this server at link:http://localhost:8080[].
However, as there are no webapps deployed in the `$JETTY_HOME` directory, you will see a 404 error page served by Jetty.
To stop the server, press `CTRL` + `c` or `CTRL` + `z` in your terminal.
*Note* the `HomeBaseWarning` - it is *not* recommended to run Jetty from the `$JETTY_HOME` directory.
Instead, see how to link:#creating-jetty-base[create a Jetty Base] below.
____
[NOTE]
You will see examples throughout the documentation referencing `$JETTY_HOME` and `$JETTY_BASE` as well as `{jetty.home}` and `{jetty.base}`.
These terms are used to refer to the location of your Jetty installation directories.
Many users find it helpful to define `$JETTY_HOME` as an environment variable that maps to their Jetty distribution directory.
More information can be found in our Administration section on link:#startup-base-and-home[managing Jetty Home and Jetty Base.]
____
[[demo-webapps-base]]
==== Demo Base
Within the standard Jetty distribution there is the `demo-base` directory.
This is a fully-functioning Jetty Base (more on that later) complete with numerous web applications demonstrating different Jetty functionality.
Additionally, the `demo-base` demonstrates the recommended way to run a Jetty base in a directory separate from `$JETTY_HOME`:
[source,screen,subs="{sub-order}"]
----
$ cd demo-base/
[my-base]$ java -jar /path/to/jetty-home/start.jar
2017-09-20 16:23:03.563:INFO::main: Logging initialized @429ms to org.eclipse.jetty.util.log.StdErrLog
2017-09-20 16:23:03.802:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:03.804:INFO:oejs.Server:main: {VERSION}
2017-09-20 16:23:03.819:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///installs/repository/jetty/demo-base/webapps/] at interval 1
2017-09-20 16:23:04.098:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=102ms
2017-09-20 16:23:04.103:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:04.267:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2017-09-20 16:23:04.267:INFO:oejs.session:main: No SessionScavenger set, using defaults
2017-09-20 16:23:04.268:INFO:oejs.session:main: Scavenging every 660000ms
2017-09-20 16:23:04.306:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@371a67ec{/async-rest,[file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-5319296087878801290.dir/webapp/, jar:file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-async-rest.war-_async-rest-any-5319296087878801290.dir/webapp/WEB-INF/lib/example-async-rest-jar-{VERSION}.jar!/META-INF/resources],AVAILABLE}{/async-rest.war}
2017-09-20 16:23:04.429:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=53ms
2017-09-20 16:23:04.432:WARN::main: test webapp is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:04.516:INFO:oejsh.ManagedAttributeListener:main: update QoSFilter null->org.eclipse.jetty.ee9.servlets.QoSFilter@7770f470 on o.e.j.w.WebAppContext@35e2d654{/test,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test.war-_test-any-6279588879522983394.dir/webapp/,STARTING}{/test.war}
2017-09-20 16:23:04.519:WARN:oeju.DeprecationWarning:main: Using @Deprecated Class org.eclipse.jetty.ee9.servlets.MultiPartFilter
2017-09-20 16:23:04.549:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@35e2d654{/test,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test.war-_test-any-6279588879522983394.dir/webapp/,AVAILABLE}{/test.war}
2017-09-20 16:23:04.646:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=12ms
2017-09-20 16:23:04.649:WARN::main: test-jndi webapp is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:04.697:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@561b6512{/test-jndi,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-jndi.war-_test-jndi-any-6023636263414992288.dir/webapp/,AVAILABLE}{/test-jndi.war}
2017-09-20 16:23:04.770:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=40ms
2017-09-20 16:23:05.036:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@2beee7ff{/proxy,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-javadoc-proxy.war-_javadoc-proxy-any-2758874759195597975.dir/webapp/,AVAILABLE}{/javadoc-proxy.war}
2017-09-20 16:23:05.072:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=16ms
2017-09-20 16:23:05.074:WARN::main: test-jaas webapp is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:05.098:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@506ae4d4{/test-jaas,file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-jaas.war-_test-jaas-any-8067423971450448377.dir/webapp/,AVAILABLE}{/test-jaas.war}
2017-09-20 16:23:05.182:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=37ms
2017-09-20 16:23:05.184:WARN::main: test-spec webapp is deployed. DO NOT USE IN PRODUCTION!
2017-09-20 16:23:05.243:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@45099dd3{/test-spec,[file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-1205866915335004234.dir/webapp/, jar:file:///private/var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/jetty-0.0.0.0-8080-test-spec.war-_test-spec-any-1205866915335004234.dir/webapp/WEB-INF/lib/test-web-fragment-{VERSION}.jar!/META-INF/resources],AVAILABLE}{/test-spec.war}
2017-09-20 16:23:05.247:INFO:oejsh.ContextHandler:main: Started o.e.j.s.h.MovedContextHandler@3e08ff24{/oldContextPath,null,AVAILABLE}
2017-09-20 16:23:05.274:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=18ms
2017-09-20 16:23:05.296:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@5ddeb7cb{/,file:///installs/repository/jetty/demo-base/webapps/ROOT/,AVAILABLE}{/ROOT}
2017-09-20 16:23:05.326:INFO:oeja.AnnotationConfiguration:main: Scanning elapsed time=21ms
2017-09-20 16:23:05.352:INFO:oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@6b695b06{/doc,file:///installs/repository/jetty/demo-base/webapps/doc/,AVAILABLE}{/doc}
2017-09-20 16:23:05.370:INFO:oejs.AbstractConnector:main: Started ServerConnector@28cda624{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-09-20 16:23:05.380:INFO:oejus.SslContextFactory:main: x509=X509@126253fd(jetty,h=[jetty.eclipse.org],w=[]) for SslContextFactory@57db2b13(file:///installs/repository/jetty/demo-base/etc/keystore,file:///installs/repository/jetty/demo-base/etc/keystore)
2017-09-20 16:23:05.381:INFO:oejus.SslContextFactory:main: x509=X509@475c9c31(mykey,h=[],w=[]) for SslContextFactory@57db2b13(file:///installs/repository/jetty/demo-base/etc/keystore,ffile:///installs/repository/jetty/demo-base/etc/keystore)
2017-09-20 16:23:05.523:INFO:oejs.AbstractConnector:main: Started ServerConnector@53f3bdbd{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-09-20 16:23:05.524:INFO:oejs.Server:main: Started @2390ms
----
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]
The demonstration web applications are not necessarily secure and should *not* be deployed in production web servers.
____
You can see the configuration of the `demo-base` by using the following commands:
[source, screen, subs="{sub-order}"]
----
> 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.

20
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/introduction/chapter.adoc
View File

@ -1,20 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[introduction]]
== Introducing Jetty
include::what-is-jetty.adoc[]
include::what-version.adoc[]
include::jetty-javaee.adoc[]
include::jetty-coordinates.adoc[]

56
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/introduction/jetty-coordinates.adoc
View File

@ -1,56 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-jetty-coordinates]]
=== Finding Jetty in Maven
_____
[IMPORTANT]
It is important that only stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are not suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
_____
==== Maven Coordinates
Jetty has existed in Maven Central almost since its inception, though the coordinates have changed over the years.
When Jetty was based at SourceForge and then The Codehaus it was located under the `groupId` of `org.mortbay.jetty`.
With Jetty 7 the project moved to the Eclipse foundation and to a new `groupId` at that time to reflect its new home.
The top level Project Object Model (POM) for the Jetty project is located under the following coordinates.
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-project</artifactId>
<version>${project.version}</version>
</dependency>
----
==== Changelogs in Maven Central
The changes between versions of Jetty are tracked in a file called VERSIONS.txt, which is under source control and is generated on release.
Those generated files are also uploaded into Maven Central during the release of the top level POM. You can find them as a classifier marked artifact.
https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-project/
[source, xml, subs="{sub-order}"]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-project</artifactId>
<version>${project.version}</version>
<classifier>version</classifier>
<type>txt</type>
</dependency>
----

104
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/introduction/jetty-javaee.adoc
View File

@ -1,104 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[jetty-javaee]]
=== Jetty and Java EE Web Profile
Jetty implements aspects of the Java EE specification, primarily the Servlet Specification.
Recent releases of the Java EE platform have introduced a Web Profile, recognizing that many developers need only a subset of the many technologies under the Java EE umbrella.
While Jetty itself does not ship all of the Web Profile technologies, Jetty architecture is such that you can plug in third party implementations to produce a container customized to your exact needs.
[[jetty-javaee-7]]
==== Java EE 7 Web Profile
In the forthcoming Java EE-7 specification, the Web Profile reflects updates in its component specifications and adds some new ones:
.JavaEE7 Web Profile
[cols=",,,",options="header",]
|=======================================================================
|JSR |Name |Included with jetty-9.1.x |Pluggable
|http://jcp.org/en/jsr/detail?id=340[JSR 340] |Servlet Specification API 3.1 |Yes |
|http://jcp.org/en/jsr/detail?id=344[JSR 344] |Java Server Faces 2.2 (JSF) |No |Yes, https://javaserverfaces.java.net/[Mojarra] or http://myfaces.apache.org/[MyFaces]
|http://jcp.org/en/jsr/detail?id=245[JSR 245] / http://jcp.org/en/jsr/detail?id=341[JSR 341] |Java Server Pages 2.3/Java Expression Language 3.0 (JSP/EL) |Yes |Yes
|http://jcp.org/en/jsr/detail?id=52[JSR 52] |Java Standard Tag Library 1.2 (JSTL) |Yes |Yes
|http://jcp.org/en/jsr/detail?id=45[JSR 45] |Debugging Support for Other Languages 1.0 |Yes (via JSP) |Yes (via JSP)
|http://jcp.org/en/jsr/detail?id=346[JSR 346] |Contexts and Dependency Injection for the JavaEE Platform 1.1 (Web Beans) |No |Yes, http://seamframework.org/Weld[Weld]
|http://jcp.org/en/jsr/detail?id=330[JSR 330] |Dependency Injection for Java 1.0 |No |Yes as part of a CDI implementation, http://seamframework.org/Weld[Weld]
|http://jcp.org/en/jsr/detail?id=316[JSR 316] |Managed Beans 1.0 |No |Yes, as part of another technology
|http://jcp.org/en/jsr/detail?id=345[JSR 345] |Enterprise JavaBeans 3.2 Lite |No |
|http://jcp.org/en/jsr/detail?id=338[JSR 338] |Java Persistence 2.1 (JPA) |No |Yes, eg http://www.hibernate.org/[Hibernate]
|http://jcp.org/en/jsr/detail?id=250[JSR 250] |Common Annotations for the Java Platform 1.2 |Yes |Partially (for non-core Servlet Spec annotations)
|http://jcp.org/en/jsr/detail?id=907[JSR 907] |Java Transaction API 1.2 (JTA) |Yes |Yes
|http://jcp.org/en/jsr/detail?id=349[JSR 349] |Bean Validation 1.1 |No |Yes as part of another technology eg JSF, or a stand-alone implementation such as http://www.hibernate.org/subprojects/validator/docs.html[Hiberate
Validator]
|http://jcp.org/en/jsr/detail?id=339[JSR 339] |Java API for RESTful Web Services 2.0 (JAX-RS) |No |
|http://jcp.org/en/jsr/detail?id=356[JSR 356] |Java API for Websocket 1.0 |Yes |No
|http://jcp.org/en/jsr/detail?id=353[JSR 353] |Java API for JSON Processing 1.0 (JSON-P) |No |Yes, eg JSON-P https://java.net/projects/jsonp/[reference implementation]
|http://jcp.org/en/jsr/detail?id=318[JSR 318] |Interceptors 1.2 |No |Yes as part of a CDI implementation
|=======================================================================
[[jetty-javaee-6]]
==== Jetty EE 6 Web Profile
Here is the matrix of JSRs for Java EE 6 Web Profile, and how they relate to Jetty:
.Java EE 6 Web Profile
[cols=",,,",options="header",]
|=======================================================================
|JSR |Name |Included with jetty-9.0.x |Pluggable
|http://jcp.org/en/jsr/detail?id=315[JSR 315] |Servlet Specification API 3.0 |Yes |
|http://jcp.org/en/jsr/detail?id=314[JSR 314] |JavaServer Faces 2.0 (JSF) |No |Yes, for example, https://javaserverfaces.java.net/[Mojarra] or http://myfaces.apache.org/[MyFaces]
|http://jcp.org/en/jsr/detail?id=245[JSR 245] |JavaServer Pages 2.2/Java Expression Language 2.2 (JSP/EL) |Yes |Yes
|http://jcp.org/en/jsr/detail?id=52[JSR 52] |Java Standard Tag Library 1.2 (JSTL) |Yes |Yes
|http://jcp.org/en/jsr/detail?id=45[JSR 45] |Debugging Support for Other Languages 1.0 |Yes (via JSP) |Yes (via JSP)
|http://jcp.org/en/jsr/detail?id=299[JSR 299] |Contexts and Dependency Injection for the Java EE Platform 1.0 (Web Beans) |No |Yes, http://seamframework.org/Weld[Weld] or http://openwebbeans.apache.org/[OpenWebBeans]
|http://jcp.org/en/jsr/detail?id=330[JSR 330] |Dependency Injection for Java 1.0 |No |Yes as part of a CDI implementation, http://seamframework.org/Weld[Weld]
|http://jcp.org/en/jsr/detail?id=316[JSR 316] |Managed Beans 1.0 |No |Yes, as part of another technology.
|http://jcp.org/en/jsr/detail?id=318[JSR 318] |Enterprise JavaBeans 3.1 |No |Yes, OpenEJB
|http://jcp.org/en/jsr/detail?id=317[JSR 317] |Java Persistence 2.0 (JPA) |No |Yes, http://www.hibernate.org/[Hibernate]
|http://jcp.org/en/jsr/detail?id=250[JSR 250] |Common Annotations for the Java Platform |Yes |Partially (for non-core Servlet Spec annotations)
|http://jcp.org/en/jsr/detail?id=907[JSR 907] |Java Transaction API (JTA) |Yes |Implementations are pluggable, such as http://www.atomikos.com/[Atomikos], http://jotm.ow2.org/[JOTM], http://jencks.codehaus.org/Transaction+Manager[Jencks (Geronimo Transaction Manager)]
|http://jcp.org/en/jsr/detail?id=303[JSR 303] |Bean Validation 1.0 |No |Yes as part of another technology (JSF), or a stand-alone implementation such as http://www.hibernate.org/subprojects/validator/docs.html[Hiberate
Validator]
|=======================================================================

36
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/introduction/what-is-jetty.adoc
View File

@ -1,36 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[what-is-jetty]]
=== What is Jetty?
Eclipse Jetty is an open-source project providing an HTTP server, HTTP client, and Servlet container.
The Jetty documentation is broken up in to four parts:
* The link:{GSTARTEDGUIDE}[Getting Started Guide] emphasizes beginning to use Jetty.
It provides information about what Jetty is and where you can download it, and where to find Jetty in repositories like Central Maven.
It also provides a Quick Start guide on how to get Jetty up and running as well as an overview of how and what to configure in Jetty.
* The link:{OPGUIDE}[Operations Guide] details configuring Jetty as a distributed package at a more granular level.
From server startup to session management, logging, HTTP/2 support and Jetty optimization, these chapters will help administrators get the most out of their distributed Jetty server instances.
This section also covers configuring many of the most common servlet container features such as JNDI and JMX.
* Aimed at advanced users of Jetty, the link:{PROGGUIDE}[Programming Guide] focuses on Jetty development.
A large portion of this section is focused on using Jetty as an embedded server in existing applications.
It contains several examples and how-to guides for making the most out of the Jetty framework.
This section also includes a guide on using the Jetty Maven plugin as well as information on debugging Jetty.
* The link:#{CONTRIBGUIDE}[Contribution Guide] is aimed at those who want to contribute to the Jetty open source project.
It includes instructions on interacting with the community, how to raise bugs, and how to report security issues.
In addition, it also details source control and build information for the project.

50
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/introduction/what-version.adoc
View File

@ -1,50 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[what-jetty-version]]
=== What Version Do I Use?
Jetty 10 and 11 are the most recent versions of Jetty and has a great many improvements over previous versions.
This documentation which focuses on Jetty 10.
While many people continue to use older versions of Jetty, we generally recommend using Jetty 10 or 11 (more on the differences later) as they represent the version of Jetty that we will actively maintain and improve over the next few years.
_____
[IMPORTANT]
It is important that only stable releases are used in production environments.
Versions that have been deprecated or are released as Milestones (M) or Release Candidates (RC) are not suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
_____
.Jetty Versions
[width="100%",cols="12%,9%,15%,6%,21%,10%,6%,21%",options="header",]
|=======================================================================
|Version |Year |Home |Min JVM |Protocols |Servlet |JSP |Status
|11 |2020- |Eclipse |11 ^(2)^ |HTTP/1.1 (RFC 7230), HTTP/2 (RFC 7540), WebSocket (RFC 6455, JSR 356), FastCGI, *JakartaEE Namespace*^(1)^ |5.0.0 |3.0.0 |Stable
|10 |2019- |Eclipse |11 ^(2)^ |HTTP/1.1 (RFC 7230), HTTP/2 (RFC 7540), WebSocket (RFC 6455, JSR 356), FastCGI |4.0.1 |2.2 |Stable
|9.4 |2016- |Eclipse |1.8 |HTTP/1.1 (RFC 7230), HTTP/2 (RFC 7540), WebSocket (RFC 6455, JSR 356), FastCGI |3.1 |2.3 |Stable
|9.3 |2015- |Eclipse |1.8 ^(3)^ |HTTP/1.1 (RFC 7230), HTTP/2 (RFC 7540), WebSocket (RFC 6455, JSR 356), FastCGI |3.1 |2.3 |Deprecated / *End of Life December 2020*
|9.2 |2014-2018 |Eclipse |1.7 ^(3)^ |HTTP/1.1 RFC2616, javax.websocket, SPDY v3 |3.1 |2.3 |Deprecated / *End of Life January 2018*
|9.1 |2013-2014 |Eclipse |1.7 ^(3)^ |HTTP/1.1 RFC2616 |3.1 |2.3 |Deprecated / *End of Life May 2014*
|9.0 |2013-2013 |Eclipse |1.7 ^(3)^ |HTTP/1.1 RFC2616 |3.1-beta |2.3 |Deprecated / *End of Life November 2013*
|8 |2009-2014 |Eclipse/Codehaus |1.6 ^(3)^ |HTTP/1.1 RFC2616, WebSocket RFC 6455, SPDY v3 |3.0 |2.2 |Deprecated / *End of Life November 2014*
|7 |2008-2014 |Eclipse/Codehaus |1.5 |HTTP/1.1 RFC2616, WebSocket RFC 6455, SPDY v3 |2.5 |2.1 |Deprecated / *End of Life November 2014*
|6 |2006-2010 |Codehaus |1.4-1.5 |HTTP/1.1 RFC2616 |2.5 |2.0 |Deprecated / *End of Life November 2010*
|5 |2003-2009 |Sourceforge |1.2-1.5 |HTTP/1.1 RFC2616 |2.4 |2.0 |Antique
|4 |2001-2006 |Sourceforge |1.2, J2ME |HTTP/1.1 RFC2616 |2.3 |1.2 |Ancient
|3 |1999-2002 |Sourceforge |1.2 |HTTP/1.1 RFC2068 |2.2 |1.1 |Fossilized
|2 |1998-2000 |Mortbay |1.1 |HTTP/1.0 RFC1945 |2.1 |1.0 |Legendary
|1 |1995-1998 |Mortbay |1.0 |HTTP/1.0 RFC1945 |- |- |Mythical
|=======================================================================
1. Due to Oracle's ownership of the "Java" trademark, usage of the javax.* namespace has been restricted and the jakarta.* namespace link:https://www.eclipse.org/lists/jakartaee-platform-dev/msg00029.html[was adopted] by the Eclipse Foundation.
2. JPMS module support is optional
3. JDK9 and newer is not supported if using MultiRelease JAR Files, or Bytecode / Annotation scanning.

17
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/upgrading/chapter.adoc
View File

@ -1,17 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[upgrading-jetty]]
== Upgrading Jetty
include::upgrading-from-jetty-9.adoc[]

20
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/upgrading/sample.adoc
View File

@ -1,20 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
= Sample Title
This is a sample paragraph.
== Sample Subsection
More sample text.

257
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/upgrading/upgrading-9.3-to-9.4.adoc
View File

@ -1,257 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
=== Upgrading from Jetty 9.3.x to Jetty 9.4.0
The purpose of this guide is to assist users migrating from Jetty 9.3.x to 9.4.0.
It is not comprehensive, but covers many of the major changes included in the release that may prove as problem areas for users.
==== The jetty.sh Script
The file `jetty.sh`, typically used to start Jetty as a service in Linux/Unix machines underwent only small changes, such as the addition of https://wiki.debian.org/LSBInitScripts[LSB tags].
You can safely replace the `jetty.sh` file packaged with Jetty 9.3 with the version found in Jetty 9.4.
==== Removed Classes
`ConcurrentArrayQueue` was removed from use in Jetty 9.3 and the class has been removed entirely as part of Jetty 9.4.
==== Module Changes in Jetty 9.4
[cols="1,1", options="header"]
|===
| Jetty 9.3 Module | Jetty 9.4 Module
| `logging` | `console-capture`
| `infinispan` | `session-store-infinispan-embedded` or `session-store-infinispan-remote`
| `jdbc-sessions` | `session-store-jdbc`
| `gcloud-memcached-sessions`, `gcloud-session-idmgr` and `gcloud-sessions` | `session-store-gcloud` and `session-store-cache`
| `nosql` | `session-store-mongo`
|===
===== Logging Modules
The module `logging` is no longer available in Jetty 9.4.
The logging module structure present in Jetty 9.3 has been replaced with a more fine-grained structure in Jetty 9.4, so that you have now more choices available that are also easier to configure.
The migration path is different depending on whether you have completely customized this module or not.
If you have a Jetty 9.3 installation, and you have both `$jetty.base/modules/logging.mod` and `$jetty.base/etc/jetty-logging.xml`, then this module is local to your `$jetty.base` setup and will be used by Jetty 9.4 as before.
No changes are required for your implementation.
If either `$jetty.base/modules/logging.mod` or `$jetty.base/etc/jetty-logging.xml` are missing, then you were relying on those present in `$jetty.home`, which were present in Jetty 9.3, but are no longer available in Jetty 9.4.
The Jetty 9.3 `logging` module has been renamed to `console-capture` in Jetty 9.4.
You need to open your Jetty 9.3 `start.ini` and replace the references to the `logging` modules with `console-capture`.
For example, in an existing Jetty 9.3 `start.ini` file the module declaration for logging would look like this:
[source, screen, subs="{sub-order}"]
----
--module=logging
jetty.logging.retainDays=7
----
In 9.4, it should be replaced by:
[source, screen, subs="{sub-order}"]
----
--module=console-capture
jetty.console-capture.retainDays=7
----
The properties that may be present in your Jetty 9.3's `start.ini`, such as `jetty.logging.retainDays` will still be working in Jetty 9.4, but a warning will be printed at Jetty 9.4 startup, saying to replace them with correspondent `jetty.console-capture.*` properties such as `jetty.console-capture.retainDays`.
==== Session Management
Session management received a significant overhaul in Jetty 9.4.
Session functionality has been refactored to promote code-reuse, easier configuration and easier customization.
Whereas previously users needed to edit xml configuration files, in Jetty 9.4 all session behavior is controlled by properties that are exposed by the various session modules.
Users now configure session management by selecting a composition of session modules.
===== Change Overview
SessionIdManager:: Previously there was a different class of SessionIdManager - with different configuration options - depending upon which type of clustering technology chosen.
In Jetty 9.4, there is only one type, the link:{JDURL}/org/eclipse/jetty/server/session/DefaultSessionIdManager.html[org.eclipse.jetty.server.session.DefaultSessionIdManager].
SessionManager:: Previously, there was a different class of SessionManager depending upon which the type of clustering technology chosen.
In Jetty 9.4 we have removed the SessionManager class and split its functionality into different, more easily extensible and composable classes:
General setters:::
All of the common setup of sessions such as the maxInactiveInterval and session cookie-related configuration has been moved to the link:{JDURL}/org/eclipse/jetty/server/session/SessionHandler.html[org.eclipse.jetty.server.session.SessionHandler]
[cols="1,1", options="header"]
|===
| 9.3 SessionManager | 9.4 SessionHandler
| `setMaxInactiveInterval(sec)` | `setMaxInactiveInterval(sec)`
| `setSessionCookie(String)` | `setSessionCookie(String)`
| `setRefreshCookieAge(sec)` | `setRefreshCookieAge(sec)`
| `setSecureRequestOnly(boolean)` | `setSecureRequestOnly(boolean)`
| `setSessionIdPathParameterName(String)` | `setSessionIdPathParameterName(String)`
| `setSessionTrackingModes(Set<SessionTrackingMode>)` | `setSessionTrackingModes(Set<SessionTrackingMode>)`
| `setHttpOnly(boolean)` | `setHttpOnly(boolean)`
| `setUsingCookies(boolean)` | `setUsingCookies(boolean)`
| `setCheckingRemoteSessionIdEncoding(boolean)` | `setCheckingRemoteSessionIdEncoding(boolean)`
|===
Persistence:::
In Jetty 9.3 `SessionManagers` (and sometimes `SessionIdManagers`) implemented the persistence mechanism.
In Jetty 9.4 we have moved this functionality into the link:{JDURL}/org/eclipse/jetty/server/session/SessionDataStore.html[`org.eclipse.jetty.server.session.SessionDataStore`].
Session cache:::
In Jetty 9.3 the `SessionManager` held a map of session objects in memory.
In Jetty 9.4 this has been moved into the new link:{JDURL}/org/eclipse/jetty/server/session/SessionCache.html[`org.eclipse.jetty.server.session.SessionCache`] interface.
For more information, please refer to the documentation on link:#jetty-sessions-architecture[Jetty Session Architecture.]
===== Default Sessions
As with earlier versions of Jetty, if you do not explicitly configure any session modules, the default session infrastructure will be enabled.
In previous versions of Jetty this was referred to as "hash" session management.
The new default provides similar features to the old hash session management:
* A session scavenger thread that runs every 10mins and removes expired sessions
* A session id manager that generates unique session ids and handles session id sharing during context forwarding
* An in-memory cache of session objects.
Requests for the same session in the same context share the same session object.
Session objects remain in the cache until they expire or are explicitly invalidated.
If you wish to configure the default setup further, enable the `session-cache-hash` module.
*Compatibility*
As Session objects do not persist beyond a server restart, there are no compatibility issues.
===== Sessions using the Filesystem
In earlier versions of Jetty, persisting sessions to the local filesystem was an option of the "hash" session manager.
In Jetty 9.4 this has been refactored to its own configurable module `session-store-file`.
*Compatibility*
Sessions stored to files by earlier versions of jetty are not compatible with jetty-9.4 sessions.
Here is a comparison of file formats, note that the file contents are listed in order of file output:
[cols="1,1", options="header"]
|===
| Jetty 9.3 | Jetty 9.4
| File name: `sessionid` | File name: `expirytime_contextpath_vhost_sessionid`
| `sessionid (utf)` | `sessionid (utf)`
| | `contextpath (utf)`
| | `vhost (utf)`
| `nodeid (utf)` | `lastnode (utf)`
| `createtime (long)` | `createtime (long)`
| `accessed (long)` | `accessed (long)`
| | `lastaccessed (long)`
| | `cookiesettime (long)`
| | `expiry (long)`
| `requests (int)` |
| | `maxInactive (long)`
| `attributes size (int)` | `attributes size (int)`
| `attributes serialized (obj)` | `attributes serialized (obj)`
| `maxInactive (long)` |
|===
____
[NOTE]
Session data is now only loaded when requested.
Previous functionality such as `setLazyLoad` has been removed.
____
===== JDBC Sessions
As with earlier versions of Jetty, sessions may be persisted to a relational database.
Enable the `session-store-jdbc` module.
*Compatibility*
Sessions stored to the database by earlier versions of jetty are not compatible with jetty-9.4 sessions.
The incompatibility is minor: in jetty-9.4 the `rowid` primary key column is no longer used, and the primary key is a composite of `(sessionid,contextpath,vhost)` columns.
===== NoSQL Sessions
As with earlier versions of Jetty, sessions may be persisted to a document database.
Jetty supports the Mongo document database.
Enable the `session-store-mongo` module.
*Compatibility*
Sessions stored to mongo by earlier versions of jetty are not compatible with jetty-9.4 sessions.
The key for each subdocument that represents the session information for a context is different between jetty-9.3 and 9.4:
[cols="1,1", options="header"]
|===
| Jetty 9.3 | Jetty 9.4
|Each context key is: vhost+context+path, where empty vhosts="::" and root context = "*" and / is replaced by _
|Each context key is: vhost:contextpath, where empty vhosts="0_0_0_0" and root context = "" and / replaced by _
| eg "::/contextA" | eg " 0_0_0_0:_contextA"
|===
===== Infinispan Sessions
As with earlier versions of Jetty, sessions may be clustered via Infinispan to either an in-process or remote infinispan instance.
Enable the `session-store-infinispan` module.
*Compatibility*
Sessions stored in infinispan by jetty-9.3 are incompatible with jetty-9.4.
In Jetty 9.3 the serialized object stored to represent the session data was `org.eclipse.jetty.session.infinispan.SerializableSessionData`.
In Jetty 9.4 the serialized object is `org.eclipse.jetty.serer.session.SessionData`.
===== GCloud Datastore
As with earlier versions of Jetty, sessions may be persisted to Google's GCloud Datastore.
Enable the `session-store-gcloud` module.
*Compatibility*
Sessions stored into GCloud Datastore by Jetty 9.3 are *incompatible* with Jetty 9.4, although the incompatibility is trivial: the name of the session id entity property has changed:
[cols="1,1", options="header"]
|===
|Jetty 9.3 | Jetty 9.4
|Kind: `GCloudSession` | Kind: `GCloudSession`
|key: `contextpath_vhost_sessionid` | key: `contextpath_vhost_sessionid`
|*"clusterId"*: `sessionId` | *"id"*: `sessionId`
|"contextPath" : `contextpath` | "contextPath": `contextpath`
|"vhost" : `vhost` | "vhost": `vhost`
|"accessed": `accesstime` | "accessed": `accesstime`
|"lastAccessed": `lastaccesstime` | "lastAccessed": `lastaccesstime`
|"createTime": `createtime` | "createTime": `createtime`
|"cookieSetTime": `cookiesettime` | "cookieSetTime": `cookiesettime`
|"lastNode": `lastnode` | "lastNode": `lastnode`
|"expiry": `expiry` | "expiry": `expiry`
|"maxInactive": `maxInactive` | "maxInactive": `maxInactive`
|"attributes": `blob` | "attributes": `blob`
|===
===== GCloud Datastore with Memcached
As with earlier versions of Jetty, sessions can be both persisted to Google's GCloud Datastore, and cached into Memcached for faster access.
Enable the `session-store-gcloud` and `session-store-cache` modules.
*Compatibility*
Sessions stored into Memcached by earlier versions of jetty are incompatible with Jetty 9.4.
Previous versions of jetty stored `org.eclipse.jetty.gcloud.memcached.session.SerializableSessionData` whereas Jetty 9.4 stores `org.eclipse.jetty.server.session.SessionData`.
==== ServletContainerInitializers
As of Jetty-9.4.4, unless the `web.xml` is version 3.0 or greater, only `ServletContainerInitializers` that are on the container classpath will be discovered.
Users wishing to use `ServletContainerInitializers` from within the webapp with older versions of `web.xml` must either upgrade their `web.xml` version, or call `WebAppContext.setConfigurationDiscovered(true)` either programmatically or in xml.
Upgrading the `web.xml` version is preferable.

58
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/upgrading/upgrading-9.4-to.10.0.adoc
View File

@ -1,58 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
=== Upgrading from Jetty 9.4.x to Jetty 10.0.x
The purpose of this guide is to assist users migrating from Jetty 9.4 to 10.
It is not comprehensive, but covers many of the major changes included in the release that may prove as problem areas for users.
==== Required Java Version
Jetty 10 requires, at a minimum, Java 11 to function.
Items such as the Java Platform Module System (JPMS), which Jetty 10 supports, are not available in earlier versions of Java.
==== ServletContainerInitializers
As of Jetty 10, Annotations will be discovered even for old versions of `web.xml` (2.5).
Users wishing not to use annotations from the webapp classpath with older versions of `web.xml` must call `WebAppContext.setConfigurationDiscovered(false)` either programmatically or in xml.
==== Removed Classes
//TODO - Insert major removed/refactored classes from Jetty-9.x.x to Jetty-10.0.x
==== Changes to Websocket
//TODO - List of changes to Websocket -- Joakim/Lachlan
==== `javax.mail` and `javax.transaction`
Both `javax.mail` and `javax.transaction` have been removed from the Jetty Distribution in Jetty 10.
If you require these jars, you will need to enable the `ext` link:#startup-modules[module] and copy the files to your `$JETTY_BASE/lib/ext` directory.
==== Module Changes in Jetty 10.0
===== New Modules in Jetty 10.0
//TODO - Insert new modules introduced in Jetty 10
===== Changes to Existing Modules in Jetty 10.0
//TODO - Insert module changes introduced in Jetty 10
==== Changes to Sessions
//TODO - List of changes to Sessions -- Jan
==== Removal of System Properties(?)
//TODO - List of removed System bits --- Greg

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/Jetty_DeployManager_AppLifeCycle-1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 64 KiB

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/Jetty_DeployManager_DeploymentManager_Roles.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/SessionsHierarchy.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 50 KiB

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/basic-architecture-handlers.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 54 KiB

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/images/basic-architecture-nested-handlers.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

Some files were not shown because too many files have changed in this diff Show More