From 1ca86ed01c5c0ad1e8f751b090acc5fcba8b71a6 Mon Sep 17 00:00:00 2001 From: Steve Loughran Date: Fri, 13 Apr 2007 15:24:35 +0000 Subject: [PATCH] now I understand how proxies work under Java 5 git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@528522 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/proxy.html | 138 ++++++++++++++++++++++++++++++++++------- 1 file changed, 117 insertions(+), 21 deletions(-) diff --git a/docs/manual/proxy.html b/docs/manual/proxy.html index df9365887..1a87037b4 100644 --- a/docs/manual/proxy.html +++ b/docs/manual/proxy.html @@ -32,7 +32,7 @@ Consult your IDE documentation for IDE-specific information upon proxy setup.

-All tasks running in Ant's JVM share the same HTTP/FTP/Socks +All tasks and threads running in Ant's JVM share the same HTTP/FTP/Socks proxy configuration.

@@ -71,33 +71,66 @@ proxy configuration.

This property maybe enough to give command-line Ant builds network access, although in practise the results - are somewhat disappointing. + are inconsistent.

- We are not entirely sure where it reads the property settings from. - For windows, it probably reads the appropriate bits of the registry. For - Unix/Linux it may use the current Gnome2 settings. - + It is has also been reported a breaking the IBM Java 5 JRE on AIX, + and does not always work on Linux (presumably due to missing gconf settings) + Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients. +

+

- One limitation of this feature, other than requiring a 1.5+ JVM, - is that it is not dynamic. A long-lasting build hosted on a laptop will - not adapt to changes in proxy settings. + To make the -autoproxy option the default, add it to the environment variable + ANT_ARGS, which contains a list of arguments to pass to Ant on every + command line run.

+

How Autoproxy works

+

+We are grateful for some input from Sun as to how the proxy code works under +Java 1.5 and up. The java.net.useSystemProxies is checked only +once, at startup time, the other checks (registry, gconf, system properties) are done +dynamically whenever needed (socket connection, URL connection etc..). +

+
Windows

- It is has also been reported a breaking the IBM Java 5 JRE on AIX, - and does not appear to work reliably on Linux. - Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients. +The JVM goes straight to the registry, bypassing WinInet, as it is not +present/consistent on all supported Windows platforms (it is part of IE, +really). Java 7 may use the Windows APIs on the platforms when it is present.

+
Linux
+

- To make the -autproxy option the default, add it to the environment variable - ANT_ARGS, which contains a list of arguments to pass to Ant on every - command line run. +The JVM uses the gconf library to look at specific entries. +The GConf-2 settings used are: +

+
+ - /system/http_proxy/use_http_proxy            boolean
+ - /system/http_proxy/use_authentication        boolean
+ - /system/http_proxy/host                      string
+ - /system/http_proxy/authentication_user       string
+ - /system/http_proxy/authentication_password   string
+ - /system/http_proxy/port                      int
+ - /system/proxy/socks_host                     string
+ - /system/proxy/mode                           string
+ - /system/proxy/ftp_host                       string
+ - /system/proxy/secure_host                    string
+ - /system/proxy/socks_port                     int
+ - /system/proxy/ftp_port                       int
+ - /system/proxy/secure_port                    int
+ - /system/proxy/no_proxy_for                   list
+ - /system/proxy/gopher_host                    string
+ - /system/proxy/gopher_port                    int
+
+

+If you are using KDE or another GUI than Gnome, you can still use the +gconf-editor tool to add these entries.

-

JVM options

+ +

Manual JVM options

Any JVM can have its proxy options explicitly configured by passing the appropriate -D system property options to the runtime. @@ -116,8 +149,13 @@ proxy configuration. setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"

- For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer" - properties dialog box. +If you insert this line into the Ant shell script itself, it gets picked up +by all continuous integration tools running on the system that call Ant via the +command line. +

+

+ For Windows, set the ANT_OPTS environment variable in the appropriate "My Computer" + properties dialog box (winXP), "Computer" properties (Vista)

This mechanism works across Java versions, is cross-platform and reliable. @@ -133,6 +171,7 @@ proxy configuration.

  • Not dynamic enough to deal with laptop configuration changes.
    • +

    SetProxy Task

    The setproxy task can be used to @@ -174,16 +213,73 @@ proxy configuration. </target> +

    Custom ProxySelector implementations

    +

    + As Java lets developers write their own ProxySelector implementations, it + is theoretically possible for someone to write their own proxy selector class that uses + different policies to determine proxy settings. There is no explicit support + for this in Ant, and it has not, to the team's knowledge, been attempted. +

    +

    + This could be the most flexible of solutions, as one could easily imagine + an Ant-specific proxy selector that was driven off ant properties, rather + than system properties. Developers could set proxy options in their + custom build.properties files, and have this propagate. +

    +

    + One issue here is with concurrency: the default proxy selector is per-JVM, + not per-thread, and so the proxy settings will apply to all sockets opened + on all threads; we also have the problem of how to propagate options from + one build to the JVM-wide selector. +

    + +

    Configuring the Proxy settings of Java programs under Ant

    + +

    + Any program that is executed with <java> without setting + fork="true" will pick up the Ant's settings. If you need + different values, set fork="false" and provide the values + in <sysproperty> elements. +

    + If you wish to have + a forked process pick up the Ant's settings, use the + <syspropertyset> + element to propagate the normal proxy settings. The following propertyset + is a datatype which can be referenced in a <java> task to + pass down the current values. + +

    +
    +<propertyset id="proxy.properties">
+  <propertyref prefix="java.net.useSystemProxies"/>
+  <propertyref prefix="http."/>
+  <propertyref prefix="https."/>
+  <propertyref prefix="ftp."/>
+  <propertyref prefix="socksProxy"/>
+</propertyset>
+
    +

    Summary and conclusions

    -There are three ways to set up proxies in Ant. +There are four ways to set up proxies in Ant.

      -
    1. With Ant1.7 using the -autoproxy parameter.
      2. +
    2. With Ant1.7 and Java 1.5+ using the -autoproxy parameter.
    3. Via JVM system properties -set these in the ANT_ARGS environment variable.
    4. Via the <setproxy> task.
      5. +
    5. Custom ProxySelector implementations
    - +

    +Proxy settings are automatically shared with Java programs started under Ant +that are not forked; to pass proxy settings down to subsidiary programs, use +a propertyset. +

    +

    +Over time, we expect the Java 5+ proxy features to stabilize, and for Java code +to adapt to them. However, given the fact that it currently does break some +builds, it will be some time before Ant enables the automatic proxy feature by +default. Until then, you have to enable the -autoproxy option or +use one of the alternate mechanisms to configure the JVM.

    Further reading