com.cleancode.net
Class UrlConnectionMgr

java.lang.Object
  com.cleancode.net.UrlConnectionMgr

public class UrlConnectionMgr
extends Object

UrlConnectionMgr retrieves a URL from the World Wide Web and provides a formatted breakdown of its components. One may request individual component data regarding:

• the network connection
• the URL itself
• the HTTP header
• the cookies
• the HTML structure

After instantiating a UrlConnectionMgr, one should first call sendCookies if there are any cookies to send. Then, invoke connect() to open the URL connection, and finally call getComponent(int) or getContent() as needed. The getComponent method is used to retrieve a component. Data is returned as a two-dimensional array, suitable for pasting into a table. The getContent method is used to retrieve the actual contents of the web page (or other appropriate entity).

There are a few utility methods which are static. buildCookie(java.lang.String, java.lang.String) and parseCookie(java.lang.String) are complementary functions for interfacing with cookies. getBasicURL(java.lang.String) may be used to strip off the query portion of a URL. getGeneralWidths(), getGeneralNames(), getCookieWidths() and getCookieNames() are support methods for setting up tables containing the returned data.

Since:

CleanCode 0.9

Version:

$Revision: 9 $

Author:

Michael Sorens

See Also:

URL, URLConnection

Nested Class Summary

static class

UrlConnectionMgr.Test A standalone test class.

Field Summary

static int	CONNECTION_DATA Selects info about the network connection.
static int	COOKIE_DATA Selects info about the transaction cookies.
static int	HEADER_DATA Selects info about the transaction header.
static int	HTML_DATA Selects info about the web page.
static int	URL_DATA Selects info about the URL.
static String	VERSION Current version of this class.

Constructor Summary

UrlConnectionMgr(String urlString)
Constructs a UrlConnectionMgr for the specified URL string.

Method Summary

static String	buildCookie(String name, String value) Construct a properly formatted cookie for transmission.
void	connect() Opens a communications link to the resource referenced by this URL, if such a connection has not already been established.
static String	getBasicURL(String urlString) Extracts the basic URL (without the query portion) from a complete URL.
String[][]	getComponent(int choice) Returns a portion of a network transaction.
String	getContent() Returns the contents of a URL, typically an HTML document.
static String[]	getCookieNames() Returns column names for cookie URL data.
static float[]	getCookieWidths() Returns relative column widths for cookie URL data.
static String[]	getGeneralNames() Returns column names for general URL data.
static float[]	getGeneralWidths() Returns relative column widths for general URL data.
static boolean	isCookie(String s) Returns true if the string could be a cookie (recognized by the presence of the cookie assignment operator and lack of line feed/carriage returns).
static String[]	parseCookie(String cookie) Parse a received cookie into its components.
String	post(String postData) Does an HTTP POST on a single line of text.
String	post(String[] postData) Does an HTTP POST on multiple lines of text.
void	sendCookie(String cookie) Send a single cookie through a URLConnection.
void	sendCookies(String[] cookies) Send multiple cookies through a URLConnection.
void	sendUserAgent(String agent) Send a user-agent request field through a URLConnection.

Methods inherited from class java.lang.Object

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

Field Detail

CONNECTION_DATA

public static final int CONNECTION_DATA

Selects info about the network connection. Used as an argument to getComponent(int) which will return: URL as known, input allowed, output allowed, user interaction, and uses cache. If the protocol is HTTP, these will additionally be returned: HTTP request method, HTTP response message, and HTTP response code.

See Also:

Constant Field Values

URL_DATA

public static final int URL_DATA

Selects info about the URL. Used as an argument to getComponent(int) which will return: authority, host, file, path, port, query, anchor, userinfo, and protocol.

See Also:

Constant Field Values

HEADER_DATA

public static final int HEADER_DATA

Selects info about the transaction header. Used as an argument to getComponent(int) which will return: HTTP response, date, server, content-type, content-length, set-cookie, cache-control, accept-ranges, keep-alive, connection, expires, and others. All of these are optional so any given web document may or may not have a particular one.

See Also:

HTTP Definition (RFC), HTTP Specifications and Drafts, Constant Field Values

COOKIE_DATA

public static final int COOKIE_DATA

Selects info about the transaction cookies. Used as an argument to getComponent(int) which will return: a list of cookies.

See Also:

parseCookie, Constant Field Values

HTML_DATA

public static final int HTML_DATA

Selects info about the web page. Used as an argument to getComponent(int) which will return: meta tags, links, document title, document type definition, and include files.

See Also:

SimpleHtmlParse, Constant Field Values

VERSION

public static final String VERSION

Current version of this class.

Constructor Detail

UrlConnectionMgr

public UrlConnectionMgr(String urlString)
                 throws IOException

Constructs a UrlConnectionMgr for the specified URL string.

Parameters:

urlString - a String representing the URL to connect to

Throws:

IOException - if an I/O error occurs while opening the connection

Method Detail

post

public String post(String[] postData)
            throws IOException

Does an HTTP POST on multiple lines of text.

Parameters:

postData - array of text lines to POST

Returns:

web server response as a string

Throws:

IOException - if problems reading or writing on the connection.

post

public String post(String postData)
            throws IOException

Does an HTTP POST on a single line of text.

Parameters:

postData - text line to POST

Returns:

web server response as a string

Throws:

IOException - if problems reading or writing on the connection.

connect

public void connect()
             throws IOException

Opens a communications link to the resource referenced by this URL, if such a connection has not already been established. This is simply a convenience method to invoke the connect method of the embedded URLConnection.

Throws:

IOException - if an I/O error occurs while opening the connection

getContent

public String getContent()
                  throws IOException

Returns the contents of a URL, typically an HTML document. Content is cached so repeated calls simply return the same content without going to the network.

Returns:

contents of a URL as a single String

Throws:

IOException - if an I/O error occurs while reading from the input stream

getComponent

public String[][] getComponent(int choice)
                        throws IOException

Returns a portion of a network transaction. The choice parameter may be one of: CONNECTION_DATA, URL_DATA, HEADER_DATA, COOKIE_DATA, or HTML_DATA. Any other values will return an empty string.

Parameters:

choice - specifies the portion of the network transaction

Returns:

table of network transaction data

Throws:

IOException - if an I/O error occurs while reading URL data

sendCookies

public void sendCookies(String[] cookies)

Send multiple cookies through a URLConnection.

Parameters:

cookies - an array of properly formatted cookies The method buildCookie may be used to create cookies.

sendCookie

public void sendCookie(String cookie)

Send a single cookie through a URLConnection.

Parameters:

cookie - a properly formatted cookie The method buildCookie may be used to create cookies.

sendUserAgent

public void sendUserAgent(String agent)

Send a user-agent request field through a URLConnection.

Parameters:

agent - a properly formatted user-agent

buildCookie

public static String buildCookie(String name,
                                 String value)

Construct a properly formatted cookie for transmission.

Parameters:

name - name of the cookie parameter

value - value of the cookie parameter

Returns:

a formatted cookie

parseCookie

public static String[] parseCookie(String cookie)

Parse a received cookie into its components. A received cookie consists of:

• name - name of the cookie;
• value - value of the cookie;
• path - specifies the subset of URLs in a domain for which the cookie is valid;
• expiry - specifies a date string that defines the valid life time of that cookie.
• domain - Internet domain name of the host from which the URL will be fetched;
• secure - if present, cookie will only be transmitted if the communications channel with the host is a secure one.

The name and value are always present; other attributes are optional.

Parameters:

cookie - a properly formatted cookie

Returns:

a String array (name, val, domain, path, expiry, secure); (absent attributes are set to the empty string).

See Also:

Cookie Spec

getBasicURL

public static String getBasicURL(String urlString)

Extracts the basic URL (without the query portion) from a complete URL.

Parameters:

urlString - a String representing the URL to connect to

Returns:

the basic URL for the specified URL

getGeneralNames

public static String[] getGeneralNames()

Returns column names for general URL data. General data consists of just a parameter and a value as compared to cookie data which has more columns.

Returns:

array of column names for general data

getGeneralWidths

public static float[] getGeneralWidths()

Returns relative column widths for general URL data. General data consists of just a parameter and a value as compared to cookie data which has more columns.

Returns:

array of relative column widths for general data

See Also:

getGeneralNames()

getCookieNames

public static String[] getCookieNames()

Returns column names for cookie URL data.

Returns:

array of column names for cookie data

See Also:

parseCookie(java.lang.String)

getCookieWidths

public static float[] getCookieWidths()

Returns relative column widths for cookie URL data.

Returns:

array of relative column widths for cookie URL data

See Also:

parseCookie(java.lang.String), getGeneralNames()

isCookie

public static boolean isCookie(String s)

Returns true if the string could be a cookie (recognized by the presence of the cookie assignment operator and lack of line feed/carriage returns).

Parameters:

s - String to test for "cookie-ness"

Returns:

boolean indicating whether string could be a cookie