diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/proxy.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/proxy.html | 292 |
1 files changed, 0 insertions, 292 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/proxy.html b/framework/src/ant/apache-ant-1.9.6/manual/proxy.html deleted file mode 100644 index 13ef6e8e..00000000 --- a/framework/src/ant/apache-ant-1.9.6/manual/proxy.html +++ /dev/null @@ -1,292 +0,0 @@ -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<html> - -<head> -<meta http-equiv="Content-Language" content="en-us"> -<link rel="stylesheet" type="text/css" href="stylesheets/style.css"> -<title>Proxy Configuration</title> -</head> - -<body> -<h2>Proxy Configuration</h2> - -<p> -This page discussing proxy issues on command-line Apache Ant. -Consult your IDE documentation for IDE-specific information upon proxy setup. -</p> - -<p> - -All tasks and threads running in Ant's JVM share the same HTTP/FTP/Socks -proxy configuration. -</p> - -<p> - When any task tries to retrieve content from an HTTP page, including the - <code><get></code> task, any automated URL retrieval in - an XML/XSL task, or any third-party task that uses the <code>java.net.URL</code> - classes, the proxy settings may make the difference between success and failure. -</p> -<p> - Anyone authoring a build file behind a blocking firewall will immediately appreciate - the problems and may want to write a build file to deal with the problem, but - users of third party build build files may find that the build file itself - does not work behind the firewall. -</p> -<p> - This is a long standing problem with Java and Ant. The only way to fix - it is to explicitly configure Ant with the proxy settings, either - by passing down the proxy details as JVM properties, or to - tell Ant on a Java1.5+ system to have the JVM work it out for itself. - -</p> - - - -<h3>Java1.5+ proxy support (new for Ant1.7)</h3> -<p> - When Ant starts up, if the <code>-autoproxy</code> - command is supplied, Ant sets the - <code>java.net.useSystemProxies</code> system property. This tells - a Java1.5+ JVM to use the current set of property settings of the host - environment. Other JVMs, such as the Kaffe and Apache Harmony runtimes, - may also use this property in future. - It is ignored on the Java1.4 and earlier runtimes. -</p> -<p> - This property maybe enough to give command-line Ant - builds network access, although in practise the results - are inconsistent. -</p> -<p> - 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> - 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> -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> -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> -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>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. - Ant can be configured through all its shell scripts via the - <code>ANT_OPTS</code> environment variable, which is a list of options to - supply to Ant's JVM: -</p> -<p> - For bash: -</p> -<pre> - export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" -</pre> - For csh/tcsh: -<pre> - setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" -</pre> -<p> -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. - Once set, all build files run via the command line will automatically have - their proxy setup correctly, without needing any build file changes. It also - apparently overrides Ant's automatic proxy settings options. -</p> -<p> - It is limited in the following ways: -</p> - <ol> - <li>Does not work under IDEs. These need their own proxy settings changed</li> - <li>Not dynamic enough to deal with laptop configuration changes.</li> - </ol> - - -<h3>SetProxy Task</h3> -<p> - The <a href="Tasks/setproxy.html">setproxy task</a> can be used to - explicitly set a proxy in a build file. This manipulates the many proxy - configuration properties of a JVM, and controls the proxy settings for all - network operations in the same JVM from that moment. -</p> -<p> - If you have a build file that is only to be used in-house, behind a firewall, on - an older JVM, <i>and you cannot change Ant's JVM proxy settings</i>, then - this is your best option. It is ugly and brittle, because the build file now contains - system configuration information. It is also hard to get this right across - the many possible proxy options of different users (none, HTTP, SOCKS). -</p> - - -<p> - Note that proxy configurations set with this task will probably override - any set by other mechanisms. It can also be used with fancy tricks to - only set a proxy if the proxy is considered reachable: -</p> - -<pre> - <target name="probe-proxy" depends="init"> - <condition property="proxy.enabled"> - <and> - <isset property="proxy.host"/> - <isreachable host="${proxy.host}"/> - </and> - </condition> - </target> - - <target name="proxy" depends="probe-proxy" if="proxy.enabled"> - <property name="proxy.port" value="80"/> - <property name="proxy.user" value=""/> - <property name="proxy.pass" value=""/> - <setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}" - proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/> - </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="Types/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 four ways to set up proxies in Ant. -</p> -<ol> -<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> - -<ul> -<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html"> -Java Networking Properties</a>. -</li> -</ul> - -</body> -</html> |