Eclipse Jetty Documentation

The Eclipse Jetty Project provides server-side libraries designed to programmatically configure and start an HTTP or WebSocket server from a main class, or to embed the server directly into an existing application.

Common use cases include:

• Exposing REST endpoints via an HTTP server.
• Building proxy applications that process and forward HTTP requests (often used in conjunction with Jetty client libraries).
• Creating generic network servers that interpret custom protocols beyond HTTP.
• Embedding WebSocket servers.

The Eclipse Jetty Project provides non-blocking client-side libraries that support both synchronous and asynchronous APIs. These libraries can be embedded in applications to interact with third-party services (like REST), act as proxies (e.g., converting HTTP/1.1 to HTTP/2 or HTTP/3), or handle WebSocket events.

Available libraries include:

• High-Level HTTP Client Library: Supports HTTP/1.1, HTTP/2, HTTP/3, and FastCGI.
• Low-Level HTTP/2 Client Library: For low-level HTTP/2 protocol operations.
• Low-Level HTTP/3 Client Library: For low-level HTTP/3 protocol operations.
• WebSocket Client Library: For receiving events from WebSocket servers.

The deployment process relies on two main components:

• Deployer: (Default: org.eclipse.jetty.deploy.StandardDeployer) Responsible for adding/removing ContextHandler instances from the Handler tree and managing their lifecycle (starting/stopping).
• DeploymentScanner: Scans directories for web application files or directories (e.g., *.war, *.properties, *.xml). It triggers the Deployer when files are added, updated, or removed.

Web applications are deployed into an Environment, which provides shared environmental properties and a specific ClassLoader.

Jetty applications are built as a tree of components. In a server application, the root is typically a Server instance; in a client application, the root is an HttpClient instance.

This tree structure provides several benefits:

• JMX Integration: Components can be registered as JMX MBeans to monitor internal state.
• Component Dumps: The entire tree and its internal states can be dumped to logs or the console for troubleshooting.

Best Practice: Use the component tree for long-lived or medium-lived components (e.g., thread pools, web application contexts). Avoid adding short-lived objects like HTTP requests or TCP connections to the tree for performance reasons. Instead, use a long-lived container to manage them and handle their JMX/dump requirements via internal data structures.

Jetty components are organized using a hierarchical structure based on the LifeCycle interface and ContainerLifeCycle containers.

• LifeCycle: An interface implemented by components that can be started and stopped. Components implementing this interface participate in the container's lifecycle management.
• Bean: A component instance added to a ContainerLifeCycle container. Beans fall into three categories:
  • Managed: Lifecycle is tied to the container.
  • Unmanaged: Independent lifecycle.
  • POJO: Plain objects without a lifecycle.
• ContainerLifeCycle: A LifeCycle implementation that can contain other beans. It manages the lifecycle of its managed beans, starting and stopping them in unison with the container.

Jetty's I/O library (both client and server) is built on Java NIO to provide a completely non-blocking architecture.

Key components include:

• SelectorManager: Manages one or more ManagedSelector instances, which wrap Java NIO Selectors to manage SelectionKeys and SelectableChannels (like SocketChannel).
• EndPoint: An abstraction for a SocketChannel or DatagramChannel. It provides non-blocking APIs for reading, writing, and closing channels.
• Connection: An abstraction responsible for reading bytes from an EndPoint and deserializing them into protocol-specific objects (e.g., HTTP/1.1 requests, WebSocket frames).

EndPoint and Connection pairs can be chained, which is useful for protocols like TLS where one layer handles decryption and the next handles protocol deserialization.

The Jetty start mechanism is invoked by executing $JETTY_HOME/start.jar from within a $JETTY_BASE directory. It operates in two primary modes:

• Tool mode: Used as a command-line tool to configure the $JETTY_BASE directory (enabling modules, creating files, downloading dependencies, etc.). The JVM performs the command and then exits.
• Start mode: Used to start the JVM that runs Jetty with the specified configuration. The JVM stays running until stopped (e.g., via Ctrl+C).

$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar ...

Jetty's standalone server architecture is built on three core concepts:

1. Jetty Module System: Provides specific features (e.g., HTTP, WebSocket, HTTP/2) by assembling Java components in a declarative way via configuration files.
2. $JETTY_BASE Directory: The location where you configure which modules are enabled and define their specific properties for your environment.
3. Jetty Start Mechanism: The process that starts a JVM, reads the configuration in $JETTY_BASE, and assembles/starts the required Jetty components.

Requests arrive via protocol connectors (like HTTP/1.1 or HTTP/2) and are forwarded to the appropriate deployed web application based on their URI.