http-listener (Sun GlassFish Enterprise Server v3 Prelude Administration Reference)

Sun GlassFish Enterprise Server v3 Prelude Administration Reference

http-listener

Defines an HTTP listen socket. The connection-pool subelement of the parent http-service element also configures some listen socket settings.

When you first install the Enterprise Server, three http-listener elements exist by default, with id values of admin-listener, http-listener1, and http-listener2. The http-listener2, which is set up with SSL, is disabled by default.

Superelements

http-service

Subelements

The following table describes subelements for the http-listener element.

Table 1–29 http-listener Subelements


Element	Required	Description
ssl	zero or one	Defines Secure Socket Layer (SSL) parameters.
property	zero or more	Specifies a property or a variable.

Attributes

The following table describes attributes for the http-listener element.

Table 1–30 http-listener Attributes


Attribute	Default	Description
`id`	none	The unique listener name. An `http-listener` name cannot begin with a number.
`address`	none	IP address of the listener. Can be in dotted-pair or IPv6 notation. Can be `any` (for `INADDR_ANY`) to listen on all IP addresses. Can be a hostname.
`port`	none	Port number on which the listener listens. Legal values are `1` - `65535`. On UNIX, creating sockets that listen on ports `1` - `1024` requires superuser privileges. Configuring an SSL listener to listen on port 443 is standard.
`external-port`	none	(optional) Specifies the external port on which the connection is made.
`family`		(optional) Deprecated. Do not use.
`blocking-enabled`	`false`	(optional) If `true`, uses a blocking socket for servicing a request.
`acceptor-threads`	`1`	(optional) Specifies the number of processors in the machine. To set the number of request processing threads, use the `thread-count` attribute of the request-processing element.
`security-enabled`	`false`	(optional) Determines whether the listener runs SSL. To turn SSL2 or SSL3 on or off and set ciphers, use an `ssl` subelement.
`default-virtual-server`	none	References the `id` attribute of the default virtual-server for this particular listener.
`server-name`	none	Tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates; it doesn’t affect the URLs for directories and files stored in the server. If your server uses an alias, the `server-name` should be the alias name. If a colon and port number are appended, that port is used in URLs the server sends to the client. If load balancing is enabled, use the server name of the load balancer.
`redirect-port`	none	(optional) If the listener is supporting non-SSL requests and a request is received for which a matching `<security-constraint>` requires SSL transport, the request is automatically redirected to the port number specified here. If load balancing is enabled, use the redirect port of the load balancer.
`xpowered-by`	`true`	(optional) If true, `X-Powered-By` headers are used according to the Servlet 2.4 and JSP 2.0 specifications.
`enabled`	`true`	(optional) Determines whether the listener is active. If set to `false`, any attempts to connect to the listener result in a socket exception (`java.net.ConnectException`). In Enterprise Server versions prior to 9.1, a listener whose `enabled` attribute was set to `false` returned a 404 response code for any requests sent to it. To achieve this behavior in the current Enterprise Server version, set the listener's `enabled` attribute to `true`, and set every associated virtual server's state to `off`. A virtual-server lists its associated listeners in its `http-listeners` attribute.

Properties

The following table describes properties for the http-listener element. Any of these properties can be defined as an http-service property, so that it applies to all http-listener elements.

Table 1–31 http-listener Properties


Property	Default	Description
`recycle-objects`	`true`	If `true`, recycles internal objects instead of using the VM garbage collector.
`reader-threads`	`0`	Specifies the number of reader threads, which read bytes from the non-blocking socket.
`acceptor-queue-length`	`4096`	Specifies the length of the acceptor thread queue. Once full, connections are rejected.
`reader-queue-length`	`4096`	Specifies the length of the reader thread queue. Once full, connections are rejected.
`use-nio-direct-bytebuffer`	`true`	If `true`, specifies that the NIO direct `ByteBuffer` is used. In a limited resource environment, it might be faster to use non-direct Java's `ByteBuffer` by setting a value of `false`.
`authPassthroughEnabled`	`false`	If `true`, indicates that this `http-listener` element receives traffic from an SSL-terminating proxy server. Overrides the `authPassthroughEnabled` property of the parent http-service element.
`proxyHandler`	`com.sun.enterprise.web.ProxyHandlerImpl`	Specifies the fully qualified class name of a custom implementation of the `com.sun.appserv.ProxyHandler` abstract class that this `http-listener` uses. Only used if the `authPassthroughEnabled` property of this `http-listener` and the parent http-service element are both set to `true`. Overrides the `proxyHandler` property of the parent `http-service` element.
`proxiedProtocol`	none	Specifies a comma-separated list of protocols that can use the same port. Allowed values are `ws/tcp` (SOAP over TCP), `http`, `https` and `tls`. For example, if you set this property to `http,https` and set the `port` to `4567`, you can access the port with either `http://host:4567/` or `https://host:4567/`. Specifying this property at the http-service level overrides settings at the `http-listener` level. If this property is not set at either level, this feature is disabled.
`bufferSize`	`4096`	Specifies the size, in bytes, of the buffer to be provided for input streams created by HTTP listeners.
`connectionTimeout`	`30`	Specifies the number of seconds HTTP listeners wait, after accepting a connection, for the request URI line to be presented.
`maxKeepAliveRequests`	`250`	Specifies the maximum number of HTTP requests that can be pipelined until the connection is closed by the server. Set this property to `1` to disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining.
`traceEnabled`	`true`	If `true`, enables the TRACE operation. Set this property to `false` to make the Enterprise Server less susceptible to cross-site scripting attacks.
`cometSupport`	`false`	If `true`, enables Comet support for this listener. If your servlet or JSP page uses Comet technology, make sure it is initialized when the Enterprise Server starts up by adding the `load-on-startup` element to your `web.xml` file. For example: <servlet> <servlet-name>CheckIn</servlet-name> <servlet-class>CheckInServlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet>
`jkEnabled`	`false`	If `true`, enables `mod_jk` support for this listener.
`compression`	`off`	Specifies use of HTTP/1.1 GZIP compression to save server bandwidth. Allowed values are: `off` – Disables compression. `on` – Compresses data. `force` – Forces data compression in all cases. positive integer – Specifies the minimum amount of data required before the output is compressed. If the `content-length` is not known, the output is compressed only if compression is set to `on` or `force`.
`compressableMimeType`	`text/html,text/xml,text/plain`	Specifies a comma-separated list of MIME types for which HTTP compression is used.
`noCompressionUserAgents`	empty `String` (`regexp` matching disabled)	Specifies a comma-separated list of regular expressions matching user-agents of HTTP clients for which compression should not be used.
`minCompressionSize` or `compressionMinSize`	none	Specifies the minimum size of a file when compression is applied.
`crlFile`	none	Specifies the location of the Certificate Revocation List (CRL) file to consult during SSL client authentication. This can be an absolute or relative file path. If relative, it is resolved against `domain-dir`. If unspecified, CRL checking is disabled.
`trustAlgorithm`	none	Specifies the name of the trust management algorithm (for example, `PKIX`) to use for certification path validation.
`trustMaxCertLength`	`5`	Specifies the maximum number of non-self-issued intermediate certificates that can exist in a certification path. This property is considered only if `trustAlgorithm` is set to `PKIX`. A value of zero implies that the path can only contain a single certificate. A value of `-1` implies that the path length is unconstrained (there is no maximum). Setting a value less than `-1` causes an exception to be thrown.
`disableUploadTimeout`	`true`	if `false`, the connection for a servlet that reads bytes slowly is closed after the `connectionUploadTimeout` is reached.
`connectionUploadTimeout`	`5`	Specifies the timeout for uploads. Applicable only if `disableUploadTimeout` is set to `false`.
`uriEncoding`	`UTF-8`	Specifies the character set used to decode the request URIs received on this HTTP listener. Must be a valid IANA character set name. Overrides the `uriEncoding` property of the parent http-service element.