JBoss Web Server currently uses the Apache Tomcat 6.0 release and it is ships as service archive (SAR) application in the deploy folder. The location of the embedded web server has changed at almost every new release of JBoss. The following table could be a useful reference if you are using different versions of JBoss:

The main configuration file is server.xml which, by default, has the following minimal configuration:

<Server>
<Listener className="org.apache.catalina.core.AprLifecycleListener"
SSLEngine="on" />
<Listener className="org.apache.catalina.core.JasperListener" />
<Service name="jboss.web">
<Connector protocol="HTTP/1.1" port="8080"
address="${jboss.bind.address}"
connectionTimeout="20000" redirectPort="8443" />
<Connector protocol="AJP/1.3" port="8009"
address="${jboss.bind.address}"
redirectPort="8443" />
<Engine name="jboss.web" defaultHost="localhost">
<Realm className="org.jboss.web.tomcat.security.JBossWebRealm"
certificatePrincipal="org.jboss.security.
auth.certs.SubjectDNMapping" allRolesMode="authOnly" />
<Host name="localhost">
<Valve className="org.jboss.web.tomcat.service.
jca.CachedConnectionValve"
cachedConnectionManagerObjectName="jboss.
jca:service=CachedConnectionManager"
transactionManagerObjectName="jboss:
service=TransactionManager" />
</Host>
</Engine>
</Service>
</Server>

Following is a short description for the key elements of the configuration:

As you can see, all the elements are organized in a hierarchical structure where the Server element acts as top-level container:

The lowest elements in the configuration are Valve and Realm, which can be nested into Engine or Host elements to provide unique processing capabilities and role management.

Customizing connectors

Most of the time when you want to customize your web container, you will have to change some properties of the connector.

<Connector protocol="HTTP/1.1" port="8080"
address="${jboss.bind.address}"
connectionTimeout="20000" redirectPort="8443" />

A complete list of the connector properties can be found on the Jakarta Tomcat site (http://tomcat.apache.org/). Here, we'll discuss the most useful connector properties:

• port: The TCP port number on which this connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address.
• acceptCount: The maximum queue length for incoming connection requests, when all possible request processing threads are in use. Any requests received when the queue is full will be refused. The default value is 10.
• connectionTimeout: The number of milliseconds the connector will wait after accepting a connection for the request URI line to be presented. The default value is 60000 (that is, 60 seconds).
• address: For servers with more than one IP address, this attribute specifies which address will be used for listening on the specified port. By default, this port will be used on all IP addresses associated with the server.
• enableLookups: Set to true if you want to perform DNS lookups in order to return the actual hostname of the remote client and to false in order to skip the DNS lookup and return the IP address in string form instead (thereby improving performance). By default, DNS lookups are enabled.
• maxHttpHeaderSize: The maximum size of the request and response HTTP header, specified in bytes. If not specified, this attribute is set to 4096 (4 KB).
• maxPostSize: The maximum size in bytes of the POST, which will be handled by the container FORM URL parameter parsing. The limit can be disabled by setting this attribute to a value less than or equal to zero. If not specified, this attribute is set to 2097152 (2 megabytes).
• maxThreads: The maximum number of request processing threads to be created by this connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to 200.

The new Apache Portable Runtime connector

Apache Portable Runtime (APR) is a core Apache 2.x library designed to provide superior scalability, performance, and better integration with native server technologies.

The mission of the Apache Portable Runtime (APR) project is to create and maintain software libraries that provide a predictable and consistent interface to underlying platform-specific implementations. The primary goal is to provide an API to which software developers may code and be assured of predictable if not identical behaviour regardless of the platform on which their software is built, relieving them of the need to code special-case conditions to work around or take advantage of platform-specific deficiencies or features.

The high-level performance of the new APR connector is made possible by the introduction of socket pollers for persistent connections (keepalive). This increases the scalability of the server, and by using sendfile system calls, static content is delivered faster and with lower CPU utilization.

Once you have set up the APR connector, you are allowed to use the following additional properties in your connector:

• keepAliveTimeout: The number of milliseconds the APR connector will wait for another HTTP request, before closing the connection. If not set, this attribute will use the default value set for the connectionTimeout attribute.
• pollTime: The duration of a poll call; by default it is 2000 (5 ms). If you try to decrease this value, the connector will issue more poll calls, thus reducing latency of the connections. Be aware that this will put slightly more load on the CPU as well.
• pollerSize: The number of sockets that the poller kept alive connections can hold at a given time. The default value is 768, corresponding to 768 keepalive connections.
• useSendfile: Enables using kernel sendfile for sending certain static files. The default value is true.
• sendfileSize: The number of sockets that the poller thread dispatches for sending static files asynchronously. The default value is 1024.

If you want to consult the full documentation of APR, you can visit http://apr.apache.org/.

Installing the APR connector

In order to install the APR connector, you need to add some native libraries to your JBoss server. The native libraries can be found at http://www.jboss.org/jbossweb/downloads/jboss-native/.

Download the version that is appropriate for your OS. Once you are ready, you need to simply unzip the content of the archive into your JBOSS_HOME directory.

As an example, Unix users (such as HP users) would need to perform the following steps:

cd jboss-5.0.0.GA
tar tvfz jboss-native-2.0.6-hpux-parisc2-ssl.tar.gz

Now, restart JBoss and, from the console, verify that the connector is bound to Http11AprProtocol.

A word of caution!
At the time of writing, the APR library still has some open issues that prevent it from loading correctly on some platforms, particularly on the 32-bit Windows.

Please consult the JBoss Issue Tracker (https://jira.jboss.org/jira/secure/IssueNavigator.jspa?) to verify that there are no open issues for your platform.