|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.net.URL
public final class URL
This final class represents an Internet Uniform Resource Locator (URL). For details on the syntax of URL's and what they can be used for, refer to RFC 1738, available from http://ds.internic.net/rfcs/rfc1738.txt
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 ".<protocol>.Handler" to each packed in the list until a hander is found. If a protocol handler is not found in this list of packages, or if the property does not exist, then the default protocol handler of "gnu.java.net.<protocol>.Handler" is tried. If this is unsuccessful, a MalformedURLException is thrown.
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:
com.foo.news.Handler com.bar.news.Handler gnu.java.net.news.Handler
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.
Normally, this class caches protocol handlers. Once it finds a handler for a particular protocol, it never tries to look up a new handler again. However, if the system property gnu.java.net.nocache_protocol_handlers is set, then this caching behavior is disabled. This property is specific to this implementation. Sun's JDK may or may not do protocol caching, but it almost certainly does not examine this property.
Please also note that an application can install its own factory for loading protocol handlers (see setURLStreamHandlerFactory). If this is done, then the above information is superseded and the behavior of this class in loading protocol handlers is dependent on that factory.
URLStreamHandler
,
Serialized FormConstructor Summary | |
---|---|
URL(String spec)
Initializes a URL from a complete string specification such as "http://www.urbanophile.com/arenn/". |
|
URL(String protocol,
String host,
int port,
String file)
Constructs a URL and loads a protocol handler for the values passed as arguments. |
|
URL(String protocol,
String host,
int port,
String file,
URLStreamHandler ph)
This method initializes a new instance of URL with the
specified protocol, host, port, and file. |
|
URL(String protocol,
String host,
String file)
Constructs a URL and loads a protocol handler for the values passed in as arugments. |
|
URL(URL context,
String spec)
This method parses a String representation of a URL within the context of an existing URL. |
|
URL(URL context,
String spec,
URLStreamHandler ph)
Creates an URL from given arguments This method parses a String representation of a URL within the context of an existing URL. |
Method Summary | |
---|---|
boolean |
equals(Object obj)
Test another URL for equality with this one. |
String |
getAuthority()
Returns the authority of the URL |
Object |
getContent()
Returns the contents of this URL as an object by first opening a connection, then calling the getContent() method against the connection |
Object |
getContent(Class[] classes)
Gets the contents of this URL |
int |
getDefaultPort()
Returns the default port of the URL. |
String |
getFile()
Returns the file portion of the URL. |
String |
getHost()
Returns the host of the URL |
String |
getPath()
Returns the path of the URL. |
int |
getPort()
Returns the port number of this URL or -1 if the default port number is being used. |
String |
getProtocol()
Returns the protocol of the URL |
String |
getQuery()
Returns the query of the URL. |
String |
getRef()
Returns the ref (sometimes called the "# reference" or "anchor") portion of the URL. |
String |
getUserInfo()
Returns the user information of the URL. |
int |
hashCode()
Returns a hashcode computed by the URLStreamHandler of this URL |
URLConnection |
openConnection()
Returns a URLConnection object that represents a connection to the remote object referred to by the URL. |
InputStream |
openStream()
Opens a connection to this URL and returns an InputStream for reading from that connection |
boolean |
sameFile(URL url)
Tests whether or not another URL refers to the same "file" as this one. |
protected void |
set(String protocol,
String host,
int port,
String file,
String ref)
Sets the specified fields of the URL. |
protected void |
set(String protocol,
String host,
int port,
String authority,
String userInfo,
String path,
String query,
String ref)
Sets the specified fields of the URL. |
static void |
setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
Sets the URLStreamHandlerFactory for this class. |
String |
toExternalForm()
Returns a String representing this URL. |
String |
toString()
Returns a String representing this URL. |
URI |
toURI()
Returns the equivalent URI object for this URL . |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public URL(String protocol, String host, int port, String file) throws MalformedURLException
protocol
- The protocol for this URL ("http", "ftp", etc)host
- The hostname or IP address to connect toport
- The port number to use, or -1 to use the protocol's
default portfile
- The "file" portion of the URL.
MalformedURLException
- If a protocol handler cannot be loaded or
a parse error occurs.public URL(String protocol, String host, String file) throws MalformedURLException
protocol
- The protocol for this URL ("http", "ftp", etc)host
- The hostname or IP address for this URLfile
- The "file" portion of this URL.
MalformedURLException
- If a protocol handler cannot be loaded or
a parse error occurs.public URL(String protocol, String host, int port, String file, URLStreamHandler ph) throws MalformedURLException
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.
protocol
- The protocol for this URL ("http", "ftp", etc)host
- The hostname or IP address to connect toport
- The port number to use, or -1 to use the protocol's default
portfile
- The "file" portion of the URL.ph
- The protocol handler to use with this URL.
MalformedURLException
- If no protocol handler can be loaded
for the specified protocol.
SecurityException
- If the SecurityManager
exists
and does not allow the caller to specify its own protocol handler.public URL(String spec) throws MalformedURLException
spec
- The complete String representation of a URL
MalformedURLException
- If a protocol handler cannot be found
or the URL cannot be parsedpublic URL(URL context, String spec) throws MalformedURLException
context
- The context on which to parse the specificationspec
- The string to parse an URL
MalformedURLException
- If a protocol handler cannot be found
for the URL cannot be parsedpublic URL(URL context, String spec, URLStreamHandler ph) throws MalformedURLException
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.
context
- The context in which to parse the specificationspec
- The string to parse as an URLph
- The stream handler for the URL
MalformedURLException
- If a protocol handler cannot be found
or the URL cannot be parsed
SecurityException
- If the SecurityManager
exists
and does not allow the caller to specify its own protocol handler.Method Detail |
---|
public boolean equals(Object obj)
equals
in class Object
obj
- The URL to compare with
Object.hashCode()
public Object getContent() throws IOException
IOException
- If opening the connection or getting the
content fails.public Object getContent(Class[] classes) throws IOException
classes
- The allow classes for the content object.
IOException
- If an error occurspublic String getFile()
path[?query]
.
Returns the empty string if there is no file portion.
public String getPath()
public String getAuthority()
public String getHost()
public int getPort()
getDefaultPort()
public int getDefaultPort()
public String getProtocol()
public String getRef()
public String getUserInfo()
public String getQuery()
public int hashCode()
hashCode
in class Object
Object.equals(Object)
,
System.identityHashCode(Object)
public URLConnection openConnection() throws IOException
IOException
- If an error occurspublic InputStream openStream() throws IOException
InputStream
for this URL.
IOException
- If an error occurspublic boolean sameFile(URL url)
url
- The URL object to test with
protected void set(String protocol, String host, int port, String file, String ref)
parseURL()
method in that class. URLs are otherwise
constant. If the given protocol does not exist, it will keep the previously
set protocol.
protocol
- The protocol name for this URLhost
- The hostname or IP address for this URLport
- The port number of this URLfile
- The "file" portion of this URL.ref
- The anchor portion of this URL.protected void set(String protocol, String host, int port, String authority, String userInfo, String path, String query, String ref)
protocol
- The protocol name for this URL.host
- The hostname or IP address for this URL.port
- The port number of this URL.authority
- The authority of this URL.userInfo
- The user and password (if needed) of this URL.path
- The "path" portion of this URL.query
- The query of this URL.ref
- The anchor portion of this URL.public static void setURLStreamHandlerFactory(URLStreamHandlerFactory fac)
fac
- The URLStreamHandlerFactory class to use
Error
- If the factory is alread set.
SecurityException
- If a security manager exists and its
checkSetFactory method doesn't allow the operationpublic String toExternalForm()
public String toString()
toString
in class Object
Object.getClass()
,
Object.hashCode()
,
Class.getName()
,
Integer.toHexString(int)
public URI toURI() throws URISyntaxException
URI
object for this URL
.
This is the same as calling new URI(this.toString())
.
RFC2396-compliant URLs are guaranteed a successful conversion to
a URI
instance. However, there are some values which
form valid URLs, but which do not also form RFC2396-compliant URIs.
URISyntaxException
- if this URL is not RFC2396-compliant,
and thus can not be successfully converted to a URI.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |