com.zenkey.net.prowser
Class Prowser

java.lang.Object
  com.zenkey.net.prowser.Prowser

public class Prowser
extends Object

The Prowser class serves as the creator and owner of one or more Tab instances whose job it is to perform web page requests. You can think of a Prowser object as a running instance of a web browser application, while the Tab objects that it owns represent the tabbed windows in which pages are actually retrieved.

Each Tab of a Prowser operates independently, maintaining individual (i.e., local) state data like current page information and browsing history. However, all Tabs owned by a particular Prowser also share a common set of global state data maintained by that Prowser. This simulates the way mainstream tabbed browsers (like Firefox) operate: one browser, with multiple tabs, all sharing various pieces of browser-wide state information. For Prowser, this global state data includes cookies, default configuration properties, and the home page (if any).

As an example, Prowser's cookie sharing functionality can allow an applicaiton to use one Tab for logging into a web account (and keeping the login session alive, perhaps in a concurrent thread or a TimerTask), while other Tabs perform actions on that account -- without having to log into separate sessions. If an application ever needs Tabs that do not share cookies ( e.g., to log into multiple accounts on the same service), it can simply use multiple Prowser instances.

A Prowser object is safe to use in multiple concurrent threads.

Version:

$Revision: 1.2 $, $Date: 2006/02/21 19:48:16 $

See Also:

Request, Response

Constructor Summary

Prowser()
Constructs a new Prowser object with a preset default configuration and no home page.

Prowser(Request homePage)
Constructs a new Prowser object with a preset default configuration and the specified home page.

Prowser(Request homePage, String defaultHttpVersion, Integer defaultTimeout, String defaultUserAgent)
Constructs a new Prowser object with the specified home page and the specified default configuration values.

Prowser(String defaultHttpVersion, Integer defaultTimeout, String defaultUserAgent)
Constructs a new Prowser object with the specified default configuration values and no home page.

Method Summary

Tab	closeTab(Tab tab) Closes the specified Tab so that it is no longer associated with this Prowser instance.
Tab[]	closeTabs() Closes all Tab's associated with this Prowser instance.
Tab	createTab() Opens a new Tab for this Prowser instance, automatically loaded with the Prowser's specified home page (if any).
Tab	createTab(boolean loadHomePage) Opens a new Tab for this Prowser instance.
String	getDefaultHttpVersion() Returns the default HTTP version used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.
Integer	getDefaultTimeout() Returns the default request timeout (in milliseconds) used by Tabs of this Prowser instance whenever a Request does not explicitly specify one.
String	getDefaultUserAgent() Returns the default user-agent string used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.
Request	getHomePage() Returns the home page Request object for this Prowser instance.
int	getTabCount() Returns the number of Tab's currently open for this Prowser instance.
Tab[]	getTabs() Returns an array of all the open tabs in this Prowser instance.
void	setDefaultHttpVersion(String httpVersion) Sets a new default HTTP version to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.
void	setDefaultTimeout(Integer timeout) Sets a new default request timeout (in milliseconds) to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.
void	setDefaultUserAgent(String userAgent) Sets a new default user-agent string to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.
void	setHomePage(Request homePage) Sets the home page Request object for this Prowser instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

Prowser

public Prowser()

Constructs a new Prowser object with a preset default configuration and no home page.

Prowser

public Prowser(Request homePage)

Constructs a new Prowser object with a preset default configuration and the specified home page.

Parameters:

homePage - The home page Request for this Prowser instance.

Prowser

public Prowser(Request homePage,
               String defaultHttpVersion,
               Integer defaultTimeout,
               String defaultUserAgent)

Constructs a new Prowser object with the specified home page and the specified default configuration values. Any null arguments will cause preset default values to be used. (A null value for homePage leaves it null.)

Parameters:

homePage - The home page Request for this Prowser instance.

defaultHttpVersion - The HTTP version to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

defaultTimeout - The request timeout (in milliseconds) to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

defaultUserAgent - The user-agent string to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

Prowser

public Prowser(String defaultHttpVersion,
               Integer defaultTimeout,
               String defaultUserAgent)

Constructs a new Prowser object with the specified default configuration values and no home page. Any null arguments will cause preset default values to be used.

Parameters:

defaultHttpVersion - The HTTP version to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

defaultTimeout - The request timeout (in milliseconds) to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

defaultUserAgent - The user-agent string to be used by this Prowser instance whenever a Request doesn't explicitly specify one.

Method Detail

closeTab

public Tab closeTab(Tab tab)

Closes the specified Tab so that it is no longer associated with this Prowser instance.

Parameters:

tab - Tab to be closed.

Returns:

The closed Tab object.

closeTabs

public Tab[] closeTabs()

Closes all Tab's associated with this Prowser instance.

Returns:

An array of the closed Tab objects.

createTab

public Tab createTab()

Opens a new Tab for this Prowser instance, automatically loaded with the Prowser's specified home page (if any).

If a home page is loaded, it will be available via the Tab.getResponse() method.

To prevent the home page from loading, use createTab(boolean) and pass it a value of false.

Returns:

A newly-created Tab object that is owned and managed by this Prowser, automatically loaded with the Prowser's specified home page (if any).

See Also:

createTab(boolean)

createTab

public Tab createTab(boolean loadHomePage)

Opens a new Tab for this Prowser instance. If loadHomePage is true, the Prowser's specified home page (if any) is automatically loaded in the new Tab; otherwise, a home page will not be loaded.

If a home page is loaded, it will be available via the Tab.getResponse() method.

Parameters:

loadHomePage - When true, causes the new Tab to automatically load the Prowser's home page (if any).

Returns:

A newly-created Tab object that is owned and managed by this Prowser, automatically loaded with the Prowser's specified home page (if any) when the loadHomePage argument is true.

See Also:

createTab()

getDefaultHttpVersion

public String getDefaultHttpVersion()

Returns the default HTTP version used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.

Returns:

The default HTTP version used by Tabs of this Prowser instance.

getDefaultTimeout

public Integer getDefaultTimeout()

Returns the default request timeout (in milliseconds) used by Tabs of this Prowser instance whenever a Request does not explicitly specify one.

Returns:

The default request timeout (in milliseconds) used by Tabs of this Prowser.

See Also:

setDefaultTimeout(Integer)

getDefaultUserAgent

public String getDefaultUserAgent()

Returns the default user-agent string used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one.

Returns:

The default user-agent string used by Tabs of this Prowser instance.

getHomePage

public Request getHomePage()

Returns the home page Request object for this Prowser instance.

Returns:

The home page Request object for this Prowser instance, or null if no home page has been set.

getTabCount

public int getTabCount()

Returns the number of Tab's currently open for this Prowser instance.

Returns:

The number of Tab's currently open for this Prowser instance.

getTabs

public Tab[] getTabs()

Returns an array of all the open tabs in this Prowser instance.

Returns:

An array of all the open tabs in this Prowser instance.

setDefaultHttpVersion

public void setDefaultHttpVersion(String httpVersion)

Sets a new default HTTP version to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one. If this value is never set, a preset default is used.

Parameters:

httpVersion - The new default HTTP version to be used by Tabs of this Prowser.

Throws:

IllegalArgumentException - If httpVersion is not valid.

setDefaultTimeout

public void setDefaultTimeout(Integer timeout)

Sets a new default request timeout (in milliseconds) to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one. If this value is never set, a preset default of Request.TIMEOUT_INFINITE is used.

A value of Request.TIMEOUT_INFINITE indicates that the calling thread should wait indefinitely for requests to complete.

Parameters:

timeout - The new default request timeout (in milliseconds) to be used by Tabs of this Prowser, or Request.TIMEOUT_INFINITE to indicate that the default behavior is to never time out requests that don't explicitly specify a timeout.

Throws:

IllegalArgumentException - If the timeout value is null or less than zero.

See Also:

Setting an explicit request timeout., Setting a temporary request timeout.

setDefaultUserAgent

public void setDefaultUserAgent(String userAgent)

Sets a new default user-agent string to be used by Tabs of this Prowser instance whenever a Request doesn't explicitly specify one. If this value is never set, a preset default is used.

Parameters:

userAgent - The new default user-agent string to be used by Tabs of this Prowser.

setHomePage

public void setHomePage(Request homePage)

Sets the home page Request object for this Prowser instance.

Parameters:

homePage - The home page Request object for this Prowser instance.