Specification of environment.xml

The purpose of the environment.xml file is to configure environmental or Server Application wide settings. Currently this means being able to set the security policy and configure logging settings. A sample environment.xml follows. Previously thread pool settings were also configured in this section but this has been deprecated. Note that previously the information stored in environment.xml was stored in a file named server.xml.

<?xml version="1.0"?>

<environment>

    <logs>
      <category name="" target="default" priority="DEBUG" />
      <category name="myAuthorizer" target="myAuthorizer-target"
                priority="DEBUG" />

      <log-target name="default"
                  location="/logs/default.log" />
      <log-target name="myAuthorizer-target"
                  location="/logs/authorizer.log" />
    </logs>

    <policy>
      <keystore name="foo-keystore"
                location="sar:/conf/keystore"
                type="JKS" />

      <grant code-base="file:${app.home}${/}some-dir${/}*"
              key-store="foo-keystore" >
        <permission class="java.io.FilePermission"
                    target="${/}tmp${/}*"
                    action="read,write" />
      </grant>

      <grant signed-by="Bob"
             code-base="sar:/SAR-INF/lib/*"
             key-store="foo-keystore" >
        <permission class="java.io.FilePermission"
                    target="${/}tmp${/}*"
                    action="read,write" />
      </grant>
    </policy>

</environment>

      

The format of the policy section should be largely self evident if the assembler has experience with standard policy files. It should be noted that if no policy section is given then the Server Application runs at full permissions. The evaluation of properties occurs in a similar manner to standard policy file property expansion. There are a number of extra properties that will be evaluated. These include; app.home and app.name.

One special thing to not is that the user can use URLs of the form, "sar:/SAR-INF/lib/*". This will apply the permissions to the jars contained in the .SAR file. Note that these urls must start with "sar:/" and must use the "/" character as file separator, regardless of current operating system.

The logs section can currently have two types of elements; log-targets which represent destinations for logging and categorys. There must be a log-target with the name "default". Categories are hierarchial in nature, have a priority and are associated with one or more log-targets. See the logging documentation for a further description of this section.

There is another type of log configuration. It is more configurable. Specify version attribute with logs elements. See javadoc of org.apache.avalon.excalibur.logger package for detailed description. Below is example configuration.

<?xml version="1.0"?>
<environment>
  <logs version="1.1">
    <factories>
      <factory type="file" class="org.apache.avalon.excalibur.logger.factory.FileTargetFactory"/>
    </factories>

    <categories>
      <category name="" log-level="INFO">
        <log-target id-ref="default"/>
      </category>
    </categories>

    <targets>
      <file id="default">
        <filename>${app.home}/logs/default-</filename>
        <append>true</append>
        <rotation type="unique" pattern="yyyyMMdd" suffix=".log">
          <date>yyyyMMdd</date>
        </rotation>
      </file>
    </targets>
  </logs>
</environment>