* There are a great many protocols supported by URL's such as "http", * "ftp", and "file". This object can handle any arbitrary URL for which * a URLStreamHandler object can be written. Default protocol handlers * are provided for the "http" and "ftp" protocols. Additional protocols * handler implementations may be provided in the future. In any case, * an application or applet can install its own protocol handlers that * can be "chained" with other protocol hanlders in the system to extend * the base functionality provided with this class. (Note, however, that * unsigned applets cannot access properties by default or install their * own protocol handlers). *
* This chaining is done via the system property java.protocol.handler.pkgs
* If this property is set, it is assumed to be a "|" separated list of
* package names in which to attempt locating protocol handlers. The
* protocol handler is searched for by appending the string
* ".
* All of the constructor methods of URL attempt to load a protocol
* handler and so any needed protocol handlers must be installed when
* the URL is constructed.
*
* Here is an example of how URL searches for protocol handlers. Assume
* the value of java.protocol.handler.pkgs is "com.foo|com.bar" and the
* URL is "news://comp.lang.java.programmer". URL would looking the
* following places for protocol handlers:
*
* If the protocol handler is not found in any of those locations, a
* MalformedURLException would be thrown.
*
* Please note that a protocol handler must be a subclass of
* URLStreamHandler.
*
* @author Aaron M. Renn (arenn@urbanophile.com)
* @author Warren Levy
* Additionally, this method allows the caller to specify a protocol handler
* to use instead of the default. If this handler is specified, the caller
* must have the "specifyStreamHandler" permission
* (see
* com.foo.news.Handler
* com.bar.news.Handler
* gnu.java.net.news.Handler
*
joe@some.host.net.
*/
private String host;
/**
* The port number of this protocol or -1 if the port number used is
* the default for this protocol.
*/
private int port = -1; // Initialize for constructor using context.
/**
* The "file" portion of the URL. It is defined as path[?query].
*/
private String file;
/**
* The anchor portion of the URL.
*/
private String ref;
/**
* This is the hashCode for this URL
*/
private int hashCode = 0;
/**
* The protocol handler in use for this URL
*/
transient private URLStreamHandler handler;
/**
* This a table where we cache protocol handlers to avoid the overhead
* of looking them up each time.
*/
private static Hashtable handlers = new Hashtable();
/**
* If an application installs its own protocol handler factory, this is
* where we keep track of it.
*/
private static URLStreamHandlerFactory factory;
private static final long serialVersionUID = -7627629688361524110L;
/**
* Constructs a URL and loads a protocol handler for the values passed as
* arguments.
*
* @param protocol The protocol for this URL ("http", "ftp", etc)
* @param host The hostname or IP address to connect to
* @param port The port number to use, or -1 to use the protocol's
* default port
* @param file The "file" portion of the URL.
*
* @exception MalformedURLException If a protocol handler cannot be loaded or
* a parse error occurs.
*/
public URL(String protocol, String host, int port, String file)
throws MalformedURLException
{
this(protocol, host, port, file, null);
}
/**
* Constructs a URL and loads a protocol handler for the values passed in
* as arugments. Uses the default port for the protocol.
*
* @param protocol The protocol for this URL ("http", "ftp", etc)
* @param host The hostname or IP address for this URL
* @param file The "file" portion of this URL.
*
* @exception MalformedURLException If a protocol handler cannot be loaded or
* a parse error occurs.
*/
public URL(String protocol, String host, String file)
throws MalformedURLException
{
this(protocol, host, -1, file, null);
}
/**
* This method initializes a new instance of URL with the
* specified protocol, host, port, and file. Additionally, this method
* allows the caller to specify a protocol handler to use instead of
* the default. If this handler is specified, the caller must have
* the "specifyStreamHandler" permission (see NetPermission)
* or a SecurityException will be thrown.
*
* @param protocol The protocol for this URL ("http", "ftp", etc)
* @param host The hostname or IP address to connect to
* @param port The port number to use, or -1 to use the protocol's default
* port
* @param file The "file" portion of the URL.
* @param handler The protocol handler to use with this URL.
*
* @exception MalformedURLException If no protocol handler can be loaded
* for the specified protocol.
* @exception SecurityException If the SecurityManager exists
* and does not allow the caller to specify its own protocol handler.
*
* @since 1.2
*/
public URL(String protocol, String host, int port, String file,
URLStreamHandler handler) throws MalformedURLException
{
if (protocol == null)
throw new MalformedURLException("null protocol");
this.protocol = protocol.toLowerCase();
if (handler != null)
{
SecurityManager s = System.getSecurityManager();
if (s != null)
s.checkPermission (new NetPermission ("specifyStreamHandler"));
this.handler = handler;
}
else
this.handler = getURLStreamHandler(protocol);
if (this.handler == null)
throw new MalformedURLException (
"Protocol handler not found: " + protocol);
this.host = host;
this.port = port;
this.authority = null;
int hashAt = file.indexOf('#');
if (hashAt < 0)
{
this.file = file;
this.ref = null;
}
else
{
this.file = file.substring(0, hashAt);
this.ref = file.substring(hashAt + 1);
}
hashCode = hashCode(); // Used for serialization.
}
/**
* Initializes a URL from a complete string specification such as
* "http://www.urbanophile.com/arenn/". First the protocol name is parsed
* out of the string. Then a handler is located for that protocol and
* the parseURL() method of that protocol handler is used to parse the
* remaining fields.
*
* @param spec The complete String representation of a URL
*
* @exception MalformedURLException If a protocol handler cannot be found
* or the URL cannot be parsed
*/
public URL(String spec) throws MalformedURLException
{
this((URL) null, spec, (URLStreamHandler) null);
}
/*
* This method parses a String representation of a URL within the
* context of an existing URL. Principally this means that any
* fields not present the URL are inheritied from the context URL.
* This allows relative URL's to be easily constructed. If the
* context argument is null, then a complete URL must be specified
* in the URL string. If the protocol parsed out of the URL is
* different from the context URL's protocol, then then URL String
* is also expected to be a complete URL.
*
* @param context The context on which to parse the specification
* @param spec The string to parse an URL
*
* @exception MalformedURLException If a protocol handler cannot be found
* for the URL cannot be parsed
*/
public URL(URL context, String spec) throws MalformedURLException
{
this(context, spec, (URLStreamHandler) null);
}
/**
* Creates an URL from given arguments
* This method parses a String representation of a URL within the
* context of an existing URL. Principally this means that any fields
* not present the URL are inheritied from the context URL. This allows
* relative URL's to be easily constructed. If the context argument is
* null, then a complete URL must be specified in the URL string.
* If the protocol parsed out of the URL is different
* from the context URL's protocol, then then URL String is also
* expected to be a complete URL.
* NetPermission) or a SecurityException
* will be thrown.
*
* @param context The context in which to parse the specification
* @param spec The string to parse as an URL
* @param handler The stream handler for the URL
*
* @exception MalformedURLException If a protocol handler cannot be found
* or the URL cannot be parsed
* @exception SecurityException If the SecurityManager exists
* and does not allow the caller to specify its own protocol handler.
*
* @since 1.2
*/
public URL(URL context, String spec, URLStreamHandler handler)
throws MalformedURLException
{
/* A protocol is defined by the doc as the substring before a ':'
* as long as the ':' occurs before any '/'.
*
* If context is null, then spec must be an absolute URL.
*
* The relative URL need not specify all the components of a URL.
* If the protocol, host name, or port number is missing, the value
* is inherited from the context. A bare file component is appended
* to the context's file. The optional anchor is not inherited.
*/
// If this is an absolute URL, then ignore context completely.
// An absolute URL must have chars prior to "://" but cannot have a colon
// right after the "://". The second colon is for an optional port value
// and implies that the host from the context is used if available.
int colon;
if ((colon = spec.indexOf("://", 1)) > 0 &&
! spec.regionMatches(colon, "://:", 0, 4))
context = null;
int slash;
if ((colon = spec.indexOf(':')) > 0 &&
(colon < (slash = spec.indexOf('/')) || slash < 0))
{
// Protocol specified in spec string.
protocol = spec.substring(0, colon).toLowerCase();
if (context != null && context.protocol.equals(protocol))
{
// The 1.2 doc specifically says these are copied to the new URL.
host = context.host;
port = context.port;
file = context.file;
authority = context.authority;
}
}
else if (context != null)
{
// Protocol NOT specified in spec string.
// Use context fields (except ref) as a foundation for relative URLs.
colon = -1;
protocol = context.protocol;
host = context.host;
port = context.port;
file = context.file;
authority = context.authority;
}
else // Protocol NOT specified in spec. and no context available.
throw new
MalformedURLException("Absolute URL required with null context");
if (handler != null)
{
SecurityManager s = System.getSecurityManager ();
if (s != null)
s.checkPermission (new NetPermission ("specifyStreamHandler"));
this.handler = handler;
}
else
this.handler = getURLStreamHandler(protocol);
if (this.handler == null)
throw new MalformedURLException("Protocol handler not found: "
+ protocol);
// JDK 1.2 doc for parseURL specifically states that any '#' ref
// is to be excluded by passing the 'limit' as the indexOf the '#'
// if one exists, otherwise pass the end of the string.
int hashAt = spec.indexOf('#', colon + 1);
this.handler.parseURL(this, spec, colon + 1,
hashAt < 0 ? spec.length() : hashAt);
if (hashAt >= 0)
ref = spec.substring(hashAt + 1);
hashCode = hashCode(); // Used for serialization.
}
/**
* Test another URL for equality with this one. This will be true only if
* the argument is non-null and all of the fields in the URL's match
* exactly (ie, protocol, host, port, file, and ref). Overrides
* Object.equals(), implemented by calling the equals method of the handler.
*
* @param url The URL to compare with
*
* @return true if the URL is equal, false otherwise
*/
public boolean equals(Object obj)
{
if (obj == null || ! (obj instanceof URL))
return false;
URL uObj = (URL) obj;
return handler.equals (this, uObj);
}
/**
* Returns the contents of this URL as an object by first opening a
* connection, then calling the getContent() method against the connection
*
* @return A content object for this URL
* @exception IOException If opening the connection or getting the
* content fails.
*
* @since 1.3
*/
public final Object getContent() throws IOException
{
return openConnection().getContent();
}
/**
* Gets the contents of this URL
*
* @exception IOException If an error occurs
*/
public final Object getContent (Class[] classes) throws IOException
{
// FIXME: implement this
return getContent();
}
/**
* Returns the file portion of the URL.
* Defined as path[?query].
* Returns the empty string if there is no file portion.
*/
public String getFile()
{
return file == null ? "" : file;
}
/**
* Returns the path of the URL. This is the part of the file before any '?'
* character.
*
* @since 1.3
*/
public String getPath()
{
int quest = (file == null) ? -1 : file.indexOf('?');
return quest < 0 ? getFile() : file.substring(0, quest);
}
/**
* Returns the authority of the URL
*
* @since 1.3
*/
public String getAuthority()
{
return authority;
}
/**
* Returns the host of the URL
*/
public String getHost()
{
int at = (host == null) ? -1 : host.indexOf('@');
return at < 0 ? host : host.substring(at + 1, host.length());
}
/**
* Returns the port number of this URL or -1 if the default port number is
* being used.
*
* @return The port number
*
* @see #getDefaultPort()
*/
public int getPort()
{
return port;
}
/**
* Returns the default port of the URL. If the StreamHandler for the URL
* protocol does not define a default port it returns -1.
*/
public int getDefaultPort()
{
return handler.getDefaultPort();
}
/**
* Returns the protocol of the URL
*/
public String getProtocol()
{
return protocol;
}
/**
* Returns the ref (sometimes called the "# reference" or "anchor") portion
* of the URL.
*
* @return The ref
*/
public String getRef()
{
return ref;
}
/**
* Returns the user information of the URL. This is the part of the host
* name before the '@'.
*
* @return the user at a particular host or null when no user defined.
*/
public String getUserInfo ()
{
int at = (host == null) ? -1 : host.indexOf('@');
return at < 0 ? null : host.substring(0, at);
}
/**
* Returns the query of the URL. This is the part of the file before the
* '?'.
*
* @ return the query part of the file, or null when there is no query part.
*/
public String getQuery ()
{
int quest = (file == null) ? -1 : file.indexOf('?');
return quest < 0 ? null : file.substring(quest + 1, file.length());
}
/**
* Returns a hashcode computed by the URLStreamHandler of this URL
*/
public int hashCode()
{
if (hashCode != 0)
return hashCode; // Use cached value if available.
else
return handler.hashCode (this);
}
/**
* Returns a URLConnection object that represents a connection to the remote
* object referred to by the URL. The URLConnection is created by calling the
* openConnection() method of the protocol handler
*
* @return A URLConnection for this URL
* @exception IOException If an error occurs
*/
public URLConnection openConnection() throws IOException
{
return handler.openConnection(this);
}
/**
* Opens a connection to this URL and returns an InputStream for reading
* from that connection
*
* @exception IOException If an error occurs
*/
public final InputStream openStream() throws IOException
{
return openConnection().getInputStream();
}
/**
* Tests whether or not another URL refers to the same "file" as this one.
* This will be true if and only if the passed object is not null, is a
* URL, and matches all fields but the ref (ie, protocol, host, port,
* and file);
*
* @param url The URL object to test with
*
* @return true if URL matches this URL's file, false otherwise
*/
public boolean sameFile(URL other)
{
return handler.sameFile(this, other);
}
/**
* Sets the specified fields of the URL. This is not a public method so
* that only URLStreamHandlers can modify URL fields. This might be called
* by the parseURL() method in that class. URLs are otherwise
* constant.
*
* @param protocol The protocol name for this URL
* @param host The hostname or IP address for this URL
* @param port The port number of this URL
* @param file The "file" portion of this URL.
* @param ref The anchor portion of this URL.
*/
protected void set(String protocol, String host, int port, String file,
String ref)
{
// TBD: Theoretically, a poorly written StreamHandler could pass an
// invalid protocol. It will cause the handler to be set to null
// thus overriding a valid handler. Callers of this method should
// be aware of this.
this.handler = getURLStreamHandler(protocol);
this.protocol = protocol.toLowerCase();
this.authority = null;
this.port = port;
this.host = host;
this.file = file;
this.ref = ref;
hashCode = hashCode(); // Used for serialization.
}
/**
* Sets the specified fields of the URL. This is not a public method so
* that only URLStreamHandlers can modify URL fields. URLs are otherwise
* constant.
*
* @since 1.3
*/
protected void set(String protocol, String host, int port,
String authority, String userInfo,
String path, String query, String ref)
{
// TBD: Theoretically, a poorly written StreamHandler could pass an
// invalid protocol. It will cause the handler to be set to null
// thus overriding a valid handler. Callers of this method should
// be aware of this.
this.handler = getURLStreamHandler(protocol);
this.protocol = protocol.toLowerCase();
if (userInfo == null)
this.host = host;
else
this.host = userInfo + "@" + host;
this.port = port;
if (query == null)
this.file = path;
else
this.file = path + "?" + query;
this.ref = ref;
hashCode = hashCode(); // Used for serialization.
}
/**
* Sets the URLStreamHandlerFactory for this class. This factory is
* responsible for returning the appropriate protocol handler for
* a given URL.
*
* @param fac The URLStreamHandlerFactory class to use
*
* @exception Error If the factory is alread set.
* @exception SecurityException If a security manager exists and its
* checkSetFactory method doesn't allow the operation
*/
public static synchronized void
setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
{
if (factory != null)
throw new Error("URLStreamHandlerFactory already set");
// Throw an exception if an extant security mgr precludes
// setting the factory.
SecurityManager s = System.getSecurityManager();
if (s != null)
s.checkSetFactory();
factory = fac;
}
/**
* Returns a String representing this URL. The String returned is
* created by calling the protocol handler's toExternalForm() method.
*
* @return A string for this URL
*/
public String toExternalForm()
{
// Identical to toString().
return handler.toExternalForm(this);
}
/**
* Returns a String representing this URL. Identical to toExternalForm().
* The value returned is created by the protocol handler's
* toExternalForm method. Overrides Object.toString()
*
* @return A string for this URL
*/
public String toString()
{
// Identical to toExternalForm().
return handler.toExternalForm(this);
}
private static synchronized URLStreamHandler
getURLStreamHandler(String protocol)
{
URLStreamHandler handler;
// See if a handler has been cached for this protocol.
if ((handler = (URLStreamHandler) handlers.get(protocol)) != null)
return handler;
// If a non-default factory has been set, use it to find the protocol.
if (factory != null)
handler = factory.createURLStreamHandler(protocol);
else if (protocol.equals ("core"))
{
handler = new gnu.gcj.protocol.core.Handler ();
}
else if (protocol.equals ("file"))
{
// This is an interesting case. It's tempting to think that we
// could call Class.forName ("gnu.gcj.protocol.file.Handler") to
// get the appropriate class. Unfortunately, if we do that the
// program will never terminate, because getURLStreamHandler is
// eventually called by Class.forName.
//
// Treating "file" as a special case is the minimum that will
// fix this problem. If other protocols are required in a
// statically linked application they will need to be handled in
// the same way as "file".
handler = new gnu.gcj.protocol.file.Handler ();
}
// Non-default factory may have returned null or a factory wasn't set.
// Use the default search algorithm to find a handler for this protocol.
if (handler == null)
{
// Get the list of packages to check and append our default handler
// to it, along with the JDK specified default as a last resort.
// Except in very unusual environments the JDK specified one shouldn't
// ever be needed (or available).
String propVal = System.getProperty("java.protocol.handler.pkgs");
propVal = (propVal == null) ? "" : (propVal + "|");
propVal = propVal + "gnu.gcj.protocol|sun.net.www.protocol";
StringTokenizer pkgPrefix = new StringTokenizer(propVal, "|");
do
{
String facName = pkgPrefix.nextToken() + "." + protocol +
".Handler";
try
{
handler =
(URLStreamHandler) Class.forName(facName).newInstance();
}
catch (Exception e)
{
// Can't instantiate; handler still null, go on to next element.
}
} while ((handler == null ||
! (handler instanceof URLStreamHandler)) &&
pkgPrefix.hasMoreTokens());
}
// Update the hashtable with the new protocol handler.
if (handler != null)
if (handler instanceof URLStreamHandler)
handlers.put(protocol, handler);
else
handler = null;
return handler;
}
private void readObject(ObjectInputStream ois)
throws IOException, ClassNotFoundException
{
ois.defaultReadObject();
this.handler = getURLStreamHandler(protocol);
if (this.handler == null)
throw new IOException("Handler for protocol " + protocol + " not found");
}
private void writeObject(ObjectOutputStream oos) throws IOException
{
oos.defaultWriteObject();
}
}