[FrontPage] [TitleIndex] [WordIndex

deegree3 proxy configuration

Status: draft

This page discusses the configuration of proxy parameters in deegree3 services and applications.

1. Identified goals

2. Intended approach

The Java VM respects a set of system properties (proxyHost, proxyPort, etc.) that allows network-related classes (e.g. java.net.URLConnection) to connect through a proxy:

2.1. General concept

The obvious approach is to ultimately rely on the Java VM system properties to configure the proxy settings for deegree3. This ensures that we can rely on the correct behaviour of the standard java.net classes, such as java.net.URLConnection. This is especially important as we depend on third-party libraries (such as Xerces for XML schema processing) that make network accesses using these classes themselves. If the system properties are set up correctly, then these components should always behave correctly in a proxy environment (although this needs to be tested in each case).

In order to make the proxy configuration more comfortable and easily accessible to users, it should be possible to change the system properties without the need to setup the system's environment variables manually. These is especially useful when a deegree3 service is deployed in a servlet container that is administered by a third party: in this case it's not always feasible to change the environment variables in the startup script of the container (or globally for the machine).

Technically, there should be a class org.deegree.commons.utils.ProxyUtils with methods for setting up the proxy configuration and other proxy related tasks (e.g. logging the current proxy configuration).

2.2. Known limitations / caveats

3. Configuration format

If the settings are not performed using environment variables (which of course is also possible), deegree3 provides an easy mechanism for setting up the proxy from an XML snippet:

<ProxyConfiguration xmlns="http://www.deegree.org/commons" overrideSystemSettings="true">

Here's the schema fragment that documents all possible options:

<xs:element name="ProxyConfiguration">
      <xs:documentation>Parameters that deegree uses to connect to
          other resources on the network.</xs:documentation>
      <xs:element name="ProxyHost" type="xs:string" minOccurs="0"/>
      <xs:element name="HttpProxyHost" type="xs:string" minOccurs="0"/>
      <xs:element name="FtpProxyHost" type="xs:string" minOccurs="0"/>
      <xs:element name="ProxyPort" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="HttpProxyPort" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="FtpProxyPort" type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="ProxyUser" type="xs:string" minOccurs="0"/>
      <xs:element name="HttpProxyUser" type="xs:string" minOccurs="0"/>
      <xs:element name="FtpProxyUser" type="xs:string" minOccurs="0"/>
      <xs:element name="ProxyPassword" type="xs:string" minOccurs="0"/>
      <xs:element name="HttpProxyPassword" type="xs:string" minOccurs="0"/>
      <xs:element name="FtpProxyPassword" type="xs:string" minOccurs="0"/>
      <xs:element name="NonProxyHosts" type="xs:string" minOccurs="0"/>
      <xs:element name="HttpNonProxyHosts" type="xs:string" minOccurs="0"/>
      <xs:element name="FtpNonProxyHosts" type="xs:string" minOccurs="0"/>
    <xs:attribute name="overrideSystemSettings" type="xs:boolean" use="optional"/>

Note that each settings is available in three flavours, just as in the VM's system properties, e.g. for ProxyHost:

4. Integration with service configuration

In order to minimize the number of configuration files that have to be edited by a user, the ProxyConfiguration element could be integrated into the main configuration file of the OGCWebServiceConfiguration.

5. Integration with standalone applications

For standalone applications, the setting of the environment variable is generally more feasible (e.g. in a starter script). Additionally, applications may choose to initialize the settings using the same xml element (either integrated the application configuration or as a separate file). Therefore, the following code can be used:

Integrated into XML configuration of application (ProxyConfiguration is a JAXB bean):

   ProxyConfiguration proxyConfig = appConfig.getProxyConfiguration();
   ProxyUtils.setupProxyParameters( proxyConfig );

From separate file:

    ProxyUtils.setupProxyParameters (fileName);


2018-04-20 12:05