You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by st...@apache.org on 2007/04/13 17:24:37 UTC
svn commit: r528522 - /ant/core/trunk/docs/manual/proxy.html
Author: stevel
Date: Fri Apr 13 08:24:35 2007
New Revision: 528522
URL: http://svn.apache.org/viewvc?view=rev&rev=528522
Log:
now I understand how proxies work under Java 5
Modified:
ant/core/trunk/docs/manual/proxy.html
Modified: ant/core/trunk/docs/manual/proxy.html
URL: http://svn.apache.org/viewvc/ant/core/trunk/docs/manual/proxy.html?view=diff&rev=528522&r1=528521&r2=528522
==============================================================================
--- ant/core/trunk/docs/manual/proxy.html (original)
+++ ant/core/trunk/docs/manual/proxy.html Fri Apr 13 08:24:35 2007
@@ -32,7 +32,7 @@
<p>
-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.
</p>
@@ -71,33 +71,66 @@
<p>
This property maybe enough to give command-line Ant
builds network access, although in practise the results
- are somewhat disappointing.
+ are inconsistent.
</p>
<p>
- 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.
+</p>
+
<p>
- 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 <code>-autoproxy</code> option the default, add it to the environment variable
+ <code>ANT_ARGS</code>, which contains a list of arguments to pass to Ant on every
+ command line run.
</p>
+<h4>How Autoproxy works</h4>
+<p>
+We are grateful for some input from Sun as to how the proxy code works under
+Java 1.5 and up. The <code>java.net.useSystemProxies</code> is checked only
+once, at startup time, the other checks (registry, gconf, system properties) are done
+dynamically whenever needed (socket connection, URL connection etc..).
+</p>
+<h5>Windows</h5>
<p>
- 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.
</p>
+<h5>Linux</h5>
+
<p>
- To make the <code>-autproxy</code> option the default, add it to the environment variable
- <code>ANT_ARGS</code>, 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:
+</p>
+<pre>
+ - /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
+</pre>
+<p>
+If you are using KDE or another GUI than Gnome, you can still use the
+<code>gconf-editor</code> tool to add these entries.
</p>
-<h3>JVM options</h3>
+
+<h3>Manual JVM options</h3>
<p>
Any JVM can have its proxy options explicitly configured by passing
the appropriate <code>-D</code> system property options to the runtime.
@@ -116,8 +149,13 @@
setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
</pre>
<p>
- 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.
+</p>
+<p>
+ For Windows, set the <code>ANT_OPTS</code> environment variable in the appropriate "My Computer"
+ properties dialog box (winXP), "Computer" properties (Vista)
</p>
<p>
This mechanism works across Java versions, is cross-platform and reliable.
@@ -133,6 +171,7 @@
<li>Not dynamic enough to deal with laptop configuration changes.</li>
</ol>
+
<h3>SetProxy Task</h3>
<p>
The <a href="OptionalTasks/setproxy.html">setproxy task</a> can be used to
@@ -174,16 +213,73 @@
</target>
</pre>
+<h3>Custom ProxySelector implementations</h3>
+<p>
+ 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.
+</p>
+<p>
+ 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.
+</p>
+<p>
+ 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.
+</p>
+
+<h3>Configuring the Proxy settings of Java programs under Ant</h3>
+
+<p>
+ Any program that is executed with <code><java></code> without setting
+ <code>fork="true"</code> will pick up the Ant's settings. If you need
+ different values, set <code>fork="false"</code> and provide the values
+ in <code><sysproperty></code> elements.
+</p>
+ If you wish to have
+ a forked process pick up the Ant's settings, use the
+ <a href="CoreTypes/propertyset.html"><code><syspropertyset></code></a>
+ element to propagate the normal proxy settings. The following propertyset
+ is a datatype which can be referenced in a <code><java></code> task to
+ pass down the current values.
+
+</p>
+<pre>
+<propertyset id="proxy.properties">
+ <propertyref prefix="java.net.useSystemProxies"/>
+ <propertyref prefix="http."/>
+ <propertyref prefix="https."/>
+ <propertyref prefix="ftp."/>
+ <propertyref prefix="socksProxy"/>
+</propertyset>
+</pre>
+
<h3>Summary and conclusions</h3>
<p>
-There are three ways to set up proxies in Ant.
+There are four ways to set up proxies in Ant.
</p>
<ol>
-<li>With Ant1.7 using the <code>-autoproxy</code> parameter.</li>
+<li>With Ant1.7 and Java 1.5+ using the <code>-autoproxy</code> parameter.</li>
<li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
<li>Via the <setproxy> task.</li>
+<li>Custom ProxySelector implementations</li>
</ol>
-
+<p>
+Proxy settings are automatically shared with Java programs started under Ant <i>
+that are not forked</i>; to pass proxy settings down to subsidiary programs, use
+a propertyset.
+</p>
+<p>
+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 <code>-autoproxy</code> option or
+use one of the alternate mechanisms to configure the JVM.
<h4>Further reading</h4>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org