4.5 Using the Apache Portable Runtime (APR)

The Apache Portable Runtime (APR) is a set of libraries and APIs that map directly to your underlying operating system. tc Runtime can use APR to provide additional scalability and performance because of high-quality integration with native server technologies. APR provides access to advanced IO functionality (such as sendfile, epoll and OpenSSL), OS level functionality (random number generation, system status, etc.), and native process handling (shared memory, NT pipes and Unix sockets).

The APR libraries are automatically installed in most Unix platforms, although you need to compile the Java Native Interface (JNI) wrappers. For other platforms, such as Windows, you must download and install the libraries. See Apache Portable Runtime (APR) Native Library for Tomcat.

Add the APR libraries to the LD_LIBRARY_PATH (Unix) or PATH (Windows) environment variable used by the tc Runtime process so that tc Runtime can access the libraries when it runs.

The following sample server.xml file shows how to configure tc Runtime to use APR. The file builds on the simple out-of-the-box configuration described in Simple tc Runtime Configuration.

See Comparing the APR-Enabled server.xml File with Out-of-the-Box server.xml for information about how the two files differ.

<?xml version='1.0' encoding='utf-8'?>
<Server port="-1" shutdown="SHUTDOWN">

  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JasperListener" />
  <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="conf/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">

    <Executor name="tomcatThreadPool" namePrefix="tomcat-http--" maxThreads="300" minSpareThreads="50"/>

    <Connector
               executor="tomcatThreadPool"
               port="8080"
               protocol="org.apache.coyote.http11.Http11AprProtocol"
               connectionTimeout="20000"
               redirectPort="8443"
               acceptCount="100"
               maxKeepAliveRequests="15"/>

    <Connector
               executor="tomcatThreadPool"
               port="8443"
               protocol="org.apache.coyote.http11.Http11AprProtocol"
               connectionTimeout="20000"
               redirectPort="8443"
               acceptCount="100"
               maxKeepAliveRequests="15"
               SSLCertificateFile="${catalina.base}/conf/tcserver.crt"
               SSLCertificateKeyFile="${catalina.base}/conf/tcserver.key"
               SSLPassword="changeme"
               SSLEnabled="true"
               scheme="https"
               secure="true"/>


    <Engine name="Catalina" defaultHost="localhost">

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase"/>

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true" deployOnStartup="true" deployXML="true"
            xmlValidation="false" xmlNamespaceAware="false">
      </Host>
    </Engine>
  </Service>
</Server>

Comparing the APR-Enabled server.xml File with Out-of-the-Box server.xml

In the preceding sample server.xml, most of the configuration is the same as the non-APR enabled server.xml file except for the following:

  • The preceding server.xml file includes an additional APR-specific listener, implemented by the org.apache.catalina.core.AprLifecycleListener class. The SSLEngine="on" attribute enables the native SSL engine, rather than the JSEE engine provided by the JDK.

  • The protocol="org.apache.coyote.http11.Http11AprProtocol" attribute of the <Connector> elements specify that the two HTTP connectors (with and without SSL enabled) both use the native HTTP protocol implementation.

See Configuring SSL for details about configuring the native SSL connector.

For complete documentation about the tc Runtime server.xml file and all the possible XML elements you can include, see Apache Tomcat Configuration Reference.