com.zenkey.net.prowser
Class Tab

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

public class Tab
extends Object

The Tab class represents a "tab window" that belongs to a particular Prowser instance; Tab objects actually do the work of executing web page requests and processing the responses. Multiple Tab instances can be owned by a single Prowser in the same way that a tabbed GUI web browser can have more than one tab window open at any one time.

The Tab class makes it easy to retrieve web pages, including encrypted https requests. You simply specify URLs and (when necessary) form data. In lieu of actually being able to see the resulting pages, their contents -- text or binary -- are easily retrievable. Also, all cookie processing and all normal server-side redirections are handled automatically. Even HTTP Basic and Digest Authentication are performed seamlessly.

A Tab object saves various pieces of state information between page requests. This is done to provide browser functionality like source viewing and page refreshing. Of particular note is the fact that for each request/response transaction that a Tab executes, it saves the Request and Response objects internally until the next page request is processed. These Request and Response objects are referred to as the "current" Request and Response (sometimes collectively called the "current page").

In keeping with Prowser's "GUI browser functionality" philosophy, the Tab class provides methods that perform common browser operations like going back one page, going forward one page, refreshing the current page, returning to the home page, and stopping the current page request.

Usage

An object of the Prowser class is used to create and maintain one or more Tab objects. A Tab object acts upon a Request object in order to retrieve a web page. The request results in a Response object that contains the page contents (and other information related to the transaction).

For example, to print out the page source for http://java.net/, you could do this:

     Prowser prowser = new Prowser();
     Tab tab = prowser.createTab();
     Request request = new Request("http://java.net/");
     Response response = tab.go(request);
     String html = response.getPageSource();
     System.out.println(html);
 

Or, you could forego most of the intermediate variables, and reduce the above code to this:

     Tab tab = new Prowser().createTab();
     System.out.println(
         tab.go("http://java.net/").getPageSource());
 

Note: If you later needed the Prowser object instantiated in the above code snippet, you could retrieve it with the following statement:

     Prowser prowser = tab.getProwser();
 

To download a file, you use the getPageBytes() method instead of getPageSource(). For example (assuming that a Tab object named tab already exists) you could obtain a PDF file with the following code:

     Request request =
         new Request("http://java.sun.com/xml/webservices.pdf");
     byte[] fileContents = tab.go(request).getPageBytes();
 

To submit a web form and retrieve the resulting page (e.g., logging into your bank account), you can use the pertinent methods to configure a Request object with the proper URL, HTTP method (POST) and form field values. However, you also have the option of specifying the request's configuration in a request file, which can be set up once and used repeatedly without having to configure the request programmatically. See Request(java.io.File) for more information.

To request a page that requires Basic or Digest Authentication, simply include the username and password as part of the URI, like this:

     http://username:password@www.site-requiring-auth.com/
 

Thread Safety

An individual Tab object is not thread-safe. This is due to local state information (like "current" page and browsing history) that each Tab maintains. However, multiple Tab instances can be safely used in concurrent threads, as long as no two threads are using the same Tab. Also, a single thread can safely employ more than one Tab.

Version:

$Revision: 1.1 $, $Date: 2006/02/21 19:55:15 $

See Also:

Prowser, Request, Response

Field Summary

static int	TRACE_ALL Write all trace info.
static int	TRACE_BODY Write HTTP response bodies to standard output.
static int	TRACE_HEADERS Write HTTP request and response headers to standard output.
static int	TRACE_OFF No tracing.
static int	TRACE_REQUEST_RESPONSE_LINES Write HTTP request and response (status) lines to standard output.
static int	TRACE_URI Write only URIs to standard output.

Method Summary

void	clearHistory() Empties out the history list of this Tab so that methods like goBack() and goForward() will have no effect (until new pages are retrieved).
protected void	finalize() Performs finalization for this Tab instance when it is garbage collected.
int	getError() Convenience method equivalent to calling getResponse().getError().
String	getErrorText() Convenience method equivalent to calling getResponse().getErrorText().
int	getHistoryIndex() Returns the "current" page's position in the history list.
int	getHistorySize() Returns the current size of the history list.
byte[]	getPageBytes() Convenience method equivalent to calling getResponse().getPageBytes().
String	getPageSource() Convenience method equivalent to calling getResponse().getPageSource().
Prowser	getProwser() Returns the Prowser that owns this Tab instance.
Request	getRequest() Returns the most recently executed Request.
Response	getResponse() Returns the most recently generated Response.
int	getStatus() Convenience method equivalent to calling getResponse().getStatus().
String	getStatusText() Convenience method equivalent to calling getResponse().getStatusText().
Response	go(Request request) Executes the specified Request and returns a new Response object.
Response	go(String uri) Creates a new Request object from the specified URI string, executes the request, and then returns a new Response object.
Response	go(URI uri) Creates a new Request object from the specified URI object, executes the request, and then returns a new Response object.
Response	goBack() Simulates the action of a web browser's Back button by returning the previous page in the history list.
Response	goForward() Simulates the action of a web browser's Forward button by returning the next page in the history list.
Response	goHome() Simulates the action of a web browser's Home button.
boolean	isClosed() Indicates if this Tab has been closed.
Response	jumpBack(int pagesBack) Returns (from the history list) a previously visited page that was originally requested prior to the "current" page.
Response	jumpForward(int pagesForward) Returns (from the history list) a previously visited page that was originally requested after to the "current" page.
Response	refresh() Simulates the action of a web browser's Refresh button.
void	setTraceFile(File traceFile, boolean append) Specifies the file to use for the trace output of this Tab instance.
void	setTraceLevel(int traceLevel) Sets the trace level of this Tab instance.
Tab	stop(Integer timeout) Simulates the action of a web browser's Stop button by enforcing a timeout that is applied to the next page request only.

Methods inherited from class java.lang.Object

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

Field Detail

TRACE_OFF

public static final int TRACE_OFF

No tracing.

See Also:

setTraceLevel(int), Constant Field Values

TRACE_URI

public static final int TRACE_URI

Write only URIs to standard output.

See Also:

setTraceLevel(int), Constant Field Values

TRACE_REQUEST_RESPONSE_LINES

public static final int TRACE_REQUEST_RESPONSE_LINES

Write HTTP request and response (status) lines to standard output. The output will also include the URIs.

See Also:

setTraceLevel(int), Constant Field Values

TRACE_HEADERS

public static final int TRACE_HEADERS

Write HTTP request and response headers to standard output. The output will also include the request/response lines and the URIs.

See Also:

setTraceLevel(int), Constant Field Values

TRACE_BODY

public static final int TRACE_BODY

Write HTTP response bodies to standard output. The output will also include the headers, the request/response lines and the URIs.

See Also:

setTraceLevel(int), Constant Field Values

TRACE_ALL

public static final int TRACE_ALL

Write all trace info. (Equivalent to the highest trace level.)

See Also:

setTraceLevel(int), Constant Field Values

Method Detail

clearHistory

public void clearHistory()

Empties out the history list of this Tab so that methods like goBack() and goForward() will have no effect (until new pages are retrieved).

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

See Also:

goBack(), goForward(), jumpBack(int), jumpForward(int), getHistoryIndex(), getHistorySize()

finalize

protected void finalize()
                 throws Throwable

Performs finalization for this Tab instance when it is garbage collected.

Overrides:

finalize in class Object

Throws:

Throwable - The Exception raised by this method.

See Also:

Object.finalize()

getError

public int getError()

Convenience method equivalent to calling getResponse().getError().

Returns:

A code representing the error condition of the request that generated the most recent response.

Throws:

IllegalStateException - If no response has been generated yet.

See Also:

getErrorText()

getErrorText

public String getErrorText()

Convenience method equivalent to calling getResponse().getErrorText().

Returns:

A String describing the error condition of the request that generated the most recent response, or null if no error condition exists (i.e., getError() returns Response.ERR_NONE).

Throws:

IllegalStateException - If no response has been generated yet.

See Also:

getError()

getHistoryIndex

public int getHistoryIndex()

Returns the "current" page's position in the history list. (The first item in the history list is at index 0.)

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The "current" page's position in the history list.

getHistorySize

public int getHistorySize()

Returns the current size of the history list.

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The current size of the history list.

getPageBytes

public byte[] getPageBytes()

Convenience method equivalent to calling getResponse().getPageBytes().

Returns:

The most recently retrieved web page as a byte array.

Throws:

IllegalStateException - If no response has been generated yet.

getPageSource

public String getPageSource()

Convenience method equivalent to calling getResponse().getPageSource().

Returns:

The most recently retrieved web page as an encoded string.

Throws:

IllegalStateException - If no response has been generated yet.

getProwser

public Prowser getProwser()

Returns the Prowser that owns this Tab instance.

Returns:

The Prowser that owns this Tab instance.

getRequest

public Request getRequest()

Returns the most recently executed Request.

Returns:

The most recently executed Request.

Throws:

IllegalStateException - If no request has been submitted yet

getResponse

public Response getResponse()

Returns the most recently generated Response.

Returns:

The most recently generated Response.

Throws:

IllegalStateException - If no response has been generated yet.

getStatus

public int getStatus()

Convenience method equivalent to calling getResponse().getStatus().

Returns:

The HTTP status code associated with the most recent response, or Response.STATUS_NOT_OBTAINED if an error occurred during the request.

Throws:

IllegalStateException - If no response has been generated yet.

See Also:

getError()

getStatusText

public String getStatusText()

Convenience method equivalent to calling getResponse().getStatusText().

Returns:

The HTTP status text associated with the most recent response, or null if an error occurred during the request (i.e., getStatus() returns Response.STATUS_NOT_OBTAINED).

Throws:

IllegalStateException - If no response has been generated yet.

See Also:

getError()

go

public Response go(Request request)

Executes the specified Request and returns a new Response object.

At the end of the transaction, the Request argument and Response result are saved as the "current" request and response in order to provide browser functionality like page refreshing and source viewing.

Parameters:

request - A Request object representing the page request to be made.

Returns:

A new Response object.

Throws:

IllegalArgumentException - If request is null.

go

public Response go(String uri)

Creates a new Request object from the specified URI string, executes the request, and then returns a new Response object.

At the end of the transaction, the newly-created Request and the Response result are saved as the "current" request and response in order to provide browser functionality like page refreshing and source viewing.

Parameters:

uri - A URI string representing the page request to be made.

Returns:

A new Response object.

Throws:

IllegalArgumentException - If uri is not valid.

go

public Response go(URI uri)

Creates a new Request object from the specified URI object, executes the request, and then returns a new Response object.

At the end of the transaction, the newly-created Request and the Response result are saved as the "current" request and response in order to provide browser functionality like page refreshing and source viewing.

Parameters:

uri - A URI object representing the page request to be made.

Returns:

A new Response object.

Throws:

IllegalArgumentException - If uri is null.

goBack

public Response goBack()

Simulates the action of a web browser's Back button by returning the previous page in the history list. Note that a "cached" Response object is returned by this method, not a newly-generated one.

As a side effect of calling this method, the "current" request and response of this Tab instance are set to be the Request and Response objects associated with the returned page. Therefore, if desired, the "cached" page that is returned by this method can be easily refreshed with code similar to the following:

     Response oldResponse = tab.goBack();
     Response newResponse = tab.refresh();
 

Obviously, another outcome of calling this method is that the history index will subsequently point to the previous page. So, for example, calling goForward() immediately after calling this method will set the history index -- along with the "current" request and response for this Tab instance -- back to the state that existed before this method was called.

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The "cached" Response object associated with the previous page in the history list, or null if the "current" page is already at the beginning of the history list.

Throws:

IllegalStateException - If no page history exists.

See Also:

goForward(), jumpBack(int), jumpForward(int), getHistoryIndex(), getHistorySize(), clearHistory()

goForward

public Response goForward()

Simulates the action of a web browser's Forward button by returning the next page in the history list. Note that a "cached" Response object is returned by this method, not a newly-generated one.

As a side effect of calling this method, the "current" request and response of this Tab instance are set to be the Request and Response objects associated with the returned page. Therefore, if desired, the "cached" page that is returned by this method can be easily refreshed with code similar to the following:

     Response oldResponse = tab.goForward();
     Response newResponse = tab.refresh();
 

Obviously, another outcome of calling this method is that the history index will subsequently point to the next page. So, for example, calling goBack() immediately after calling this method will set the history index -- along with the "current" request and response for this Tab instance -- back to the state that existed before this method was called.

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The "cached" Response object associated with the next page in the history list, or null if the "current" page is already at the end of the history list.

Throws:

IllegalStateException - If no page history exists.

See Also:

goBack(), jumpForward(int), jumpBack(int), getHistoryIndex(), getHistorySize(), clearHistory()

goHome

public Response goHome()

Simulates the action of a web browser's Home button. The home page Request is re-submitted and a new Response is generated.

Returns:

A new Response object.

Throws:

IllegalStateException - If no home page has been set, or the home page is invalid.

isClosed

public boolean isClosed()

Indicates if this Tab has been closed.

Returns:

A boolean value indicating if this Tab has been closed.

jumpBack

public Response jumpBack(int pagesBack)

Returns (from the history list) a previously visited page that was originally requested prior to the "current" page. (The number of pages to jump back is indicated by the pagesBack argument.) This method simulates the action of clicking the little arrow on the right side of a browser's Back button to select a page from a drop-down menu of recent history. Note that a "cached" Response object is returned by this method, not a newly-generated one.

As a side effect of calling this method, the "current" request and response of this Tab instance are set to be the Request and Response objects associated with the returned page. Therefore, if desired, the "cached" page that is returned by this method can be easily refreshed with code similar to the following:

     Response oldResponse = tab.jumpBack(3);
     Response newResponse = tab.refresh();
 

Obviously, another outcome of calling this method is that the history index will subsequently point to the selected page. So, for example, calling jumpForward(int) immediately after calling this method can set the history index -- along with the "current" request and response for this Tab instance -- back to the state that existed before this method was called (assuming that both calls use the same value for the number of pages to jump).

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The "cached" Response object associated with the page that is pagesBack pages back in the history list, or null if the "current" page is less than pagesBack pages from the beginning of the history list.

Throws:

IllegalArgumentException - If pagesBack is not a positive value.

IllegalStateException - If no page history exists.

See Also:

jumpForward(int), goBack(), goForward(), getHistoryIndex(), getHistorySize(), clearHistory()

jumpForward

public Response jumpForward(int pagesForward)

Returns (from the history list) a previously visited page that was originally requested after to the "current" page. (The number of pages to jump forward is indicated by the pagesForward argument.) This method simulates the action of clicking the little arrow on the right side of a browser's Forward button to select a page from a drop-down menu of recent history. Note that a "cached" Response object is returned by this method, not a newly-generated one.

As a side effect of calling this method, the "current" request and response of this Tab instance are set to be the Request and Response objects associated with the returned page. Therefore, if desired, the "cached" page that is returned by this method can be easily refreshed with code similar to the following:

     Response oldResponse = tab.jumpForward(3);
     Response newResponse = tab.refresh();
 

Obviously, another outcome of calling this method is that the history index will subsequently point to the selected page. So, for example, calling jumpBack(int) immediately after calling this method can set the history index -- along with the "current" request and response for this Tab instance -- back to the state that existed before this method was called (assuming that both calls use the same value for the number of pages to jump).

Note that the history list has a maximum capacity of 15 items. These items are currently "cached" in-memory, although future versions of the Prowser library may implement a disk cacheing mechanism and/or an API for sizing the history list according to an application's needs.

Returns:

The "cached" Response object associated with the page that is pagesFoward pages forward in the history list, or null if the "current" page is less than pagesForward pages from the end of the history list.

Throws:

IllegalArgumentException - If pagesForward is not a positive value.

IllegalStateException - If no page history exists.

See Also:

jumpBack(int), goForward(), goBack(), getHistoryIndex(), getHistorySize(), clearHistory()

refresh

public Response refresh()

Simulates the action of a web browser's Refresh button. The most recent Request is re-submitted and a new Response is generated.

Returns:

A new Response object.

Throws:

IllegalStateException - If no initial Request exists to be refreshed.

setTraceFile

public void setTraceFile(File traceFile,
                         boolean append)
                  throws FileNotFoundException

Specifies the file to use for the trace output of this Tab instance. Trace output will be written to this location provided that the setTraceLevel(int) method has been called with a value higher than TRACE_OFF. If no file is ever specified, standard output is used by default. To set the output location back to standard output, pass null for the traceFile argument.

Parameters:

traceFile - File to receive trace output, or null to use standard output.

append - If true, trace output will be appended to the file (assuming that the file existed before this Tab instance was created); otherwise, the file will be overwritten.

Throws:

FileNotFoundException - If the attempt to open the specified file fails.

setTraceLevel

public void setTraceLevel(int traceLevel)

Sets the trace level of this Tab instance. The trace level dictates how much information from each request/response transaction is written to the trace file (or standard output if no trace file has been specified). See setTraceFile(File, boolean) for information on specifying a trace file.

See the TRACE_xxx constants for valid values and their meanings.

Parameters:

traceLevel - The trace level of this Tab instance.

stop

public Tab stop(Integer timeout)

Simulates the action of a web browser's Stop button by enforcing a timeout that is applied to the next page request only. This method returns the Tab object that it acts upon so that a page request method call can be chained onto it, like this:

     response = tab.stop(5000).go("http://java.sun.com/");
 

This differs from Request.setTimeout(Integer), which sets an explicit timeout that is inherrent to a Request, and it is also different than Prowser.setDefaultTimeout(Integer), which sets a new default timeout used for any Request that does not explicitly specify one. The difference is that this method sets a temporary timeout; it only applies to the next request processed. Subsequent requests are not affected. Note that the above code could also be written as follows, with the same effect, but with less clarity:

     tab.stop(5000);   // Sets 5-sec timeout for *next* request *only*
     response = tab.go(" http://java.sun.com/");
 

The temporary timeout set by this method will apply to any page request method, e.g., go(Request), refresh(), goBack(), etc.

Parameters:

timeout - The number of milliseconds to wait before timing out the next reqeust only, or Request.TIMEOUT_INFINITE to indicate that the next request should never time out.

Returns:

The Tab object for which the temporary timeout is being set (i.e., this Tab).

Throws:

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

See Also:

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