org.apache.batik.util

Class ParsedURL

public class ParsedURL extends Object

This class is used as a replacement for java.net.URL. This is done for several reasons. First unlike java.net.URL this class will accept and parse as much of a URL as possible, without throwing a MalformedURL exception. This makes it extreamly useful for simply parsing a URL string (hence it's name). Second it allows for extension of the protocols supported by the URL parser. Batik uses this to support the 'Data' protocol. Third by default it checks the streams that it opens to see if they are GZIP compressed, if so it automatically uncompresses them (avoiding opening the stream twice in the processes). It is worth noting that most real work is defered to the ParsedURLData class to which most methods are forwarded. This is done because it allows a constructor interface to ParsedURL (mostly for compatability with core URL), in spite of the fact that the real implemenation uses the protocol handlers as factories for protocol specific instances of the ParsedURLData class.

Constructor Summary
	ParsedURL(String urlStr) Construct a ParsedURL from the given url string.
	ParsedURL(URL url) Construct a ParsedURL from the given java.net.URL instance.
	ParsedURL(String baseStr, String urlStr) Construct a sub URL from two strings.
	ParsedURL(URL baseURL, String urlStr) Construct a sub URL from a base URL and a string for the sub url.
	ParsedURL(ParsedURL baseURL, String urlStr) Construct a sub URL from a base ParsedURL and a string for the sub url.

Method Summary
static InputStream	checkGZIP(InputStream is) This is a utility function others can call that checks if is is a GZIP stream if so it returns a GZIPInputStream that will decode the contents, otherwise it returns (or a buffered version of is) untouched.
boolean	complete() Returns true if the URL looks well formed and complete.
boolean	equals(Object obj) Implement Object.equals.
String	getContentEncoding() Returns the content encoding if available.
String	getContentType() Returns the content type if available.
String	getContentTypeCharset() Returns the content type's charset parameter, if available.
String	getContentTypeMediaType() Returns the content type's type/subtype, if available.
static String	getGlobalUserAgent()
static ParsedURLProtocolHandler	getHandler(String protocol) Returns the handler for a particular protocol.
String	getHost() Returns the host for this URL, if any, `null` if there isn't one or it doesn't make sense for the protocol.
String	getPath() Returns the path for this URL, if any (where appropriate for the protocol this also includes the file, not just directory).
int	getPort() Returns the port on the host to connect to, if it was specified in the url that was parsed, otherwise returns -1.
String	getPortStr() Returns the URL up to and include the port number on the host.
String	getProtocol() Returns the protocol for this URL.
protected static String	getProtocol(String urlStr) Parse out the protocol from a url string.
String	getRef() Returns the 'fragment' reference in the URL.
String	getUserAgent() Return the user agent current associated with this url (or null if none).
boolean	hasContentTypeParameter(String param) Returns whether the Content-Type header has the given parameter.
int	hashCode() Implement Object.hashCode.
InputStream	openStream() Attempt to open the stream checking for common compression types, and automatically decompressing them if found.
InputStream	openStream(String mimeType) Attempt to open the stream checking for common compression types, and automatically decompressing them if found.
InputStream	openStream(String[] mimeTypes) Attempt to open the stream checking for common compression types, and automatically decompressing them if found.
InputStream	openStream(Iterator mimeTypes) Attempt to open the stream checking for common compression types, and automatically decompressing them if found.
InputStream	openStreamRaw() Attempt to open the stream, does no checking for compression types.
InputStream	openStreamRaw(String mimeType) Attempt to open the stream, does no checking for compression types.
InputStream	openStreamRaw(String[] mimeTypes) Attempt to open the stream, does no checking for comression types.
InputStream	openStreamRaw(Iterator mimeTypes) Attempt to open the stream, does no checking for comression types.
static ParsedURLData	parseURL(String urlStr) Factory method to construct an appropriate subclass of ParsedURLData
static ParsedURLData	parseURL(String baseStr, String urlStr) Factory method to construct an appropriate subclass of ParsedURLData, for a sub url.
static ParsedURLData	parseURL(ParsedURL baseURL, String urlStr) Factory method to construct an appropriate subclass of ParsedURLData, for a sub url.
static void	registerHandler(ParsedURLProtocolHandler handler) Registers a Protocol handler by adding it to the handlers map.
boolean	sameFile(ParsedURL other)
static void	setGlobalUserAgent(String userAgent)
void	setUserAgent(String userAgent) Sets the user agent associated with this url (null clears any associated user agent).
String	toString() Return a string rep of the URL (can be passed back into the constructor if desired).

Constructor Detail

ParsedURL

public ParsedURL(String urlStr)

Construct a ParsedURL from the given url string.

Parameters: urlStr The string to try and parse as a URL

ParsedURL

public ParsedURL(URL url)

Construct a ParsedURL from the given java.net.URL instance. This is useful if you already have a valid java.net.URL instance. This bypasses most of the parsing and hence is quicker and less prone to reinterpretation than converting the URL to a string before construction.

Parameters: url The URL to "mimic".

ParsedURL

public ParsedURL(String baseStr, String urlStr)

Construct a sub URL from two strings.

Parameters: baseStr The 'parent' URL. Should be complete. urlStr The 'sub' URL may be complete or partial. the missing pieces will be taken from the baseStr.

ParsedURL

public ParsedURL(URL baseURL, String urlStr)

Construct a sub URL from a base URL and a string for the sub url.

Parameters: baseURL The 'parent' URL. urlStr The 'sub' URL may be complete or partial. the missing pieces will be taken from the baseURL.

ParsedURL

public ParsedURL(ParsedURL baseURL, String urlStr)

Construct a sub URL from a base ParsedURL and a string for the sub url.

Parameters: baseURL The 'parent' URL. urlStr The 'sub' URL may be complete or partial. the missing pieces will be taken from the baseURL.

Method Detail

checkGZIP

public static InputStream checkGZIP(InputStream is)

This is a utility function others can call that checks if is is a GZIP stream if so it returns a GZIPInputStream that will decode the contents, otherwise it returns (or a buffered version of is) untouched.

Parameters: is Stream that may potentially be a GZIP stream.

complete

public boolean complete()

Returns true if the URL looks well formed and complete. This does not garuntee that the stream can be opened but is a good indication that things aren't totally messed up.

equals

public boolean equals(Object obj)

Implement Object.equals. Relies heavily on the contained ParsedURLData's implementation of equals.

getContentEncoding

public String getContentEncoding()

Returns the content encoding if available. This is only available for some protocols.

getContentType

public String getContentType()

Returns the content type if available. This is only available for some protocols.

getContentTypeCharset

public String getContentTypeCharset()

Returns the content type's charset parameter, if available. This is only available for some protocols.

getContentTypeMediaType

public String getContentTypeMediaType()

Returns the content type's type/subtype, if available. This is only available for some protocols.

getGlobalUserAgent

public static String getGlobalUserAgent()

getHandler

public static ParsedURLProtocolHandler getHandler(String protocol)

Returns the handler for a particular protocol. If protocol is null or no match is found in the handlers map it returns the default protocol handler.

Parameters: protocol The protocol to get a handler for.

getHost

public String getHost()

Returns the host for this URL, if any, null if there isn't one or it doesn't make sense for the protocol.

getPath

public String getPath()

Returns the path for this URL, if any (where appropriate for the protocol this also includes the file, not just directory). Note that getPath appears in JDK 1.3 as a synonym for getFile from JDK 1.2.

getPort

public int getPort()

Returns the port on the host to connect to, if it was specified in the url that was parsed, otherwise returns -1.

getPortStr

public String getPortStr()

Returns the URL up to and include the port number on the host. Does not include the path or fragment pieces.

getProtocol

public String getProtocol()

Returns the protocol for this URL. The protocol is everything upto the first ':'.

getProtocol

protected static String getProtocol(String urlStr)

Parse out the protocol from a url string. Used internally to select the proper handler, all other parsing is done by the selected protocol handler.

getRef

public String getRef()

Returns the 'fragment' reference in the URL.

getUserAgent

public String getUserAgent()

Return the user agent current associated with this url (or null if none).

hasContentTypeParameter

public boolean hasContentTypeParameter(String param)

Returns whether the Content-Type header has the given parameter.

hashCode

public int hashCode()

Implement Object.hashCode. Relies on the contained ParsedURLData's implementation of hashCode.

openStream

public InputStream openStream()

Attempt to open the stream checking for common compression types, and automatically decompressing them if found.

openStream

public InputStream openStream(String mimeType)

Attempt to open the stream checking for common compression types, and automatically decompressing them if found.

Parameters: mimeType The expected mime type of the content in the returned InputStream (mapped to Http accept header among other possabilities).

openStream

public InputStream openStream(String[] mimeTypes)

Attempt to open the stream checking for common compression types, and automatically decompressing them if found.

Parameters: mimeTypes The expected mime types of the content in the returned InputStream (mapped to Http accept header among other possabilities).

openStream

public InputStream openStream(Iterator mimeTypes)

Attempt to open the stream checking for common compression types, and automatically decompressing them if found.

Parameters: mimeTypes The expected mime types of the content in the returned InputStream (mapped to Http accept header among other possabilities). The elements of the iterator must be strings.

openStreamRaw

public InputStream openStreamRaw()

Attempt to open the stream, does no checking for compression types.

openStreamRaw

public InputStream openStreamRaw(String mimeType)

Attempt to open the stream, does no checking for compression types.

Parameters: mimeType The expected mime type of the content in the returned InputStream (mapped to Http accept header among other possabilities).

openStreamRaw

public InputStream openStreamRaw(String[] mimeTypes)

Attempt to open the stream, does no checking for comression types.

Parameters: mimeTypes The expected mime types of the content in the returned InputStream (mapped to Http accept header among other possabilities).

openStreamRaw

public InputStream openStreamRaw(Iterator mimeTypes)

Attempt to open the stream, does no checking for comression types.

Parameters: mimeTypes The expected mime types of the content in the returned InputStream (mapped to Http accept header among other possabilities). The elements of the iterator must be strings.

parseURL

public static ParsedURLData parseURL(String urlStr)

Factory method to construct an appropriate subclass of ParsedURLData

Parameters: urlStr the string to parse.

parseURL

public static ParsedURLData parseURL(String baseStr, String urlStr)

Factory method to construct an appropriate subclass of ParsedURLData, for a sub url.

Parameters: baseStr The base URL string to parse. urlStr the sub URL string to parse.

parseURL

public static ParsedURLData parseURL(ParsedURL baseURL, String urlStr)

Factory method to construct an appropriate subclass of ParsedURLData, for a sub url.

Parameters: baseURL The base ParsedURL to parse. urlStr the sub URL string to parse.

registerHandler

public static void registerHandler(ParsedURLProtocolHandler handler)

Registers a Protocol handler by adding it to the handlers map. If the given protocol handler returns null as it's supported protocol then it is registered as the default protocol handler.

Parameters: handler the new Protocol Handler to register