View Javadoc

1   /*
2    * $HeadURL: https://svn.apache.org/repos/asf/httpcomponents/oac.hc3x/trunk/src/java/org/apache/commons/httpclient/HttpsURL.java $
3    * $Revision$
4    * $Date$
5    *
6    * ====================================================================
7    *
8    *  Licensed to the Apache Software Foundation (ASF) under one or more
9    *  contributor license agreements.  See the NOTICE file distributed with
10   *  this work for additional information regarding copyright ownership.
11   *  The ASF licenses this file to You under the Apache License, Version 2.0
12   *  (the "License"); you may not use this file except in compliance with
13   *  the License.  You may obtain a copy of the License at
14   *
15   *      http://www.apache.org/licenses/LICENSE-2.0
16   *
17   *  Unless required by applicable law or agreed to in writing, software
18   *  distributed under the License is distributed on an "AS IS" BASIS,
19   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20   *  See the License for the specific language governing permissions and
21   *  limitations under the License.
22   * ====================================================================
23   *
24   * This software consists of voluntary contributions made by many
25   * individuals on behalf of the Apache Software Foundation.  For more
26   * information on the Apache Software Foundation, please see
27   * <http://www.apache.org/>.
28   *
29   */
30  
31  package org.apache.commons.httpclient;
32  
33  import org.apache.commons.httpclient.util.URIUtil;
34  
35  /***
36   * The HTTPS URL.
37   *
38   * @author <a href="mailto:jericho at apache.org">Sung-Gu</a>
39   * @author <a href="mailto:mbowler@GargoyleSoftware.com">Mike Bowler</a>
40   */
41  public class HttpsURL extends HttpURL {
42  
43      // ----------------------------------------------------------- Constructors
44  
45      /***
46       * Create an instance as an internal use.
47       */
48      protected HttpsURL() {
49      }
50  
51  
52      /***
53       * Construct a HTTPS URL as an escaped form of a character array with the
54       * given charset to do escape encoding.
55       *
56       * @param escaped the HTTPS URL character sequence
57       * @param charset the charset to do escape encoding
58       * @throws URIException If {@link #checkValid()} fails
59       * @throws NullPointerException if <code>escaped</code> is <code>null</code>
60       * @see #getProtocolCharset
61       */
62      public HttpsURL(char[] escaped, String charset)
63          throws URIException, NullPointerException {
64          protocolCharset = charset;
65          parseUriReference(new String(escaped), true);
66          checkValid();
67      }
68  
69  
70      /***
71       * Construct a HTTPS URL as an escaped form of a character array.
72       *
73       * @param escaped the HTTPS URL character sequence
74       * @throws URIException If {@link #checkValid()} fails
75       * @throws NullPointerException if <code>escaped</code> is <code>null</code>
76       * @see #getDefaultProtocolCharset
77       */
78      public HttpsURL(char[] escaped) throws URIException, NullPointerException {
79          parseUriReference(new String(escaped), true);
80          checkValid();
81      }
82  
83  
84      /***
85       * Construct a HTTPS URL from a given string with the given charset to do
86       * escape encoding.
87       *
88       * @param original the HTTPS URL string
89       * @param charset the charset to do escape encoding
90       * @throws URIException If {@link #checkValid()} fails
91       * @see #getProtocolCharset
92       */
93      public HttpsURL(String original, String charset) throws URIException {
94          protocolCharset = charset;
95          parseUriReference(original, false);
96          checkValid();
97      }
98  
99  
100     /***
101      * Construct a HTTPS URL from a given string.
102      *
103      * @param original the HTTPS URL string
104      * @throws URIException If {@link #checkValid()} fails
105      * @see #getDefaultProtocolCharset
106      */
107     public HttpsURL(String original) throws URIException {
108         parseUriReference(original, false);
109         checkValid();
110     }
111 
112 
113     /***
114      * Construct a HTTPS URL from given components.
115      *
116      * @param host the host string
117      * @param port the port number
118      * @param path the path string
119      * @throws URIException If {@link #checkValid()} fails
120      * @see #getDefaultProtocolCharset
121      */
122     public HttpsURL(String host, int port, String path) throws URIException {
123         this(null, host, port, path, null, null);
124     }
125 
126 
127     /***
128      * Construct a HTTPS URL from given components.
129      *
130      * @param host the host string
131      * @param port the port number
132      * @param path the path string
133      * @param query the query string
134      * @throws URIException If {@link #checkValid()} fails
135      * @see #getDefaultProtocolCharset
136      */
137     public HttpsURL(String host, int port, String path, String query)
138         throws URIException {
139 
140         this(null, host, port, path, query, null);
141     }
142 
143 
144     /***
145      * Construct a HTTPS URL from given components.
146      *
147      * @param user the user name
148      * @param password his or her password
149      * @param host the host string
150      * @throws URIException If {@link #checkValid()} fails
151      * @see #getDefaultProtocolCharset
152      */
153     public HttpsURL(String user, String password, String host)
154         throws URIException {
155 
156         this(user, password, host, -1, null, null, null);
157     }
158 
159 
160     /***
161      * Construct a HTTPS URL from given components.
162      *
163      * @param user the user name
164      * @param password his or her password
165      * @param host the host string
166      * @param port the port number
167      * @throws URIException If {@link #checkValid()} fails
168      * @see #getDefaultProtocolCharset
169      */
170     public HttpsURL(String user, String password, String host, int port)
171         throws URIException {
172 
173         this(user, password, host, port, null, null, null);
174     }
175 
176 
177     /***
178      * Construct a HTTPS URL from given components.
179      *
180      * @param user the user name
181      * @param password his or her password
182      * @param host the host string
183      * @param port the port number
184      * @param path the path string
185      * @throws URIException If {@link #checkValid()} fails
186      * @see #getDefaultProtocolCharset
187      */
188     public HttpsURL(String user, String password, String host, int port,
189             String path) throws URIException {
190 
191         this(user, password, host, port, path, null, null);
192     }
193 
194 
195     /***
196      * Construct a HTTPS URL from given components.
197      *
198      * @param user the user name
199      * @param password his or her password
200      * @param host the host string
201      * @param port the port number
202      * @param path the path string
203      * @param query The query string.
204      * @throws URIException If {@link #checkValid()} fails
205      * @see #getDefaultProtocolCharset
206      */
207     public HttpsURL(String user, String password, String host, int port,
208             String path, String query) throws URIException {
209 
210         this(user, password, host, port, path, query, null);
211     }
212 
213 
214     /***
215      * Construct a HTTPS URL from given components.
216      *
217      * @param host the host string
218      * @param path the path string
219      * @param query the query string
220      * @param fragment the fragment string
221      * @throws URIException If {@link #checkValid()} fails
222      * @see #getDefaultProtocolCharset
223      */
224     public HttpsURL(String host, String path, String query, String fragment)
225         throws URIException {
226 
227         this(null, host, -1, path, query, fragment);
228     }
229 
230 
231     /***
232      * Construct a HTTPS URL from given components.
233      *
234      * Note: The <code>userinfo</code> format is normally
235      * <code>&lt;username&gt;:&lt;password&gt;</code> where
236      * username and password must both be URL escaped.
237      *  
238      * @param userinfo the userinfo string whose parts are URL escaped
239      * @param host the host string
240      * @param path the path string
241      * @param query the query string
242      * @param fragment the fragment string
243      * @throws URIException If {@link #checkValid()} fails
244      * @see #getDefaultProtocolCharset
245      */
246     public HttpsURL(String userinfo, String host, String path, String query,
247             String fragment) throws URIException {
248 
249         this(userinfo, host, -1, path, query, fragment);
250     }
251 
252 
253     /***
254      * Construct a HTTPS URL from given components.
255      *
256      * Note: The <code>userinfo</code> format is normally
257      * <code>&lt;username&gt;:&lt;password&gt;</code> where
258      * username and password must both be URL escaped.
259      *  
260      * @param userinfo the userinfo string whose parts are URL escaped
261      * @param host the host string
262      * @param port the port number
263      * @param path the path string
264      * @throws URIException If {@link #checkValid()} fails
265      * @see #getDefaultProtocolCharset
266      */
267     public HttpsURL(String userinfo, String host, int port, String path)
268         throws URIException {
269 
270         this(userinfo, host, port, path, null, null);
271     }
272 
273 
274     /***
275      * Construct a HTTPS URL from given components.
276      *
277      * Note: The <code>userinfo</code> format is normally
278      * <code>&lt;username&gt;:&lt;password&gt;</code> where
279      * username and password must both be URL escaped.
280      *  
281      * @param userinfo the userinfo string whose parts are URL escaped
282      * @param host the host string
283      * @param port the port number
284      * @param path the path string
285      * @param query the query string
286      * @throws URIException If {@link #checkValid()} fails
287      * @see #getDefaultProtocolCharset
288      */
289     public HttpsURL(String userinfo, String host, int port, String path,
290             String query) throws URIException {
291 
292         this(userinfo, host, port, path, query, null);
293     }
294 
295 
296     /***
297      * Construct a HTTPS URL from given components.
298      *
299      * Note: The <code>userinfo</code> format is normally
300      * <code>&lt;username&gt;:&lt;password&gt;</code> where
301      * username and password must both be URL escaped.
302      *  
303      * @param userinfo the userinfo string whose parts are URL escaped
304      * @param host the host string
305      * @param port the port number
306      * @param path the path string
307      * @param query the query string
308      * @param fragment the fragment string
309      * @throws URIException If {@link #checkValid()} fails
310      * @see #getDefaultProtocolCharset
311      */
312     public HttpsURL(String userinfo, String host, int port, String path,
313             String query, String fragment) throws URIException {
314 
315         // validate and contruct the URI character sequence
316         StringBuffer buff = new StringBuffer();
317         if (userinfo != null || host != null || port != -1) {
318             _scheme = DEFAULT_SCHEME; // in order to verify the own protocol
319             buff.append(_default_scheme);
320             buff.append("://");
321             if (userinfo != null) {
322                 buff.append(userinfo);
323                 buff.append('@');
324             }
325             if (host != null) {
326                 buff.append(URIUtil.encode(host, URI.allowed_host));
327                 if (port != -1 || port != DEFAULT_PORT) {
328                     buff.append(':');
329                     buff.append(port);
330                 }
331             }
332         }
333         if (path != null) {  // accept empty path
334             if (scheme != null && !path.startsWith("/")) {
335                 throw new URIException(URIException.PARSING,
336                         "abs_path requested");
337             }
338             buff.append(URIUtil.encode(path, URI.allowed_abs_path));
339         }
340         if (query != null) {
341             buff.append('?');
342             buff.append(URIUtil.encode(query, URI.allowed_query));
343         }
344         if (fragment != null) {
345             buff.append('#');
346             buff.append(URIUtil.encode(fragment, URI.allowed_fragment));
347         }
348         parseUriReference(buff.toString(), true);
349         checkValid();
350     }
351 
352     /***
353      * Construct a HTTP URL from given components.
354      *
355      * @param user the user name
356      * @param password his or her password
357      * @param host the host string
358      * @param port the port number
359      * @param path the path string
360      * @param query the query string
361      * @param fragment the fragment string
362      * @throws URIException If {@link #checkValid()} fails
363      * @see #getDefaultProtocolCharset
364      */
365     public HttpsURL(String user, String password, String host, int port,
366             String path, String query, String fragment) throws URIException {
367         this(HttpURL.toUserinfo(user, password), host, port, path, query, fragment);
368     }    
369 
370     /***
371      * Construct a HTTPS URL with a given relative HTTPS URL string.
372      *
373      * @param base the base HttpsURL
374      * @param relative the relative HTTPS URL string
375      * @throws URIException If {@link #checkValid()} fails
376      */
377     public HttpsURL(HttpsURL base, String relative) throws URIException {
378         this(base, new HttpsURL(relative));
379     }
380 
381 
382     /***
383      * Construct a HTTPS URL with a given relative URL.
384      *
385      * @param base the base HttpsURL
386      * @param relative the relative HttpsURL
387      * @throws URIException If {@link #checkValid()} fails
388      */
389     public HttpsURL(HttpsURL base, HttpsURL relative) throws URIException {
390         super(base, relative);
391         checkValid();
392     }
393 
394     // -------------------------------------------------------------- Constants
395 
396     /***
397      * Default scheme for HTTPS URL.
398      */
399     public static final char[] DEFAULT_SCHEME = { 'h', 't', 't', 'p', 's' };
400     
401     /***
402      * Default scheme for HTTPS URL.
403      * @deprecated Use {@link #DEFAULT_SCHEME} instead.  This one doesn't
404      * conform to the project naming conventions.
405      */
406     public static final char[] _default_scheme = DEFAULT_SCHEME;
407 
408 
409     /***
410      * Default port for HTTPS URL.
411      */
412     public static final int DEFAULT_PORT = 443;
413 
414     /***
415      * Default port for HTTPS URL.
416      * @deprecated Use {@link #DEFAULT_PORT} instead.  This one doesn't conform
417      * to the project naming conventions.
418      */
419     public static final int _default_port = DEFAULT_PORT;
420 
421 
422     /***
423      * The serialVersionUID.
424      */
425     static final long serialVersionUID = 887844277028676648L;
426 
427     // ------------------------------------------------------------- The scheme
428 
429     /***
430      * Get the scheme.  You can get the scheme explicitly.
431      *
432      * @return the scheme
433      */
434     public char[] getRawScheme() {
435         return (_scheme == null) ? null : HttpsURL.DEFAULT_SCHEME;
436     }
437 
438 
439     /***
440      * Get the scheme.  You can get the scheme explicitly.
441      *
442      * @return the scheme null if empty or undefined
443      */
444     public String getScheme() {
445         return (_scheme == null) ? null : new String(HttpsURL.DEFAULT_SCHEME);
446     }
447 
448     // --------------------------------------------------------------- The port
449 
450     /***
451      * Get the port number.
452      * @return the port number
453      */
454     public int getPort() {
455         return (_port == -1) ? HttpsURL.DEFAULT_PORT : _port;
456     }    
457     
458     // ---------------------------------------------------------------- Utility
459 
460     /***
461      * Verify the valid class use for construction.
462      *
463      * @throws URIException the wrong scheme use
464      */
465     protected void checkValid() throws URIException {
466         // could be explicit protocol or undefined.
467         if (!(equals(_scheme, DEFAULT_SCHEME) || _scheme == null)) {
468             throw new URIException(URIException.PARSING, "wrong class use");
469         }
470     }
471 
472 }
473