
                           README for Prowser 0.2.0

===============================================================================
  0. Contents
===============================================================================

    0. Contents
    1. About Prowser
    2. What's New in Version 0.2.0
    3. Requirements
    4. Usage
    5. Change Log
    6. To Do
    7. Licenses
    8. Third-party Source
    9. Support


===============================================================================
  1. About Prowser
===============================================================================

Prowser is a "programmatic browser" library for Java. It enables programs to
easily surf the web via an API that simulates the way GUI browsers are used.

Prowser's features include:

    * Web page retrieval by simply specifying a URL.
    * Support for HTTP GET and POST methods.
    * Ability to submit form data in a request, either via a query string (GET)
      or in a request body (POST).
    * Complex request creation through the use of request files.
    * Automatic handling of redirects.
    * Automatic handling of cookies.
    * Ability to perform encrypted requests (https:).
    * Ability to perform HTTP Basic and Digest Authentication requests.
    * Access to retrieved web page as encoded page source (for scanning HTML).
    * Access to retrieved web page in binary form (for downloading files).
    * Ability to perform common browser operations normally provided via
      standard buttons on GUI browsers (Back, Forward, Refresh, Home, and Stop).
    * Configurable request timeout settings.
    * Configurable HTTP version usage.
    * Configurable user-agent string.
    * Page history.
    * Access to page data like content type, character set, and title.
    * "Tabbed" browsing. 

For more information, visit the following web sites:

    http://prowser.sourceforge.net/
    http://sourceforge.net/projects/prowser/


===============================================================================
  2. What's New in Version 0.2.0
===============================================================================

For a detailed list, see the distribution's CHANGES file. Highlights include:

    * Added tabbed browsing! (NOTE: This renders the 0.1.0 API incompatible
      with 0.2.0.)
    * Overhauled history mechanism.
    * "Debug" functionality now referred to as "Trace".
    * Added methods for obtaining the final URI, the page titile, the
      content-type, and the character set to the Response class.
    * Other minor changes and enhancements.


===============================================================================
  3. Requirements
===============================================================================

Prowser requires Java 5.0 (1.5.0) or greater.


===============================================================================
  4. Usage
===============================================================================

To use the Prowser library in your applications:

    1. Add file prowser-x.x.x.jar to the classpath used by your compiler (where
       "x.x.x" is the version of Prowser contained in the JAR file).
    
    2. Import the following packages in each source file that will use Prowser:
    
           import com.zenkey.net.prowser.Prowser;
           import com.zenkey.net.prowser.Request;
           import com.zenkey.net.prowser.Response;

    3. Write code using Prowser's API, which is documented at:
    
           http://prowser.sourceforge.net/javadoc/


To run a program that uses the Prowser library, make sure file
prowser-x.x.x.jar is in the classpath. For example, on a Windows machine, you
could do something like this:

    1. Change to the directory that contains your program's compiled *.class
       file (e.g., YourProgram.class).
      
    2. Copy file prowser-x.x.x.jar to the current directory.
  
    3. Run the following command:

           java -classpath .;prowser-x.x.x.jar YourProgram


For more information on how to use Prowser's API (including examples), visit
the following site:

    http://prowser.sourceforge.net/


===============================================================================
  5. Change Log
===============================================================================

See the distribution file named CHANGES.


===============================================================================
  6. To Do
===============================================================================

The following is a list of TENTATIVE changes and enhancements:

* Provide ability to specify custom request header fields.
* Provide retrieval of request and response header fields after page is
  retrieved.
* Implement Prowser.saveFileAs(Request request, String filename).
* Implement Prowser.saveFile(Request req), using filename from response header.
* Provide ability to POST binary data.
  (See HttpClient's PostMethod.setRequestEntity(RequestEntity requestEntity).)
* Provide ability to POST multipart/form data.
  (See http://jakarta.apache.org/commons/httpclient/methods/multipartpost.html.)
* Provide ability to POST requests with user defined request bodies (e.g., for
  making requests to SOAP services).
* Implement disk-based page caching.
* Implement setting of max size for history list. (Currently 15.)
* Implement setting of max redirects. (Currently 10.)
* Implement serialization of Prowser (and possibly Request) objects.
* Implement better way to supress HttpClient log messages.
* Update JUnit tests for Request class, and create JUnit tests for Prowser and
  Response classes.
* Implement encrypted password mechanism for Request(File) constructor.


===============================================================================
  7. Licenses
===============================================================================

Prowser is licensed under the GNU Lesser General Public License, as published
by the Free Software Foundation. A copy of that license is provided with the
Prowser distribution in a file named COPYING. See the following web site for
more information:

    http://www.gnu.org/licenses/licenses.html

This version of Prowser includes software developed by The Apache Software
Foundation. That software is licensed under the Apache License, Version 2.0. A
copy of that license is provided with the Prowser distribution in a file named
third-party-licenses/LICENSE. See the following web site for more information:

    http://www.apache.org/licenses/


===============================================================================
  8. Third-party Source
===============================================================================

This version of Prowser uses the following Apache Jakarta components. The source
code of these components is freely available at http://jakarta.apache.org/:

    Jakarta Commons HttpClient
    Jakarta Commons Codec
    Jakarta Commons Logging


===============================================================================
  9. Support
===============================================================================

To report bugs, submit a feature request, or ask a question, go to the
following site and click on "Support Requests":

    http://sourceforge.net/projects/prowser/
