bb.net
Class UrlUtil

java.lang.Object
  extended by bb.net.UrlUtil

public final class UrlUtil
extends Object

Provides static utility methods for dealing with URLs.

This class is multithread safe: it is immutable (both its immediate state, as well as the deep state of its fields).

Author:
Brent Boyer

Nested Class Summary
static class UrlUtil.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private static int connectTimeout_default
           
private static String fileProtocol
           
private static String httpProtocol
           
private static String httpsProtocol
           
private static String mailtoProtocol
           
private static int readTimeout_default
           
 
Constructor Summary
private UrlUtil()
          This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.
 
Method Summary
private static String analyseFileUrl(URL url)
           
private static String analyseHttpUrl(URL url)
           
private static String analyseMailtoUrl(URL url)
           
private static String analyseUnsupportedUrl(URL url)
           
static String analyseUrl(URL url)
          Analyses the supplied URL.
static String description(URL url)
          Returns a string that describes every aspect of url.
static byte[] drain(URL url)
          Returns StreamUtil.drain( getInputStream(url) ).
static String drainIntoString(URL url)
          Returns StreamUtil.drainIntoString( getInputStream(url) ).
static URL extractUrl(String urlString, int lineNumber, URL context)
          First strips any quote marks from urlString via a call to removeQuotes, and then returns a new URL instance based off of urlString and context.
static URL getFileUrl(File file)
          Returns a new URL that points to file.
static InputStream getInputStream(URL url)
          Returns getInputStream( url, connectTimeout_default, readTimeout_default ).
static InputStream getInputStream(URL url, int connectTimeout, int readTimeout)
          Creates a URLConnection for url with the specified connect and read timeouts, then opens and returns an InputStream from it.
static OutputStream getOutputStream(URL url)
          Returns getOutputStream( url, connectTimeout_default, readTimeout_default ).
static OutputStream getOutputStream(URL url, int connectTimeout, int readTimeout)
          Creates a URLConnection for url with the specified connect and read timeouts, then opens and returns an OutputStream from it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

fileProtocol

private static final String fileProtocol
See Also:
Constant Field Values

httpProtocol

private static final String httpProtocol
See Also:
Constant Field Values

httpsProtocol

private static final String httpsProtocol
See Also:
Constant Field Values

mailtoProtocol

private static final String mailtoProtocol
See Also:
Constant Field Values

connectTimeout_default

private static final int connectTimeout_default
See Also:
Constant Field Values

readTimeout_default

private static final int readTimeout_default
See Also:
Constant Field Values
Constructor Detail

UrlUtil

private UrlUtil()
This sole private constructor suppresses the default (public) constructor, ensuring non-instantiability outside of this class.

Method Detail

getFileUrl

public static URL getFileUrl(File file)
                      throws IllegalArgumentException,
                             MalformedURLException
Returns a new URL that points to file.

Throws:
IllegalArgumentException - if file == null
MalformedURLException - if file's path cannot be parsed into a proper URL specification

extractUrl

public static URL extractUrl(String urlString,
                             int lineNumber,
                             URL context)
                      throws IllegalArgumentException,
                             ParseException,
                             MalformedURLException
First strips any quote marks from urlString via a call to removeQuotes, and then returns a new URL instance based off of urlString and context.

Parameters:
urlString - a String which should specify a URL
lineNumber - the line number where urlString is found; used only if throw a ParseException
context - the context URL; used to resolve relative URLs; may be null if is not to be specified
Throws:
IllegalArgumentException - if urlString is null, or lineNumber < 0
ParseException - if a leading but no matching trailing quote mark is present, or vice versa, on urlString
MalformedURLException - if urlString cannot be parsed into a proper URL specification

drain

public static byte[] drain(URL url)
                    throws IllegalArgumentException,
                           IllegalStateException,
                           IOException,
                           UnknownServiceException
Returns StreamUtil.drain( getInputStream(url) ).

Throws:
IllegalArgumentException - if url == null
IllegalStateException - if url's inputStream turns out to hold more than Integer.MAX_VALUE bytes (which cannot be held in a java array)
IOException - if an I/O problem occurs
UnknownServiceException - if the protocol does not support input

drainIntoString

public static String drainIntoString(URL url)
                              throws IllegalArgumentException,
                                     IllegalStateException,
                                     IOException,
                                     UnknownServiceException
Returns StreamUtil.drainIntoString( getInputStream(url) ).

Throws:
IllegalArgumentException - if url == null
IllegalStateException - if url's inputStream turns out to hold more than Integer.MAX_VALUE bytes (which cannot be held in a java array)
IOException - if an I/O problem occurs
UnknownServiceException - if the protocol does not support input

getInputStream

public static InputStream getInputStream(URL url)
                                  throws IllegalArgumentException,
                                         IOException,
                                         UnknownServiceException
Returns getInputStream( url, connectTimeout_default, readTimeout_default ).

Throws:
IllegalArgumentException
IOException
UnknownServiceException

getInputStream

public static InputStream getInputStream(URL url,
                                         int connectTimeout,
                                         int readTimeout)
                                  throws IllegalArgumentException,
                                         IOException,
                                         UnknownServiceException
Creates a URLConnection for url with the specified connect and read timeouts, then opens and returns an InputStream from it.

Throws:
IllegalArgumentException - if url == null; connectTimeout or readTimeout is < 0
IOException - if an I/O problem occurs
UnknownServiceException - if the protocol does not support input

getOutputStream

public static OutputStream getOutputStream(URL url)
                                    throws IllegalArgumentException,
                                           IOException,
                                           UnknownServiceException
Returns getOutputStream( url, connectTimeout_default, readTimeout_default ).

Throws:
IllegalArgumentException
IOException
UnknownServiceException

getOutputStream

public static OutputStream getOutputStream(URL url,
                                           int connectTimeout,
                                           int readTimeout)
                                    throws IllegalArgumentException,
                                           IOException,
                                           UnknownServiceException
Creates a URLConnection for url with the specified connect and read timeouts, then opens and returns an OutputStream from it.

Throws:
IllegalArgumentException - if url == null; connectTimeout or readTimeout is < 0
IOException - if an I/O problem occurs
UnknownServiceException - if the protocol does not support input

analyseUrl

public static String analyseUrl(URL url)
                         throws IllegalArgumentException
Analyses the supplied URL. The exact analysis performed is completely protocol dependent, but it typically involves trying to follow the link and see if valid data is on the other end.

Parameters:
url - the URL to analyse
Throws:
IllegalArgumentException - if url == null
See Also:
List of some protocols, RFC2396 Uniform Resource Identifiers (URI): Generic Syntax

analyseFileUrl

private static String analyseFileUrl(URL url)

analyseHttpUrl

private static String analyseHttpUrl(URL url)

analyseMailtoUrl

private static String analyseMailtoUrl(URL url)

analyseUnsupportedUrl

private static String analyseUnsupportedUrl(URL url)

description

public static String description(URL url)
                          throws IllegalArgumentException
Returns a string that describes every aspect of url.

Parameters:
url - a URL
Throws:
IllegalArgumentException - if url == null