+ +All tasks running in Ant's JVM share the same HTTP/FTP/Socks +proxy configuration. +
+ +
+ When any task tries to retrieve content from an HTTP page, including the
+ <get> task, any automated URL retrieval in
+ an XML/XSL task, or any third-party task that uses the java.net.URL
+ classes, the proxy settings may make the difference between success and failure.
+
+ 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. +
+
+ This is a longstanding problem with Java and Ant, which Java1.5 finally
+ addresses. When Ant is run under Java1.5, it automatically sets the
+ java.net.useSystemProxies system property, telling the JVM to
+ switch to the OS-configured proxy settings.This is automatic, but it can be disabled.
+
+ When running Ant on older JVMs, this property is ignored. There are two other + ways to configure Ant's proxy settings in these cases. +
+ + + +
+ When Ant starts up, it automatically sets the
+ java.net.useSystemProxies 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, which is why Ant always sets the
+ property -it is ignored on the Java1.4 and earlier runtimes.
+
+ This property should be enough to automatically give Ant hosted + builds network access. It may also work under an IDE, though that depends + upon the IDE and how it starts ant. If it bypasses Ant's Main entry point, + the proxy setup may be skipped, and if networking has already started up + by the time ant is run, the option may be ignored. Consult your IDE + documentation for IDE-specific information upon proxy setup. +
+
+ To disable this automatic feature, set the command line option
+ -noproxy, or set a JVM or Ant property
+ java.net.useSystemProxies to a value other than
+ true or on. If the JVM option is already set,
+ Ant will not touch it; if an Ant property of that name is set, Ant will
+ pass the value of that property down to the JVM.
+
+ 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. + +
+ The biggest 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. Furthermore, unless the user
+ is running an adaptive
+ laptop, the host's proxy settings will not-automatically adapt to
+ changes in network context. The -noproxy option may be a useful
+ one to use when roaming.
+
+ Any JVM can have its proxy options explicitly configured by passing
+ the appropriate -D system property options to the runtime.
+ Ant can be configured through all its shell scripts via the
+ ANT_OPTS environment variable, which is a list of options to
+ supply to Ant's JVM:
+
+ For bash: +
++ export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" ++ For csh/tcsh: +
+ setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080" ++
+ For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer" + properties dialog box. +
++ 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 ants automatic proxy settings options +
++ It is limited in the following ways: +
++ If you are using Ant on a pre-Java1.5 machine behind a firewall, this is + the simplest and best way to configure your runtime to work with build files + that go beyond the firewall. +
+ ++ The setproxy task 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. +
++ If you have a build file that is only to be used in-house, behind a firewall, on + an older JVM, and you cannot change Ant's JVM proxy settings, 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). +
+ + ++ 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: +
+ +
+ <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>
+
+
++There are three ways to set up proxies in Ant. +
+-noproxy to disable this.+As Java1.5 adoption increases, automatic proxy support should become more +widespread. For this reason, we would encourage users not to try and +second-guess network configurations with setproxy, and instead to encourage +users to move up to Ant1.7/Java1.5, and if they cannot, to set proxy options +in the ANT_ARGS environment variable. +
+ +null.
@@ -423,6 +429,8 @@ public class Main implements AntMain {
+ "\nThis can be caused by a version mismatch between "
+ "the ant script/.bat file and Ant itself.";
throw new BuildException(msg);
+ } else if (arg.equals("-noproxy")) {
+ proxy=false;
} else if (arg.startsWith("-")) {
// we don't have any more args to recognize!
String msg = "Unknown argument: " + arg;
@@ -627,6 +635,8 @@ public class Main implements AntMain {
}
}
+
+
project.init();
project.setUserProperty(MagicNames.ANT_VERSION, getAntVersion());
@@ -642,6 +652,11 @@ public class Main implements AntMain {
buildFile.getAbsolutePath());
project.setKeepGoingMode(keepGoingMode);
+ if (proxy) {
+ //proxy setup if enabled
+ ProxySetup proxySetup = new ProxySetup(project);
+ proxySetup.enableProxies();
+ }
ProjectHelper.configureProject(project, buildFile);
@@ -809,7 +824,8 @@ public class Main implements AntMain {
+ lSep);
msg.append(" -nouserlib Run ant without using the jar files from" + lSep
+ " ${user.home}/.ant/lib" + lSep);
- msg.append(" -noclasspath Run ant without using CLASSPATH");
+ msg.append(" -noclasspath Run ant without using CLASSPATH" + lSep);
+ msg.append(" -noproxy Java 1.5 only: do not use the OS proxies");
System.out.println(msg.toString());
}
diff --git a/src/main/org/apache/tools/ant/util/ProxySetup.java b/src/main/org/apache/tools/ant/util/ProxySetup.java
new file mode 100644
index 000000000..df690276e
--- /dev/null
+++ b/src/main/org/apache/tools/ant/util/ProxySetup.java
@@ -0,0 +1,81 @@
+/*
+ * Copyright 2005 The Apache Software Foundation
+ *
+ * Licensed 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.
+ *
+ */
+
+package org.apache.tools.ant.util;
+
+import org.apache.tools.ant.Project;
+
+/**
+ * Code to do proxy setup. This is just factored out of the main system just for
+ * @since Ant1.7
+ */
+
+public class ProxySetup {
+
+ private Project owner;
+
+ /**
+ * Java1.5 property that enables use of system proxies.
+ * @value
+ */
+ public static final String USE_SYSTEM_PROXIES="java.net.useSystemProxies";
+
+
+ /**
+ * create a proxy setup class bound to this project
+ * @param owner
+ */
+ public ProxySetup(Project owner) {
+ this.owner = owner;
+ }
+
+ /**
+ * Get the current system property settings
+ * @return current value; null for none or no access
+ */
+ public static String getSystemProxySetting() {
+ try {
+ return System.getProperty(USE_SYSTEM_PROXIES);
+ } catch (SecurityException e) {
+ //if you cannot read it, you wont be able to write it either
+ return null;
+ }
+ }
+
+ /**
+ * turn proxies on;
+ * if the proxy key is already set to some value: leave alone.
+ * if an ant property of the value {@link #USE_SYSTEM_PROXIES}
+ * is set, use that instead. Else set to "true".
+ */
+ public void enableProxies() {
+ if(!(getSystemProxySetting() != null)) {
+ String proxies =owner.getProperty(USE_SYSTEM_PROXIES);
+ if(proxies ==null || Project.toBoolean(proxies)) {
+ proxies ="true";
+ }
+ String message = "setting " + USE_SYSTEM_PROXIES + " to " + proxies;
+ try {
+ owner.log(message,Project.MSG_DEBUG);
+ System.setProperty(USE_SYSTEM_PROXIES,proxies);
+ } catch (SecurityException e) {
+ owner.log("Security Exception when "+message);
+ }
+ }
+ }
+
+}