Once in a while I get questions about whether Apache Tomcat implements a way to include other files in server.xml, Tomcat’s main configuration file.  The answer is that there is a way to do it, and that Tomcat didn’t have to implement a new feature for it to work.  The way to do it is: XML entity includes.

XML is a featureful and flexible data file format, and one thing that makes it helpful is that the XML parsers can be generic (think non-custom code), and because they can be generic, many different software projects can use the same parser code.  If the parser code can be shared, then all the features added to the parser can be available to all of the software projects that use the parser.  A great example of this is: it is common for us to want to include an additional file into a configuration file, so someone along the way added entity includes to the XML standard, then the XML parsers implemented it.  Tomcat got it “for free”.

Here’s how to include a file in your Tomcat’s server.xml.  Edit your server.xml, and at the very top of the file, right after any <?xml> declaration line (that’s optional), put the following DOCTYPE declaration to define a file entity:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE server-xml [
  <!ENTITY connector1-config SYSTEM "connector1-config.xml">
]>

This markup means that this document’s name is “server-xml”, and we’re defining a new entity named “connector1-config” which the XML parser can find in a file named “connector1-config.xml”.  You can name your entities anything you want, as long as the parser accepts the characters you use.  I suggest just using alpha-numeric characters and dash, to keep it simple.  It turns out that if you don’t specify an absolute path to the file, the parser will look for the file in the same directory as the file that includes it, so the parser will look in Tomcat’s conf/ directory.

But, we haven’t yet used the connector XML entity we defined at the top of server.xml.  At the point in the file where we want the parser to insert the connector’s XML, we need only to write “@connector1-config;” like this:

<Server ...>
    <Service ...>
 
        <!-- See conf/connector1-config.xml for this connector's config. -->
        &connector1-config;
 
    </Service>
</Server>

Then, in your connector1-config.xml file put the following XML snippet:

    <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 8089 -->
    <Connector port="8089" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />

Using this include mechanism, you may include any file that resides in the same directory as Tomcat’s server.xml file.

If, instead, you want to include a file in another directory, where your Tomcat JVM user has read permission to the file, you can specify an absolute path when you define the entity, like this:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE server-xml [
  <!ENTITY connector1-config SYSTEM "file:///opt/myproject/connector1-config.xml">
]>

You use this entity the same way, just by placing “&connector1-config;” wherever you want the XML snippet included.

Filed under: Tomcat / Tcat Server | Social tagging: Agile > configuration > howto > server.xml > tomcat tip