private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
Table of Contents
This chapter discusses various options for configuring Jetty connectors.
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.
Jetty primarily uses a single connector type called 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 only a selector-based non blocking I/O connector, and a collection of
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:
that accepts HTTP connections (that may be upgraded to WebSocket connections).
that accepts SSL/TLS connections. The
ConnectionFactory configured after the SSL one is a HTTP
ConnectionFactories, and therefore the SSL/TLS connections will carry the HTTP protocol.
that accepts SSL connections that carry either HTTP or SPDY traffic.
Initially the SSL connection is chained to a Next Protocol Negotiation
(NPN) connection, which eventually replaces itself with a connection
for a protocol it negotiates with the client; this protocol may be a
version of SPDY or HTTP. If the client does not support NPN, HTTP is
Typically you need to configure very little on connectors other than
set the listening port (see Network
Settings), and perhaps enable
X-Forwarded-For customization (see
Configuration). Most other settings are for expert configuration
The services a
instance uses are set by constructor injection and once
instantiated cannot be changed. Most 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
), you can do this with:
You can see the other arguments that can be passed when
ServerConnector in the Javadoc.
Typically the defaults are sufficient for almost all deployments.
You 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:
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
element to be customizable:
The network settings that you can set on the
Table 6.1. Connector Configuration
|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
|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
|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 TIME_WAIT. For servers it is typically OK to leave this as the default true.|
|soLingerTime||A value >=0 set the socket SO_LINGER value in milliseconds. Jetty attempts to gently close all TCP/IP connections with proper half close semantics, so a linger timeout should not be required and thus the default is -1.|
class holds the configuration for
s, which you can create 1:1 with each HTTP connection or 1:n
on a multiplexed SPDY connection. Thus a
object is injected into both the HTTP and SPDY connection factories. To
avoid duplicate configuration, the standard Jetty distribution creates
HttpConfiguration instance in
, which is a
Ref element then used in
A typical configuration of HttpConfiguration is:
For SSL based connectors (in
jetty-spdy.xml), the common "httpConfig" instance is used as
the basis to create an SSL specific configuration with ID
This adds a
which adds SSL Session IDs and certificate information as request
The SSL/TLS connectors for HTTPS and SPDY require a certificate to
establish a secure connection. Jetty holds certificates in standard JVM
keystores and are configured as keystore and truststores on a
instance that is injected into an
instance. An example using the keystore distributed with Jetty
(containing a self signed test certificate) is in
. Read more about SSL keystores in Configuring SSL.
It is the
ConnectionFactory instances injected into a
ServerConnector that create the protocol handling
Connection instances for the network endpoints the connector accepts.
Thus the different instances of connectors in a Jetty setup vary mostly
in the configuration of the factories for the protocols they support.
Other than selecting which factories to use, there is typically very
little factory configuration required other than injecting the
The simplest example in the Jetty distribution is
Here the connector has only a single
ConnectionFactory, and when a new connection is accepted,
it is the
HttpConnectionFactory that creates an
A more complex example involving multiple connection factories is
In this case five connection factories are created and linked together by their protocol names:
The default protocol is identified by the first connection factory,
which in this case is a
instantiated with "npn" as the next protocol. Thus accepted
endpoints are associated with an
instance that is chained to an
instance created by the "npn" connection factory.
This is the
chained to the
SslConnectionFactory. The NPN connections
negotiate with the client for the next protocol and then a factory
of that name is looked up to create a connection to replace the
NPN connection. If NPN is not supported, the defaultProtocol is
configured as "http/1.1".
The factory NPN connections use if SPDY version 3 is negotiated.
The factory NPN connections use if SPDY version 2 is negotiated.
The factory NPN connections use if HTTP version 1.1 is negotiated or if NPN is not supported. Note that HTTP/1.1 can also handle HTTP/1.0.