49 * @author James Gosling
50 * @see java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
51 * @since 1.0
52 */
53 public abstract class URLStreamHandler {
54 /**
55 * Opens a connection to the object referenced by the
56 * {@code URL} argument.
57 * This method should be overridden by a subclass.
58 *
59 * <p>If for the handler's protocol (such as HTTP or JAR), there
60 * exists a public, specialized URLConnection subclass belonging
61 * to one of the following packages or one of their subpackages:
62 * java.lang, java.io, java.util, java.net, the connection
63 * returned will be of that subclass. For example, for HTTP an
64 * HttpURLConnection will be returned, and for JAR a
65 * JarURLConnection will be returned.
66 *
67 * @param u the URL that this connects to.
68 * @return a {@code URLConnection} object for the {@code URL}.
69 * @exception IOException if an I/O error occurs while opening the
70 * connection.
71 */
72 protected abstract URLConnection openConnection(URL u) throws IOException;
73
74 /**
75 * Same as openConnection(URL), except that the connection will be
76 * made through the specified proxy; Protocol handlers that do not
77 * support proxying will ignore the proxy parameter and make a
78 * normal connection.
79 *
80 * <p> Calling this method preempts the system's default
81 * {@link java.net.ProxySelector ProxySelector} settings.
82 *
83 * @implSpec
84 * The default implementation of this method first checks that the given
85 * {@code URL} and {@code Proxy} are not null, then throws {@code
86 * UnsupportedOperationException}. Subclasses should override this method
87 * with an appropriate implementation.
88 *
89 * @param u the URL that this connects to.
90 * @param p the proxy through which the connection will be made.
91 * If direct connection is desired, Proxy.NO_PROXY
92 * should be specified.
93 * @return a {@code URLConnection} object for the {@code URL}.
94 * @exception IOException if an I/O error occurs while opening the
95 * connection.
96 * @exception IllegalArgumentException if either u or p is null,
97 * or p has the wrong type.
98 * @exception UnsupportedOperationException if the subclass that
99 * implements the protocol doesn't support this method.
100 * @since 1.5
101 */
102 protected URLConnection openConnection(URL u, Proxy p) throws IOException {
103 if (u == null || p == null)
104 throw new IllegalArgumentException("null " + (u == null ? "url" : "proxy"));
105 throw new UnsupportedOperationException("Method not implemented.");
106 }
107
108 /**
109 * Parses the string representation of a {@code URL} into a
110 * {@code URL} object.
111 * <p>
112 * If there is any inherited context, then it has already been
113 * copied into the {@code URL} argument.
114 * <p>
115 * The {@code parseURL} method of {@code URLStreamHandler}
116 * parses the string representation as if it were an
117 * {@code http} specification. Most URL protocol families have a
118 * similar parsing. A stream protocol handler for a protocol that has
493 ? "//" + s : "")
494 + ((s = u.getPath()) != null ? s : "")
495 + ((s = u.getQuery()) != null ? '?' + s : "")
496 + ((s = u.getRef()) != null ? '#' + s : "");
497 }
498
499 /**
500 * Sets the fields of the {@code URL} argument to the indicated values.
501 * Only classes derived from URLStreamHandler are able
502 * to use this method to set the values of the URL fields.
503 *
504 * @param u the URL to modify.
505 * @param protocol the protocol name.
506 * @param host the remote host value for the URL.
507 * @param port the port on the remote machine.
508 * @param authority the authority part for the URL.
509 * @param userInfo the userInfo part of the URL.
510 * @param path the path component of the URL.
511 * @param query the query part for the URL.
512 * @param ref the reference.
513 * @exception SecurityException if the protocol handler of the URL is
514 * different from this one
515 * @since 1.3
516 */
517 protected void setURL(URL u, String protocol, String host, int port,
518 String authority, String userInfo, String path,
519 String query, String ref) {
520 if (this != u.handler) {
521 throw new SecurityException("handler for url different from " +
522 "this handler");
523 } else if (host != null && u.isBuiltinStreamHandler(this)) {
524 String s = IPAddressUtil.checkHostString(host);
525 if (s != null) throw new IllegalArgumentException(s);
526 }
527 // ensure that no one can reset the protocol on a given URL.
528 u.set(u.getProtocol(), host, port, authority, userInfo, path, query, ref);
529 }
530
531 /**
532 * Sets the fields of the {@code URL} argument to the indicated values.
533 * Only classes derived from URLStreamHandler are able
534 * to use this method to set the values of the URL fields.
535 *
536 * @param u the URL to modify.
537 * @param protocol the protocol name. This value is ignored since 1.2.
538 * @param host the remote host value for the URL.
539 * @param port the port on the remote machine.
540 * @param file the file.
541 * @param ref the reference.
542 * @exception SecurityException if the protocol handler of the URL is
543 * different from this one
544 * @deprecated Use setURL(URL, String, String, int, String, String, String,
545 * String);
546 */
547 @Deprecated
548 protected void setURL(URL u, String protocol, String host, int port,
549 String file, String ref) {
550 /*
551 * Only old URL handlers call this, so assume that the host
552 * field might contain "user:passwd@host". Fix as necessary.
553 */
554 String authority = null;
555 String userInfo = null;
556 if (host != null && !host.isEmpty()) {
557 authority = (port == -1) ? host : host + ":" + port;
558 int at = host.lastIndexOf('@');
559 if (at != -1) {
560 userInfo = host.substring(0, at);
561 host = host.substring(at+1);
562 }
|
49 * @author James Gosling
50 * @see java.net.URL#URL(java.lang.String, java.lang.String, int, java.lang.String)
51 * @since 1.0
52 */
53 public abstract class URLStreamHandler {
54 /**
55 * Opens a connection to the object referenced by the
56 * {@code URL} argument.
57 * This method should be overridden by a subclass.
58 *
59 * <p>If for the handler's protocol (such as HTTP or JAR), there
60 * exists a public, specialized URLConnection subclass belonging
61 * to one of the following packages or one of their subpackages:
62 * java.lang, java.io, java.util, java.net, the connection
63 * returned will be of that subclass. For example, for HTTP an
64 * HttpURLConnection will be returned, and for JAR a
65 * JarURLConnection will be returned.
66 *
67 * @param u the URL that this connects to.
68 * @return a {@code URLConnection} object for the {@code URL}.
69 * @throws IOException if an I/O error occurs while opening the
70 * connection.
71 */
72 protected abstract URLConnection openConnection(URL u) throws IOException;
73
74 /**
75 * Same as openConnection(URL), except that the connection will be
76 * made through the specified proxy; Protocol handlers that do not
77 * support proxying will ignore the proxy parameter and make a
78 * normal connection.
79 *
80 * <p> Calling this method preempts the system's default
81 * {@link java.net.ProxySelector ProxySelector} settings.
82 *
83 * @implSpec
84 * The default implementation of this method first checks that the given
85 * {@code URL} and {@code Proxy} are not null, then throws {@code
86 * UnsupportedOperationException}. Subclasses should override this method
87 * with an appropriate implementation.
88 *
89 * @param u the URL that this connects to.
90 * @param p the proxy through which the connection will be made.
91 * If direct connection is desired, Proxy.NO_PROXY
92 * should be specified.
93 * @return a {@code URLConnection} object for the {@code URL}.
94 * @throws IOException if an I/O error occurs while opening the
95 * connection.
96 * @throws IllegalArgumentException if either u or p is null,
97 * or p has the wrong type.
98 * @throws UnsupportedOperationException if the subclass that
99 * implements the protocol doesn't support this method.
100 * @since 1.5
101 */
102 protected URLConnection openConnection(URL u, Proxy p) throws IOException {
103 if (u == null || p == null)
104 throw new IllegalArgumentException("null " + (u == null ? "url" : "proxy"));
105 throw new UnsupportedOperationException("Method not implemented.");
106 }
107
108 /**
109 * Parses the string representation of a {@code URL} into a
110 * {@code URL} object.
111 * <p>
112 * If there is any inherited context, then it has already been
113 * copied into the {@code URL} argument.
114 * <p>
115 * The {@code parseURL} method of {@code URLStreamHandler}
116 * parses the string representation as if it were an
117 * {@code http} specification. Most URL protocol families have a
118 * similar parsing. A stream protocol handler for a protocol that has
493 ? "//" + s : "")
494 + ((s = u.getPath()) != null ? s : "")
495 + ((s = u.getQuery()) != null ? '?' + s : "")
496 + ((s = u.getRef()) != null ? '#' + s : "");
497 }
498
499 /**
500 * Sets the fields of the {@code URL} argument to the indicated values.
501 * Only classes derived from URLStreamHandler are able
502 * to use this method to set the values of the URL fields.
503 *
504 * @param u the URL to modify.
505 * @param protocol the protocol name.
506 * @param host the remote host value for the URL.
507 * @param port the port on the remote machine.
508 * @param authority the authority part for the URL.
509 * @param userInfo the userInfo part of the URL.
510 * @param path the path component of the URL.
511 * @param query the query part for the URL.
512 * @param ref the reference.
513 * @throws SecurityException if the protocol handler of the URL is
514 * different from this one
515 * @since 1.3
516 */
517 protected void setURL(URL u, String protocol, String host, int port,
518 String authority, String userInfo, String path,
519 String query, String ref) {
520 if (this != u.handler) {
521 throw new SecurityException("handler for url different from " +
522 "this handler");
523 } else if (host != null && u.isBuiltinStreamHandler(this)) {
524 String s = IPAddressUtil.checkHostString(host);
525 if (s != null) throw new IllegalArgumentException(s);
526 }
527 // ensure that no one can reset the protocol on a given URL.
528 u.set(u.getProtocol(), host, port, authority, userInfo, path, query, ref);
529 }
530
531 /**
532 * Sets the fields of the {@code URL} argument to the indicated values.
533 * Only classes derived from URLStreamHandler are able
534 * to use this method to set the values of the URL fields.
535 *
536 * @param u the URL to modify.
537 * @param protocol the protocol name. This value is ignored since 1.2.
538 * @param host the remote host value for the URL.
539 * @param port the port on the remote machine.
540 * @param file the file.
541 * @param ref the reference.
542 * @throws SecurityException if the protocol handler of the URL is
543 * different from this one
544 * @deprecated Use setURL(URL, String, String, int, String, String, String,
545 * String);
546 */
547 @Deprecated
548 protected void setURL(URL u, String protocol, String host, int port,
549 String file, String ref) {
550 /*
551 * Only old URL handlers call this, so assume that the host
552 * field might contain "user:passwd@host". Fix as necessary.
553 */
554 String authority = null;
555 String userInfo = null;
556 if (host != null && !host.isEmpty()) {
557 authority = (port == -1) ? host : host + ":" + port;
558 int at = host.lastIndexOf('@');
559 if (at != -1) {
560 userInfo = host.substring(0, at);
561 host = host.substring(at+1);
562 }
|