org.dlese.dpc.util
Class TimedURLConnection

java.lang.Object
  org.dlese.dpc.util.TimedURLConnection

public class TimedURLConnection
extends Object

A URLConnection wrapper that allows a connection timeout to be set, support for gzip streaming, GET and POST data. A timout is useful for applications that need to retrieve content from a URL without hanging if the remote server does not respond within a given period of time. Throws a URLConnectionTimedOutException if the connection is not made within the allotted time or a IOException if the connection fails for some other reason, such as an HTTP type 500 or 403 error.

The static methods importURL(java.lang.String, int) and getInputStream(java.lang.String, int) are provided for convenience.

Example that uses the static getInputStream method:

import org.dlese.dpc.util.TimedURLConnection;
import org.dlese.dpc.util.URLConnectionTimedOutException;
import org.dom4j.Document;
import org.dom4j.DocumentException;
import org.dom4j.io.SAXReader;
// Plus other imports...

try {


// Get an input stream for the remote content (throws exeception if timeout occurs):
InputStream istm = TimedURLConnection.getInputStream("http://example.org/remoteData.xml", 2000);

// Process the InputStream as desired. In this example, the InputStream is used to create a dom4j XML DOM:
...
try{
SAXReader reader = new SAXReader();
Document document = reader.read(istm);
} catch ( DocumentException e ) {
// Handle the Exception as desired...
}

// Now the DOM is ready for use...
...

} catch (URLConnectionTimedOutException exc) {
// The URLConnection timed out...
} catch (IOException ioe) {
// The URLConnection threw an IOException while attempting to connect...
}


Version:

$Id: TimedURLConnection.java,v 1.16 2010/08/18 18:21:04 jweather Exp $

Author:

John Weatherley

See Also:

URLConnection

Constructor Summary

TimedURLConnection()

Method Summary

static InputStream	getInputStream(String url, int timeOutPeriod) Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds.
static InputStream	getInputStream(URL url, int timeOutPeriod) Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds.
static InputStream	getInputStream(URL url, String postData, int timeOutPeriod) Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds.
static long	getUrlLastModifiedTime(URL url, int timeOutPeriod) Gets the last modified time of the URL, timing out if the remote server does not respond within the given number of milliseconds.
static String	importURL(String url, int timeOutPeriod) Imports the content of a given URL into a String using the default character encoding, timing out if the remote server does not respond within the given number of milliseconds.
static String	importURL(String url, String characterEncoding, int timeOutPeriod) Imports the content of a given URL into a String using the given character encoding timing out if the remote server does not respond within the given number of milliseconds.
static String	importURL(String url, String postData, String characterEncoding, int timeOutPeriod) Imports the content of a given URL into a String using the given character encoding, using POST data if indicated or GET, timing out if the remote server does not respond within the given number of milliseconds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimedURLConnection

public TimedURLConnection()

Method Detail

importURL

public static String importURL(String url,
                               int timeOutPeriod)
                        throws IOException,
                               URLConnectionTimedOutException

Imports the content of a given URL into a String using the default character encoding, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). If the connection is http, then redirects are followed. Uses gzip encoding if the server supports it. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

Returns:

A String containing the contents of the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

importURL

public static String importURL(String url,
                               String characterEncoding,
                               int timeOutPeriod)
                        throws IOException,
                               URLConnectionTimedOutException

Imports the content of a given URL into a String using the given character encoding timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). If the connection is http, then redirects are followed. Uses gzip encoding if the server supports it. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

characterEncoding - The character encoding to use, for example 'UTF-8'

Returns:

A String containing the contents of the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

importURL

public static String importURL(String url,
                               String postData,
                               String characterEncoding,
                               int timeOutPeriod)
                        throws IOException,
                               URLConnectionTimedOutException

Imports the content of a given URL into a String using the given character encoding, using POST data if indicated or GET, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). If the connection is http, then redirects are followed. Uses gzip encoding if the server supports it. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

characterEncoding - The character encoding to use, for example 'UTF-8'

postData - Data to POST in the request of the form parm1=value1&param2=value2 or null to use GET (pass all params in the url)

Returns:

A String containing the contents of the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

getInputStream

public static InputStream getInputStream(String url,
                                         int timeOutPeriod)
                                  throws IOException,
                                         URLConnectionTimedOutException

Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). Supports gzip compression (returns a GZIPInputStream if the server supports it). If the connection is http, then redirects are followed. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

Returns:

An InputStream for the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

getInputStream

public static InputStream getInputStream(URL url,
                                         int timeOutPeriod)
                                  throws IOException,
                                         URLConnectionTimedOutException

Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). Supports gzip compression (returns a GZIPInputStream if the server supports it). If the connection is http, then redirects are followed. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

Returns:

An InputStream for the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

getInputStream

public static InputStream getInputStream(URL url,
                                         String postData,
                                         int timeOutPeriod)
                                  throws IOException,
                                         URLConnectionTimedOutException

Gets an InputStream for the given URL, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). Supports gzip compression (returns a GZIPInputStream if the server supports it). If the connection is http, then redirects are followed. Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to import

timeOutPeriod - Milliseconds to wait before timing out

postData - Data to POST in the request of the form parm1=value1&param2=value2 or null to use GET (pass all params in the url)

Returns:

An InputStream for the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds

getUrlLastModifiedTime

public static long getUrlLastModifiedTime(URL url,
                                          int timeOutPeriod)
                                   throws IOException,
                                          URLConnectionTimedOutException

Gets the last modified time of the URL, timing out if the remote server does not respond within the given number of milliseconds. A timeout set to 0 disables the timeout (e.g. timeout of infinity). Throws an IOException if an http connection returns something other than status 200.

Parameters:

url - The URL to check

timeOutPeriod - Milliseconds to wait before timing out

Returns:

The last modified time of the URL

Throws:

IOException - If IO Error

URLConnectionTimedOutException - If timeout occurs before the server responds