1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.resolver.internal.ant.types;
20
21 import org.apache.maven.resolver.internal.ant.AntRepoSys;
22 import org.apache.tools.ant.BuildException;
23 import org.apache.tools.ant.Project;
24 import org.apache.tools.ant.types.DataType;
25 import org.apache.tools.ant.types.Reference;
26
27 /**
28 * Defines a proxy configuration for Maven artifact resolution.
29 * <p>
30 * This Ant data type allows specification of a proxy host, port, type (e.g., HTTP),
31 * non-proxy hosts, and optional authentication credentials.
32 * Once declared, it is automatically registered with the project's repository system.
33 * </p>
34 *
35 * <p>
36 * A proxy definition can also be referenced by {@code refid}, allowing reuse and modular build files.
37 * When defined as a reference, no other attributes or nested elements may be set.
38 * </p>
39 *
40 * @see Authentication
41 * @see org.apache.maven.resolver.internal.ant.AntRepoSys
42 */
43 public class Proxy extends DataType {
44
45 private String host;
46
47 private int port;
48
49 private String type;
50
51 private String nonProxyHosts;
52
53 private Authentication authentication;
54
55 /**
56 * Default constructor initializes the proxy with no settings.
57 * This allows attributes to be set before the project is assigned.
58 */
59 public Proxy() {
60 // Default constructor
61 }
62
63 /**
64 * Sets the associated Ant {@code Project} and registers this proxy instance
65 * with the repository system.
66 *
67 * @param project the Ant project
68 */
69 @Override
70 public void setProject(Project project) {
71 super.setProject(project);
72
73 AntRepoSys.getInstance(project).addProxy(this);
74 }
75
76 /**
77 * Resolves this object if defined as a reference and verifies that it is a
78 * {@code Proxy} instance.
79 *
80 * @return the referenced {@code Proxy} instance
81 * @throws org.apache.tools.ant.BuildException if the reference is invalid
82 */
83 protected Proxy getRef() {
84 return getCheckedRef(Proxy.class);
85 }
86
87 /**
88 * Sets this proxy as a reference to another defined proxy.
89 * <p>
90 * This method must not be used in combination with any other attributes
91 * or nested {@code <authentication>} elements.
92 * </p>
93 *
94 * @param ref the reference to another {@code Proxy} definition
95 *
96 * @throws org.apache.tools.ant.BuildException if attributes or children are already set
97 */
98 @Override
99 public void setRefid(Reference ref) {
100 if (host != null || port != 0 || type != null || nonProxyHosts != null) {
101 throw tooManyAttributes();
102 }
103 if (authentication != null) {
104 throw noChildrenAllowed();
105 }
106 super.setRefid(ref);
107 }
108
109 /**
110 * Returns the proxy host name or IP address.
111 *
112 * @return the proxy host
113 */
114 public String getHost() {
115 if (isReference()) {
116 return getRef().getHost();
117 }
118 return host;
119 }
120
121 /**
122 * Sets the proxy host name or IP address.
123 *
124 * @param host the proxy host to use
125 * @throws org.apache.tools.ant.BuildException if this object is a reference
126 */
127 public void setHost(String host) {
128 checkAttributesAllowed();
129 this.host = host;
130 }
131
132 /**
133 * Returns the proxy port number.
134 *
135 * @return the port number
136 */
137 public int getPort() {
138 if (isReference()) {
139 return getRef().getPort();
140 }
141 return port;
142 }
143
144 /**
145 * Sets the proxy port number.
146 * Must be within the range 1 to 65535.
147 *
148 * @param port the port number
149 * @throws org.apache.tools.ant.BuildException if the port is out of range or attributes are not allowed
150 */
151 public void setPort(int port) {
152 checkAttributesAllowed();
153 if (port <= 0 || port > 0xFFFF) {
154 throw new BuildException("The port number must be within the range 1 - 65535");
155 }
156 this.port = port;
157 }
158
159 /**
160 * Returns the proxy type, such as {@code http}.
161 *
162 * @return the proxy type, or {@code null} if not set
163 */
164 public String getType() {
165 if (isReference()) {
166 return getRef().getType();
167 }
168 return type;
169 }
170
171 /**
172 * Sets the proxy type (e.g., {@code http}).
173 *
174 * @param type the proxy protocol type
175 * @throws org.apache.tools.ant.BuildException if this object is a reference
176 */
177 public void setType(String type) {
178 checkAttributesAllowed();
179 this.type = type;
180 }
181
182 /**
183 * Returns the non-proxy hosts setting, typically a pipe-delimited list.
184 *
185 * @return the non-proxy hosts
186 */
187 public String getNonProxyHosts() {
188 if (isReference()) {
189 return getRef().getNonProxyHosts();
190 }
191 return nonProxyHosts;
192 }
193
194 /**
195 * Sets the non-proxy hosts — hosts that should bypass the proxy.
196 * The format is usually a pipe-separated list (e.g., {@code localhost|*.example.com}).
197 *
198 * @param nonProxyHosts the non-proxy hosts pattern
199 * @throws org.apache.tools.ant.BuildException if this object is a reference
200 */
201 public void setNonProxyHosts(String nonProxyHosts) {
202 checkAttributesAllowed();
203 this.nonProxyHosts = nonProxyHosts;
204 }
205
206 /**
207 * Returns the {@link Authentication} settings associated with this proxy.
208 *
209 * @return the authentication configuration, or {@code null} if none
210 */
211 public Authentication getAuthentication() {
212 if (isReference()) {
213 return getRef().getAuthentication();
214 }
215 return authentication;
216 }
217
218 /**
219 * Allow Ant to add an {@code <authentication>} child element to configure credentials for the proxy.
220 *
221 * @param authentication the authentication element
222 * @throws org.apache.tools.ant.BuildException if multiple authentications are specified or children are not allowed
223 */
224 public void addAuthentication(Authentication authentication) {
225 checkChildrenAllowed();
226 if (this.authentication != null) {
227 throw new BuildException("You must not specify multiple <authentication> elements");
228 }
229 this.authentication = authentication;
230 }
231
232 /**
233 * Sets a reference to an existing {@link Authentication} element to be used for this proxy.
234 * <p>
235 * This allows the proxy to reuse a separately defined {@code <authentication>} element
236 * via Ant's {@code refid} mechanism, enabling modular and reusable configuration.
237 * If no authentication has been previously configured, a new {@code Authentication} instance is created and associated with the project.
238 * </p>
239 *
240 * @param ref the Ant reference pointing to an existing {@code Authentication} instance
241 *
242 * @see #addAuthentication(Authentication)
243 * @see Authentication
244 */
245 public void setAuthRef(Reference ref) {
246 if (authentication == null) {
247 authentication = new Authentication();
248 authentication.setProject(getProject());
249 }
250 authentication.setRefid(ref);
251 }
252 }