BrowserHawk4J 14.0

Copyright (c) 1997-2011 cyScape, Inc.  All rights reserved.

----------------------
QUICK INDEX:
----------------------

  - INTRODUCTION
  - NEW FEATURES IN BROWSERHAWK 14
  - FIXES IN BROWSERHAWK 14
  - RULES ENFORCEMENT TECHNOLOGY (RET)
  - JAVASCRIPT ERROR TRACKING
  - PAGE LOAD TIME (PLT)
  - SYSTEM REQUIREMENTS
  - CHECKING THE EXTENDED PROPERTIES
  - LICENSING
  - SPECIAL NOTE TO USERS OF BROWSERHAWK4J ACROSS LOAD-BALANCED SERVERS
  - UPGRADING
  - INSTALLATION
    - FOR A SINGLE WEB APP
    - FOR USE ACROSS ALL WEB APPS
    - FOR USE WITH COLDFUSION MX AND IIS (Windows)
    - FOR USE WITH COLDFUSION MX (non-Windows)
    - FOR USE WITH PHP
  - TESTING OPEN PORTS
  - TESTING SSL ENABLED
  - TESTING SSL KEYSIZE
  - TROUBLESHOOTING
  - SUPPORT AND FEEDBACK
  - EXAMPLE USAGE
       USING BROWSERHAWK FROM A SERVLET
       USING BROWSERHAWK FROM A JSP
       USING BROWSERHAWK FROM CFMX (COLD FUSION MX)
       USING BROWSERHAWK FROM ASP (ACTIVE SERVER PAGES)
       PERFORMING EXTENDED PROPERTY DETECTION FROM A SERVLET
       PERFORMING EXTENDED PROPERTY DETECTION FROM A JSP
  - INCLUDED EXAMPLES/SAMPLES
  - BROWSER HAWK REPORTS
  - NOTES ON POST DATA PASS-THROUGH
  - KNOWN ISSUES
  - FILE AND DIRECTORY STRUCTURE
  - CHANGES
  - NOTICE

----------------------
INTRODUCTION
----------------------

BrowserHawk makes it easy for professional web developers to build high
impact sites that reach the widest possible audience, while ensuring a
Flawless Web Experience for every visitor, regardless of their browser
settings and system capabilities.

BrowserHawk4J is implemented as a powerful server-side Java library combined
with the most complete browser capabilities knowledge base found anywhere
in the world.  BrowserHawk instantly matches visiting browsers with entries
in the knowledge base to identify the browser type, version, platform, and
over 120 other properties of the browser.

It also includes advanced capabilities to inspect a browser to detect whether
cookies or JavaScript is enabled or disabled, what connection speed the
client has in communicating with the server, the current width and height of
the browser desktop, the available width and height of the browser window,
the color depth of the client, and whether various plugins -- such as
Macromedia Flash, Macromedia Director, QuickTime, Adobe Acrobat, RealPlayer,
and Windows MediaPlayer -- are installed or not (and often what version of
each plugin), and much more!


---------------------------------
NEW FEATURES IN BROWSERHAWK 14
---------------------------------

The OSName, OSVersion, and OSDetails properties have been improved in BH 14.
Previously OSName and OSVersion were available only as extended properties.
Now these properties are available as both basic properties (on the
BrowserInfo class) and as extended properties (on the ExtendedBrowserInfo
class).  The basic properties extract the values from the User-Agent string
(fast, easy, but not always available), while extended properties use
client-side JavaScript and Java (slower, but more often available).

The definitions of the properties have changed also:

OSName returns the major name of the OS, without the version.  Examples
include "Windows", "OS X", "iOS", and "Android".

OSVersion returns the numeric version of the OS, if known.  Examples include
"6.0" for Windows Vista, "10.6.7" for Mac OS X Snow Leopard, or "4.3.2" for
iOS.  Using numbers here makes it easy to do "version X or greater"
comparisons.

OSDetails returns the OSName and the OSVersion in one.  For Windows and Mac OS
X it uses the human-friendly version string instead of the number.  Examples
include "Windows Vista", "OS X Lion", and "iOS 4.3.2".  If no version id or
number is known, it's omitted.

---------------------------------
NEW FEATURES IN BROWSERHAWK 14
---------------------------------

- Support for IE 10 preview builds

- Support for Firefox 7

- Support for Windows 8 beta

- Support for OS X Lion

- Support for Flash 11

- Support for WinInstaller version 5

- Support for the Fluid browser: The "Fluid" browser is now detected. By
  design, BrowserHawk returns this as Safari 5.x for the browser and version
  properties, and "Fluid" for the ContainerBrowser property, along with its
  version info in the ContainerVersion properties.

- Expanded mobile device detection: Support for several additional mobile
  devices was added.

- Mobile device type detection: The new DeviceType property (string) returns
  "Handheld" or "Tablet" for mobile devices, accordingly.  OS bit size
  detection: The new OSBitSize* property (integer) returns the bit size of the
  underlying operating system, such as 32 or 64 bits.  Browser bit size
  detection: The new BrowserBitSize* property (integer) returns the bit size
  of the browser, such as 32 or 64 bits. Use this to determine whether a user
  on a 64 bit operating system is running a 32 bit versus 64 bit version of
  their browser.

- Detection of blocked Flash: The new Plugin_FlashBlocked property returns
  True if Flash is installed, but is being blocked from running by software
  on the user's machine, such as a browser plugin. Note that not all blockers
  are detectable.

- Flash timeout setting: The new FlashTimeout property (integer) provides the
  flexibility to control the amount of time BH waits before determining that
  Flash is blocked.

- New Java check type setting: The new JavaCheckType property (integer) can
  be used to delay loading of the applet used by BH to test Java. This
  applies to the JavaVendor, JavaVersion, Plugin_Javaver, OSName, OSVersion,
  OSDetails, and OSArch properties. This setting may be useful for some edge
  cases where Java settings for a particular user are not being detected. It
  is also useful if you are using a custom PageMessage for your "Please
  wait..." temporary page when also testing these Java based properties,
  allowing your PageMessage to show much more quickly. Note that this is an
  advanced setting. In general, JavaCheckType should be kept at its default of
  0 unless you have a specific reason to change it.

- Detection of WebKit: The new WebKit property (boolean) returns True if the
  browser is based on the WebKit layout engine, False otherwise.

- Detection of WebKit version: The new WebKitVersion property (string)
  returns the version number of the WebKit layout engine, for WebKit based
  browsers. The result is returned in various formats such as "532.9",
  "533.17.9" and "534.1+".

- DocType setting: The new DocTypeTag property (string) can be used to set
  the "<!DOCTYPE>" tag that BrowserHawk writes out in the HTML of the
  temporary page displayed while performing an extended property test. Setting
  this may be helpful or even mandatory if you are using a PageMessage which
  includes complex HTML.

- OSName property: Major improvements were made to the OSName property. OSName
  was simplified to return "Windows" for all Windows platforms, and "OS X" for
  Macs.

- OSVersion property: Major improvements were made to the OSVersion property.
  This property now returns the version number of the OS, not just for
  browsers but also for mobile devices when available (such as with iOS and
  Andriod devices). Examples include "6.1" for Windows 7, "10.7.1" for OS X
  Lion, and "4.2" for an iOS device running that version. See the
  documentation for more information.

- OSDetails property: Major improvements were made to the OSDetails property.
  OSDetails now provides the detailed information which includes the OS name
  and its version, such as "Windows 8", "OS X Lion", and "iOS 4.2".
  OSName and OSVersion as "basic" properties: OSName and OSVersion are now
  available as basic properties and do not require an extended property test.
  This provides for instant testing of these properties. The extended property
  versions of these properties are still available, which are useful for edge
  cases such as older versions of Opera or to get the full version info (x.y.z
  instead of x.y) for OS X users running Firefox. Unless these edge cases are
  critical, we highly recommend switching to the basic version of these
  properties. BH for ActiveX users - simply do not pass in OSName or OSVersion
  to SetExtProperties. BH for .NET/Java users - simply do not pass in OSName
  or OSVersion to AddProperties, and instead get the results from the
  BrowserObj class instead of ExtendedBrowserObj.

- Connection speed testing: The Progressive connection speed test was enhanced
  to more accurately measure very fast connections, such as those in the 5-35+
  Mbps range.

- Expanded RET engine: Rules Enforcement Technology (RET) now supports setting
  Progressive connection speed options, as well as several additional options,
  directly in the rules XML file.

- RET output formatting: RET now supports a "format" function which provides
  more user-friendly output of BH property values. For example, use:
  <message>Your speed is %format(ConnectionSpeed)%</message> to have BH output
  "Your speed is 5.62 Mbps" instead of "Your speed is 5621213".

- Enhanced blocked popup detection: The PopupsBlocked property is now faster
  and works with Chrome. Previously Chrome would always return that popups
  were not blocked, regardless of the setting.

- Enhanced Java detection: Extensive enhancements were made to the Java
  detection to make the tests faster and more accurate. This also improves
  detection of Java under OS X Lion. These improvements apply to JavaVendor,
  JavaVersion, Plugin_JavaVer, and the extended property versions of OSName,
  OSVersion, OSDetails and OSArch.

- Enhanced Plugin_JavaVer results: The Plugin_JavaVer property with IE now
  returns up to 1.7 (depending on what version is installed) instead of only
  up to 1.4+ as before. Further, on non-IE browsers, this property now can
  return the full version of the Java plug-in, instead of just x.y+.
  Enhanced firewall and open ports testing: The Firewall, OpenPorts,
  ImagesEnabled, and SSLEnabled properties were improved to run faster and
  provider greater accuracy.

- Expanded BRWS: The BrowserHawk Reports Web Service (BRWS) was expanded to
  support logging of the new properties: DeviceType, OSBitSize,
  BrowserBitSize, WebKit, WebkitVersion, and Plugin_FlashBlocked.
  Updated BrowserHawk Editor: Minor updates and enhancements were made to the
  BrowserHawk Editor.

- Expanded samples: Additional samples that demonstrate the new BrowserHawk
  properties were added.

--------------------------
FIXES IN BROWSERHAWK 14
--------------------------

- Improved Java detection to better support detection under OS X Lion.

- Miscellaneous bug fixes.


-------------------------------------
RULES ENFORCEMENT TECHNOLOGY (RET)
-------------------------------------

BrowserHawk4J 11 introduced Rules Enforcement Technology (RET).  RET
provides an easy way to ensure that each web site visitor meets your site's
minimum browser and system requirements, and to provide automated self-help
to those users who do not.  All without writing any program code!

To use RET you simply define a group of "rules" that reflect your site's
requirements.  Each rule is configured to evaluate to one of 4 states: Pass,
Fail, Warn, and Info.  You define the conditions under which these states
are assigned.  You then pass this rule set to BrowserHawk, which enforces
the rules and takes the actions you specify based on the outcomes of its
testing.

For example, you may define one rule that a user must have Flash 9 or
higher, and that it is failure condition if not.  Another rule may be that
cookies should be enabled, and it is considered only a warning condition if
not. 

In one particular RET implementation, a "pass/fail" table can be presented
to the user that summarizes their browser test results.  This table contains
details about the tests performed, the results, and customized messages
such as corrective actions to take.  BrowserHawk can fully render this
table all on its own, or you can take control and generate the table
yourself if you wish.

In another RET implementation, a user could be redirected to a particular
page or site based on the result of any particular rule, rather than shown
a results table.  Or both styles can be combined, whereby the user is shown
the table except if certain conditions are true - in which case the user is
redirected instead.  Furthermore, for advance usage, you can even
programmatically access the test results and write your own custom
handlers.

RET provides you with great flexibility and complete customization,
including the ability to completely customize the look and feel of the
results table using CSS, specify alternative column headings and
graphic/icons, and even renaming the states.

RET is also completely extensible. For instance, the logic within the XML
rules file can make use of the full set of BrowserHawk standard and
extended property values, as well as values from other data sources such as
your backend systems.  For example, you could add a rule that would display
a warning message to the user such as "Your credit card on file expires in
10 days. Please click here to update this now."

The XML rules file consists of a root element <tests> containing a series
of <test> elements, each representing a test to apply.  Each <test>
corresponds to a specific requirement that, if desired, can result in a
redirect action or a row in the HTML results table.  A full overview and
specification can be found online at http://www.cyscape.com/ret, and the
RET User Guide is included in the BrowserHawk4J distribution.

Note: This feature requires the Enterprise Edition of BrowserHawk.

----------------------------
JAVASCRIPT ERROR TRACKING
----------------------------

One challenge in ensuring a flawless web experience for every user is that
you have little or no visibility into errors that occur on the browser.
With the wide variety of browsers, operating systems, and endless
configuration options available to end users it is nearly impossible to
catch all bugs during Quality Assurance efforts.

BrowserHawk4J 11 solved this challenge by monitoring your web pages for
JavaScript errors that occur "out in the wild".  This enables you to
quickly identify and fix these otherwise hidden issues, which typically go
either unnoticed or unreported by your web site visitors.

When JavaScript errors occur BrowserHawk will log details of the error to
your database -- recorded via BrowserHawk Reports Web Service (BRWS)
technology.  The details include the full path and name of the page where
the error occurred, a description of the error, and line number where it
occurred.

In addition, you can optionally assign several parameters to be logged
along with the error record, such as the user ID and session ID under which
the error occurred, and any other arbitrary data you wish.

Note: This feature requires the Enterprise Edition of BrowserHawk.

To use BrowserHawk to monitor your web pages for JavaScript errors, each
page on your site that you wish to monitor must be instrumented to enable
BrowserHawk to track the page.  This is done by inserting a single line of
JavaScript into your master page, master template, common include file, or
other means used to add common elements (such as navigation) to all your
pages.

Instrumenting your pages for error monitoring is a simple process, as
follows:

1.   Set up and configure the BrowserHawk4J Reports Web Service (BRWS).
When JavaScript errors are detected, the errors are reported to the BRWS,
which then logs the details to your database.

2.   Edit the bhawk_errortracker.js file distributed as source with
BrowserHawk (under the directory webapps/bhawk/webfiles).  IMPORTANT: you
must update the "recordServer" variable in this script so that it points to
your BRWS and delete the alert() line afterward to indicate you have.  See
the comments in the script file for more details, including other
configuration options.

3.   Place a copy of the edited bhawk_errortracker.js file on your web
server in a web directory that is part of your site.

4.   Edit your template or common include file to add the following line of
code somewhere within your HEAD section of the HTML:
<script src="/someFolder/bhawk_errortracker.js" type="text/javascript">&nbsp;</script>

Note that you should change the path shown above to point to the actual web
path of the directory where you placed the script.

Note that the seemingly extra &nbsp; is purposeful - do not remove this.

After following these steps, JavaScript errors that occur on your web site
will be now to logged to your database.

To test your configuration you can use the following sample web page, which
purposely causes a JavaScript error to occur so that it is logged.
Remember to change the path below to match the path to where you placed the
bhawk_errortracker.js script file:

<html>
  <head>
    <script src="/someFolder/bhawk_errortracker.js" type="text/javascript">&nbsp;</script>
  </head>
  <body>
    <script>
      if (noSuchVar == true); // this will trigger an error since this var does not exist
    </script>
    Done - error about noSuchVar not being defined should now be logged to your database
  </body>
</html>

It's sometimes useful to log errors you catch yourself during JavaScript
execution.  You can log these errors as well with a direct call to the
bhawk_logerror(errorstr, errorfile, errorline, errortype) function that's
built into bhawk_errortracker.js.  It accepts an error string (what went
wrong), an error file (in which file did it go wrong), the error line (if
it's known), and the error type ("js" is the standard error type used for
all automatically caught JavaScript errors; use that orcreate your own).


-----------------------
PAGE LOAD TIME (PLT)
-----------------------

BrowserHawk4J 10 introduced Page Load Time (PLT) technology.  PLT enables
you to track page load times for every visitor to your site in real-time.
Unlike traditional monitoring tools, the page load times reported are the
actual load times as experienced by your visitors.  More information on PLT
can be found at http://www.cyscape.com/plt.


----------------------
SYSTEM REQUIREMENTS
----------------------

BrowserHawk4J can be used anywhere server-side Java(tm) is available,
including ColdFusion MX, servlets, JavaServer Pages (JSPs), and PHP
pages.  The only requirement is a Java 1.4 JVM (i.e. JDK 1.4) or later.
Note that to use any of the extended properties of BrowserHawk4J (as
defined below), you must use the BH4J bean from an environment where the
browser's request and response objects are exposed, such as the case
with ColdFusion MX, JSP, and servlets.

-------------------------------------------------------------------------------
CHECKING THE EXTENDED PROPERTIES (plug-ins, connection speed, screen size, etc)
-------------------------------------------------------------------------------

We refer to the "extended Properties" of the BH4J JavaBean as browser settings
that can only be determined by interrogating the browser at run time.  These
differ from "basic" properties which can be determined solely on the server by
the user agent string.  Examples of extended properties include detection of
disabled settings (such as cookies and JavaScript), connection speed, Flash
and other plug-ins, open ports, SSL key sizes, images enabled, and screen and
browser sizes.  Examples of basic properties include the browser type,
version, and platform.

See www.cyscape.com/docs/showhelp.asp?topic=basic_vs_extended_browser_properties
for more information on basic vs extended properties.

When testing any of the extended properties it is first necessary that
you tell BH4J which of the extended properties you want it to check by
passing an instance of the ExtendedOptions class to the
getExtendedBrowserInfo() method.  Although you can test for 'all', it
is highly recommended that you configure BrowserHawk to test only
those properties that you are indeed interested in testing.  For
example, if you are only interested in testing the Flash version and
screen size, use "Plugin_Flash,ScreenSize".  This is far more
efficient than using 'all'.

After configuring the ExtendedOptions you must then call the
getExtendedBrowserInfo() method *before* checking the results of the
corresponding BH4J property.  When calling the
getExtendedBrowserInfo() method, you can specify a 'requestType' of
REQUEST_TYPE_AUTO, REQUEST_TYPE_COOKIE, REQUEST_TYPE_QUERY_STRING, or
REQUEST_TYPE_POST.  Using a requestType of REQUEST_TYPE_AUTO is
recommended.

***** IMPORTANT NOTE *****

If the getExtendedBrowserInfo() method returns a value of null, you
should immediately issue a 'return;' to end processing of the
servlet/JSP.  BH4J will then call your page back a second time, except
this time it will not return null so processing of your page will
continue.  With this in mind, it is best to call
getExtendedBrowserInfo() as early in your JSP/servlet as possible.

For examples on using getExtendedBrowserInfo(), see the sections below
which discuss detecting disabled cookies and connection speed.  In
addition, there are many examples included in the 'examples' BH4J
subdirectory.

Additional information can be found in the Javadocs included with the
BH4J software.


---------------------------
Property Reference Guide
---------------------------

For detailed information on each property supported by BrowserHawk4J
and their possible return values, see the ExtendedBrowserInfo and
ExtendedOptions classes in the included JavaDocs.

You can also read through the Property Reference Guide at:
http://www.cyscape.com/docs/showhelp.asp?topic=about_the_property_and_method_guide


------------
LICENSING
------------

BrowserHawk4J is provided under the terms and conditions set forth in
the BrowserHawk4J End User License Agreement (EULA).  A copy of the
EULA is included with your BrowserHawk4J software.  Please be sure to
carefully read and understand the EULA before continuing.  Placing the
BrowserHawk4J software or any of its related files on your server, or
using BrowserHawk4J in any way, constitutes your full and
unconditional acceptance of the EULA.


------------------------------------------------------------------------
SPECIAL NOTE TO USERS OF BROWSERHAWK4J ACROSS LOAD-BALANCED SERVERS / 
  SPECIAL PROXIES
------------------------------------------------------------------------

If you are using BrowserHawk4J in a web server environment which
consists of load balanced servers or special proxy services (such as
those which hide or munge URLs) it may be necessary for you to take a
few additional steps in order to use the getExtendedBrowserInfo()
method.

The getExtendedBrowserInfo() method requires that BrowserHawk4J
intercept an initial request for a JSP or servlet page, perform a
quick test, and then reload the requested JSP/servlet automatically
(by issuing a redirect back to the same JSP/servlet).  This process is
extremely fast and transparent to the end user.  However if you find
that BH4J does not use the correct URL in the redirect (such may be
the case due to a load balancer or special proxy), you can configure
BH4J to use the exact base URL by editing the browserhawk.properties
file or calling ExtendedOptions.setServerURL().  See the comments in
the properties file for details.

In addition, if you are using the cookie based requestType
(REQUEST_TYPE_AUTO or REQUEST_TYPE_COOKIE) in a load balanced server
environment where multiple requests from the same visitor may be
handled by a different server, you must configure the ExtendedOptions
by calling setCookieDomain() passing in ".{yourdomain}.com" prior to
calling getExtendedBrowserInfo().  For example ".cyscape.com" (note
the preceeding '.' is mandatory).  This effectively sets the cookie's
domain property to this value so that the BH4J cookie that holds the
answer can be read by any of the servers in your farm.


------------
UPGRADING
------------

You can upgrade from older versions of BrowserHawk to version 14 simply by
performing the following basic steps:

1) Search your hard drive for ALL copies of bhawk4j.jar on your system, and
   overwrite all copies found with the bhawk4j.jar file included in this
   distribution.

2) Do the same with maindefs.bdd.

3) Do the same with BrowserHawk4J.cfm (in the samples/cfmx directory,
   used by any CFMX scripts).

4) If upgrading from BrowserHawk 9.x thru 12.x, you can use the same
   browserhawk.properties file as earlier.  (There are no new properties
   entries in 11.0.)

5) Make sure to install the new license.  If it has a new name make sure to
   assign that name in browserhawk.properties.

6) Copy the new webapps/bhawk/webfiles/bhawkcap.swf to the web directory
   containing your JSPs or other scripts.

Optional:

7) Copy over the new samples.

8) Copy over the Javadocs from under docs.

9) If using BRWS4J, upgrade your database schema to understand the new
   properties.  An oracle-upgrade.sql is provided as a sample.


----------------------------------------
INSTALLATION IN A SINGLE WEB APPLICATION
----------------------------------------

Note: If you encounter any problems after installation, or if you
require further clarifications, please see the TROUBLESHOOTING section
of this document.

To extract the software use WinZip or equivalent tool to extract the files
from the .zip file into a subdirectory where you wish to house the files.

ATTENTION COLDFUSION MX USERS: If you will use BH4J with ColdFusion MX,
skip ahead to the section below titled "INSTALLATION FOR USE WITH
ColdFusion MX" for specific steps on installing for use with CFMX.
-------

To install into a single "web application" on your server (same
instructions for all platforms):

0. Note this requires a server implementing Servlet API 2.2 or later.
   If your server does not support API 2.2 or later, then it doesn't
   support "web applications", and you should continue down to the
   instructions for installing BrowserHawk4J across a full server.

1. Copy the webapps/bhawk directory into the appropriate webapps 
   directory of your server.  The "bhawk" directory is a pre-created
   web application with ready-to-use sample JSP and servlet files.
   It has a bhawk4j.jar file in its WEB-INF/lib directory and various
   support files in the WEB-INF/classes directory.

2. Place your license key into the WEB-INF/classes directory.

   License key installation for free evaluation version:  If you are
   using an evaluation copy of BrowserHawk4J, the license key you need is
   named bh_evalkey.lic.  The bh_evalkey.lic file is distributed separately
   from this BrowserHawk4J software.  You can download an evaluation
   license key from www.cyscape.com/products/bhawk if you have not
   done so already.

   To install this key, place it in the location as described at the top of
   this section.

   License key installation for purchased copies:  When you purchase
   BrowserHawk4J, you will receive a license key by email with your order.
   This key is in the format your_name.lic (such as bob_smith.lic).

   To install this key:

     - Place the key in the location as described at the top of this
       section

     - Edit your browserhawk.properties file, changing the entry
       "license.file" from "bh_evalkey.lic" to the name of your license
       file (i.e. bob_smith.lic).

3. If you plan to test the JavaVendor, JavaVersion, OSName, OSArch,
   OSVersion, BrowserBitSize, MSJVMBuild, and/or MSBuildIncrement
   properties, note the JVMDetector.class is placed within the web
   application root.  You can move this file to any other location
   accessible to the visitor's browser (the same as if it was any other
   applet).  If you want to move it you can use the setJVMCodeBase() method
   on ExtendedOptions.

4. If you plan to test open ports, please see the section TESTING OPEN PORTS
   below.

5. If you plan to test SSL enabled or SSL key size, please see the section
   TESTING SSL ENABLED and TESTING SSL KEYSIZE below.

6. After installing we recommend you trying one of the examples included
   with this software to verify your successful installation.  See the
   "INCLUDED EXAMPLES/SAMPLES" section of this document for more information.


----------------------------------------------------------
INSTALLATION ACROSS ALL WEB APPS FOR THE ENTIRE SERVER
----------------------------------------------------------


To install across all web applications for the entire server (same
instructions for all platforms):

0. The files by default are placed in a WAR format appropriate for single
   web app deployment, so you will need to copy them from this format to
   the directories appropriate for your server's server-wide deployment.

1. Ensure the bhawk4j.jar file (found under webapps/bhawk/WEB-INF/lib)
   is placed within your server's classpath.  Depending on your web 
   server, this may require copying the file to an appropriate location,
   changing your server's startup script, changing your server's 
   configuration files, or making a change through a graphical administration
   tool.  See your server's documentation for details.
   Note that setting the system CLASSPATH variable may not be sufficient; 
   it's the server program's CLASSPATH that must be set.  Remember, placing 
   a JAR file in a directory in your CLASSPATH is not sufficient; the 
   CLASSPATH must include a direct reference to the file (/dir/bhawk4j.jar).

2. Place the browserhawk.properties, maindefs.bdd, bhawk_sp.dat, and
   bhawk_bb.dat files (found under webapps/bhawk/WEB-INF/classes) somewhere
   in your server's CLASSPATH.  Also place your license key file under the 
   CLASSPATH.  Any directory in the classpath is fine.  Do not place them 
   inside a JAR file.

   License key installation for free evaluation version:  If you are
   using an evaluation copy of BrowserHawk4J, the license key you need is
   named bh_evalkey.lic.  The bh_evalkey.lic file is distributed separately
   from this BrowserHawk4J software.  You can download an evaluation
   license key from www.cyscape.com/products/bhawk if you have not
   done so already.

   To install this key, place it in the location as described at the top of
   this section.

   License key installation for purchased copies:  When you purchase
   BrowserHawk4J, you will receive a license key by email with your order.
   This key is in the format your_name.lic (such as bob_smith.lic).

   To install this key:

     - Place the key in the location as described at the top of this
       section

     - Edit your browserhawk.properties file, changing the entry
       "license.file" from "bh_evalkey.lic" to the name of your license
       file (i.e. bob_smith.lic).

3. If you plan to test the JavaVendor, JavaVersion, OSName, OSArch,
   OSVersion, BrowserBitSize, MSJVMBuild, and/or MSBuildIncrement
   properties, place the JVMDetector.class (found under webapps/bhawk)
   somewhere within the web content that is accessible to the visitor's
   browser (the same as if it was any other applet).  For example,
   webapps/ROOT.  The applet is found automatically by the browser if you can
   use the same directory holding the page calling getExtendedBrowserInfo().
   Otherwise, you can just place it anywhere in the web application but you
   must inform the browser where to find it using the setJVMCodeBase() method
   on ExtendedOptions.

4. If you plan to test open ports, please see the section TESTING OPEN PORTS
   below.

5. If you plan to test SSL enabled or SSL key size, please see the section
   TESTING SSL ENABLED and TESTING SSL KEYSIZE below.

6. After installing we recommend you trying one of the examples included
   with this software to verify your successful installation.  See the
   "INCLUDED EXAMPLES/SAMPLES" section of this document for more information.

----------------------------------------------------------
INSTALLATION FOR USE WITH COLDFUSION MX AND IIS (Windows)
----------------------------------------------------------

0. Assuming you have a stand alone installation of CFMX (not the J2EE option)
   there will be a "lib" and "classes" directory under
   <CFInstallationDir>\wwwroot\WEB-INF.  For example,
   \CFusionMX7\wwwroot\WEB-INF\classes and \CFusionMX7\wwwroot\WEB-INF\lib.

   These directories will be the target for many of the BrowserHawk4J
   installation files.  

   If you are using the J2EE option then the path for these target directories
   is <CF war directory>\WEB-INF\lib and <CF war directory>\WEB-INF\classes.
   In this case substitute <CF war directory> in place of <CFInstallationDir>
   in the directions below. Or, instead you may wish to follow the instructions
   in the sections above for installing for a web application or all web apps.
   
1. Copy all files from the .zip's webapps\bhawk\WEB-INF\classes directory into
   <CFInstallationDir>\wwwroot\WEB-INF\classes

2. Copy the bhawk4j.jar file out of the .zip's webapps\bhawk\WEB-INF\lib
   directory into <CFInstallationDir>\wwwroot\WEB-INF\lib

3. For evaluation usage: Place a copy of the bh_evalkey.lic in
   <CFInstallationDir>\wwwroot\WEB-INF\classes.  bh_evalkey.lic is available
   from the bh_evalkey.zip file you downloaded from our web site after
   registering for the evaluation download. If you do not have it, download
   another copy from http://www.cyscape.com.

   For purchased licenses: Place your purchased license key in
   <CFInstallationDir>\wwwroot\WEB-INF\classes.  This key was sent to you with
   your order, and is typically in the format of "Your Name.lic".  Then edit the
   browserhawk.properties file (which was copied to
   <CFInstallationDir>\wwwroot\WEB-INF\classes in step 1 above) to change the
   value of the "license.file" entry to point to the name of your license key.
   For example, change:
        license.file=bh_evalkey.lic
      to:
        license.file=Bob_Smith_Ent.lic

4. Assuming your localhost is set up to run web pages out of \inetpub\wwwroot,
   copy all files located in the .zip's \webapps\bhawk\webfiles directory into
   \inetpub\wwwroot.  If your base directory that you run CFMX apps is
   different than this, put these files there instead.

5. *** YOU MUST RESTART THE ColdFusion MX Application Server service after 
   performing these steps (or reboot) in order for ColdFusion MX to recognize
   these newly installed files.

6. Optional: Install the BrowserHawk CFMX samples.  Do this by copying the
   \webapps\bhawk\cfmx folder in your .zip file along with all the folder's
   contents to a web directory such as \inetpub\wwwroot.  Then point your
   browser to the web location of the index.html file within that directory.
   For instance:
      http://localhost/cfmx/index.html

   Running these samples is an excellent way to confirm your installation was
   successful.  The samples also are an excellent learning aid for best
   understanding how to use BrowserHawk4J with CFMX.  The source code in the
   samples has been heavily documented for this purpose.

7. See the section in this document titled "USING BROWSERHAWK FROM COLDFUSION
   MX" for an overview of how to use BrowserHawk with ColdFusion MX, including
   information about the BrowserHawk custom tag that ships with this product.

8. NOTES:

   - If you plan to test the JavaVendor, JavaVersion, OSName, OSArch,
     OSVersion, BrowserBitSize, MSJVMBuild, and/or MSBuildIncrement
     properties, be sure the JVMDetector.class (found under webapps/bhawk
     in the .zip) is located somewhere within the web content that is
     accessible to the visitor's browser (the same as if it were any other
     applet).  For example, \inetpub\wwwroot.  The applet is found
     automatically by the browser if your CFM page running the BrowserHawk
     code is located in the same directory as this applet.  Otherwise, you
     can just place the applet anywhere in the web application but you must
     inform the browser where to find it using the setJVMCodeBase() method
     on ExtendedOptions.

   - If you plan to test open ports, please see the section TESTING OPEN PORTS
     below.

   - If you plan to test SSL enabled or SSL key size, please see the section
     TESTING SSL ENABLED and TESTING SSL KEYSIZE below.


----------------------------------------------------------
INSTALLATION FOR USE WITH COLDFUSION MX (NON-WINDOWS)
----------------------------------------------------------


1. Install the CFMX product on your server.  The development kit is available
   for download from www.macromedia.com.  Installation instructions vary by 
   servlet engine. Tomcat instructions can be found at 
   http://www.macromedia.com/support/coldfusion/j2ee/phase2-tomcat-deploy.html.

2. There will be a "CFusionMX\wwwroot" or "cfusion" (or similarly named) web 
   application directory created during CFMX install.  We'll call this CFDIR.
   Copy the bhawk/WEB-INF/lib contents into the CFDIR/WEB-INF/lib directory,
   and copy the bhawk/WEB-INF/classes contents into the CFDIR/WEB-INF/classes
   directory.

   When extracting these files, be sure to set your unzip utility so that it
   does NOT preserve the file paths found in the .zip.

3. Copy the files in the bhawk directory to the CFDIR directory.
   You should at minimum copy over JVMDetector.class, BrowserHawk4J.cfm,
   bh4jtagtest.cfm, and showbrow.cfm.  You can copy the JSP files if
   you're interested in JSP.

4. Restart your ColdFusion services and any related web services.  Sometimes
   this is necessary for CFMX to recognize the BH4J classes you copied over.

5. Browse to the included CFM samples you wish to run.  For example, the
   URL might look like http://yourserver:yourport/showbrow.cfm.  If you
   receive an error that a BrowserHawk class cannot be found, the most likely
   reason is that you either did not restart your ColdFusion services after
   installing the files, or that you installed the files in the incorrect
   directories.  Do not try to run BrowserHawk4J.cfm directly, as that file
   is just a tag.


------------------------------
INSTALLATION FOR USE WITH PHP
------------------------------

BrowserHawk4J can integrate with PHP pages when used in conjunction with
a PHP/Java Bridge component.  Please see the file PHP_README.txt for
installation and usage instructions. Note that use with PHP is unsupported.


---------------------------------------------------------------
TESTING OPEN PORTS
---------------------------------------------------------------

BrowserHawk tests open ports by causing the browser to make a background
request for an image file to a server using the port in question.  If it
succeeds, the port is open; if not, the port is most likely closed.  This test
requires a server be listening on any ports being tested.  The default is to
use the server http://pchk.cyscape.com and the resource /bhawkp1.gif, thus
making requests to http://pchk.cyscape.com/bhawkp1.gif for port 80,
http://pchk.cyscape.com:554/bhawkp1.gif for port 554, and
http://pchk.cyscape.com:1755/bhawkp1.gif for port 1755.  

It's very important that you change the server used for the tests to one under
your control for production use!  They cyScape server is for development only
and may not always be available.  In fact, the BrowserHawk software license
legally requires you to use a separate server for production purposes.  You
can configure the server by editing browserhawk.properties and changing the
extended.port.check.url property, or to make changes on a page-by-page basis
you can call ExtendedOptions.setPortCheckURL().

To configure which ports to test, again go to browserhawk.properties and edit
extended.port.check to be a comma-separated list of ports.  You can also call
ExtendedOptions.setPortsToCheck().  You'll find a bhawkp1.gif included in the
distribution for your convenience.

Note that testing open ports on a page requested via https might
normally cause the browser to emit a warning to the user about insecure
items in a secure page.  To avoid this warning, if the page testing
ports is using https, the ImagesEnabled test uses the
extended.ssl.check.url server to do its test.  If you will be testing
ImagesEnabled from an https page, make sure to include the
extended.port.check.resource graphic on the extended.ssl.check.url
machine.


---------------------------------------------------------------
TESTING SSL ENABLED
---------------------------------------------------------------

BrowserHawk tests if SSL enabled in a manner similar to how it tests
open ports.  It attempts to make a background secure connection to fetch
an image and, if it succeeds, determines that SSL is enabled and if not,
determines that it's not.  As with testing open ports, this test
requires you have a server listening using HTTPS.  The default is to use
the server https://schk.cyscape.com and the same resource as open ports
(/bhawkp1.gif).

IT'S VERY IMPORTANT for production use that you change the secure server
to one under your control!  You can configure the server to use by
editing browserhawk.properties and changing the extended.ssl.check.url
property, or to make changes on a page-by-page basis you can call
ExtendedOptions.setSSLCheckURL().


---------------------------------------------------------------
TESTING SSL KEYSIZE
---------------------------------------------------------------

BrowserHawk has two ways to test the SSL key size.  The first is "static"
where BrowserHawk examines the properties of the secure connection used to
connect to the servlet or JSP.  This feature existed in BrowserHawk 5.0.
Sometimes this doesn't work, however, because not all servers expose the SSL
connection information as the spec requires.

BrowserHawk 6.0 added an extended ability to determine SSL key size which works
even when your production server doesn't support exposing SSL information to
the servlet/JSP environment.  This extended property detection causes the
browser to make a background connection to an SSL server running a special
dynamic page.  This dynamic page returns to the browser the current key size,
and that information can be included in the BrowserHawk results.  This
approach has the advantage that SSL key size can be determined even when the
production server doesn't support key size detection or when the original
request page wasn't available using HTTPS.

The extended test requires running a secure server with the special page to
report the key size.  The default server URL is https://schk.cyscape.com.  As
with all these tests, for production use YOU MUST CHANGE THIS.

The default resource is /sslcheck.asp, which is provided with the BrowserHawk
distribution under webapps/bhawk/ssl.  This ASP page is designed to run inside
a Microsoft IIS installation with BrowserHawk for ASP installed.  If you have
a servlet engine that supports key size detection (perhaps not your main
server but a side server you can install like Apache Tomcat), you can change
the resource to /sslcheck.jsp and run it on the side server.  The JSP file is
also provided with the distribution in webapps/bhawk/ssl.

You can alter the resource to use in browserhawk.properties by changing the
extended.ssl.check.resource property, or make page-by-page changes using
ExtendedOptions.setSSLCheckResource().


---------------------------------------------------------------
TROUBLESHOOTING (Knowledgebase at http://www.cyscape.com/kb)
---------------------------------------------------------------

If BrowserHawk4J is not working after your installation, or you encounter
problems with it following a successful installation, please review the
following troubleshooting check list:


Have you looked at the log output?
-----------------------------------

Anytime BrowserHawk4J encounteres an error or possible misconfiguration, it
sends a description message to the server's standard error.  Exactly where
this output is displayed depends on the server, and may be non-obvious.  Some
servers have a system console where the messages will appear; others have a
log file to hold standard error.  Be sure to look for standard error messages
to be fully informed of problems BrowserHawk4J encounters.


Did you install a license?
---------------------------

BrowserHawk4J requires a license key.  When BrowserHawk4J can't find a
license file, the getBrowserInfo() method throws a runtime LicenseException
whose message explains the license file does not exist (Error 1260).  If you
never downloaded a license, you can do so at 
http://www.cyscape.com/products/bhawk

If you downloaded a license and the server isn't able to find it, be sure the
license is in the server's classpath and that the name of the license file is
correctly set in the browserhawk.properties file in the "license.file"
entry.  The default name is "bh_evalkey.lic" which is used for the evaluation
license.  If you are using a purchased key, change this name to match the
name of the key sent to you after purchasing the product.

For more information on installing your license key please see item #2 under
the INSTALLATION section above.


For problems installing BrowserHawk across all web applications, did you 
remember to change your server's classpath, not just the system classpath?
---------------------------------------------------------------------------

BrowserHawk4J locates classes and data files by searching the server's
classpath.  With most web and application servers this classpath is
different than the system classpath, and must be set specifically
according to the server's administration tools, configuration files,
or startup script.  You can determine your server's classpath by
having a servlet or JSP page print the value of
System.getProperty("java.class.path"). Make sure you installed the
BrowserHawk4J files based on this class path setting and not the
system's class path.

A common server-wide installation problem is putting the bhawk4j.jar
file into the class path, but not explicitly adding the full file name
to your class path.  Remember, as noted in the INSTALLATION
instructions, placing a JAR file in a directory in your CLASSPATH is
not sufficient; the CLASSPATH must include a direct reference to the
file (/dir/bhawk4j.jar).


Has your evaluation license expired?
-------------------------------------

Evaluation licenses are only valid for a certain period of time and
will expire.  When BrowserHawk4J finds an expired license, the
getBrowserInfo() method throws a runtime LicenseException whose
message says the evaluation key has expired (Error 1271).
BrowserHawk4J supports only one evaluation period.  You can purchase
non-expiring license by visiting http://www.cyscape.com/order.


Could your purchased license key be for an earlier version of the product?
---------------------------------------------------------------------------

When you purchase BrowserHawk4J, you are licensing a specific version
of the product.  A major version upgrade (for example, 6.x to 7.0) will
require the purchase of an upgrade at a significant discount.  If you
try to use a license key for an earlier version of the product with an
newer version of the product, the getBrowserInfo() method throws a
runtime LicenseException whose message says the license was for the
wrong version of the product (Error 1282). You can purchase a valid
license by visiting http://www.cyscape.com/order. First email us your
license key so we can send you information on how to upgrade at a
discount.


Could the license be corrupt?
------------------------------

When BrowserHawk4J detects a corrupt license file, the
getBrowserInfo() method throws a LicenseException whose message says
the license key has invalid data (Error 1270).  This can happen if the
license key is accidentally modified or gets corrupted somehow during
the download.  If you are using an evaluation version of the license
key, try downloading it again.  If you are using a purchased version
of a license key, try replacing your .lic file with a copy from the
original version that was sent to you after ordering.  If the problem
persists, contact us at support@cyscape.com.


Did you put the support files in the right place?
--------------------------------------------------

If you're having problems with Java-related properties, make sure
JVMDetector.class is in the same directory as your JSP or that you've
configured ExtendedOptions to use setJVMCodeBase() to point at the virtual
directory.  This solves the "Applet not inited" error.

If you're having problems with speed detection, make sure bhawk_sp.dat is
somewhere in your server's CLASSPATH.

If you're having problems with broadband detection, make sure bhawk_bb.dat is
somewhere in your server's CLASSPATH.

If you're having problems with open port checking, make sure you have your
side server setup listening on all the ports you want tested and that the
server URL and resource properties are configured to point at this server.

If you're having problems with SSL enabled or key size checking, make sure you
have your secure side server setup and listening for HTTPS traffic and the
server URL and resource properties are configured to point at this server.


Is the open port check unreliable?
-----------------------------------

Try increasing the firewall timeout from 3000 to 5000 or higher.  That gives
the test more time to wait for a response.


Is Plugin_FlashBlocked returning 1?
------------------------------------

If you are consistently receiving a returned value of 1 for this property
for all users (indicating Flash is blocked) when you are certain that Flash
is indeed not blocked, then it means the bhawkcap.swf file needed for this
test is not in the right location. See the installation steps above.


Is OSBitSize returning -3?
---------------------------

If you consistently get a value of -3 for this property for all non-IE
browsers the most likely cause is that the bhawkcap.swf file is not located
in the same directory as your web script that is performing the OSBitSize
test.  See the installation steps above.


Are you having another problem?
--------------------------------

You can find additional technical support information an information
on any updates that may be available from http://www.cyscape.com/kb.
If you require additional information please contact us at
support@cyscape.com.


-----------------------
SUPPORT AND FEEDBACK
-----------------------

If you require technical support for BrowserHawk4J, please start by checking
our detailed knowledgebase at:

   http://www.cyscape.com/kb

If your question is not answered there, please use its submission
option to post your question.  Or if you prefer you can email us at
support@cyscape.com.  Be sure to include a detailed description of
your question or issue (including the exception stack trace, if any),
along with your operating system, JVM version and vendor, and which
web server you are using.

Likewise we are always interested in hearing your comments and
suggestions.  Feel free to email us to let us know what you think or
to suggestion new product features or updates.

-----------------------------------
USING BROWSERHAWK FROM A SERVLET
-----------------------------------

Using BrowserHawk from a servlet is simple:

1. Install BrowserHawk as described above.

2. Import the BrowserHawk package.

import com.cyscape.browserhawk.*;

3. Get a BrowserInfo object.

BrowserInfo b = BrowserHawk.getBrowserInfo(req);

4. Use the BrowserInfo object to learn about the client.

float version = b.getVersion();
boolean tables = b.getTables();
boolean javaScript = b.getJavaScript();
float javaScriptVer = b.getJavaScriptVer();
int keySize = b.getSSLKeySize();
// etc

For full details on what methods are available on BrowserHawk and
BrowserInfo, see the Javadoc documentation under the docs directory.

Examples using BrowserHawk4J from a servlet page are available in the
webapps/bhawk/java subdirectory.

To try out the servlet examples, simply copy the servlet .java and
.class files to wherever your server expects servlets.  This location
depends on your web server, and some servers require editing a web.xml
deployment descriptor file.  With the servlets properly installed, you
can access them using URLs such as the following:

http://localhost:8080/servlet/ShowBrowser
http://localhost:8080/servlet/Redir
http://localhost:8080/servlet/EncryptResponseServlet

The exact URLs to use depends on your web server configuration.

The first access may take a few seconds (depending on your hardware) while
the server processes its browser configuration data.  All subsequent accesses
will be nearly instantaneous.

-------------------------------
USING BROWSERHAWK FROM A JSP
-------------------------------

Using BrowserHawk from a JSP page is also easy:

1. Install BrowserHawk as described above.

2. Import the BrowserHawk package.

<%@ page import = "com.cyscape.browserhawk.*" %>

3. Get a BrowserInfo object.

<% BrowserInfo b = BrowserHawk.getBrowserInfo(request); %>

4. Use the BrowserInfo object to learn about the client.

Your browser version is <%= b.getVersion() %>

Your keysize is <%= b.getSSLKeySize() %>

<% if (!b.getBrowser().equals("Netscape")) { %>
  This site requires Netscape.
<% return; } %>

For full details on what methods are available on BrowserHawk and
BrowserInfo, see the Javadoc documentation under the docs directory.

Examples using BrowserHawk4J from a JSP page are available in the
webapps/bhawk/jsp subdirectory.

To try out the JSP examples, copy the .jsp files to somewhere under your web
server's document root.  Then access them using URLs such as:

http://localhost:8080/showbrow.jsp

Again, the exact URL depends on your web server configuration.

The first access may take a few seconds (depending on your hardware) while
the server processes its browser configuration data. All subsequent accesses
will be nearly instantaneous.


----------------------------------------
USING BROWSERHAWK FROM COLDFUSION MX
----------------------------------------

BrowserHawk4J integrates seamlessly with Macromedia's ColdFusion MX
technology.  To make using BrowserHawk4J even easier, we've included
a sample custom tag called CF_BrowserHawk4J under the file name
BrowserHawk4J.cfm. To use this custom tag, please it in the same
directory where your ColdFusion MX pages run from, or in your global
custom tags directory.

This custom tag returns test results for some of the most popular BrowserHawk
tests, including detecting browser type, version, platform, broadband vs.
dialup connections, Flash and Acrobat plugins, disabled cookies/JavaScript
and more.

You will likely want to customize this tag to remove checks for properties
you are not interested in, and to add checks for properties you want to detect
which are not already included.  See the source for BrowserHawk4J.cfm for
more info.

If you prefer, you can use BrowserHawk4J without the custom tag as well. Most
of the included CFMX samples run without the custom tag, so you can study
these samples to see how they work.  


-----------------------------------------------------------
USING BROWSERHAWK FROM ASP (ACTIVE SERVER PAGES) OR ASP.NET
-----------------------------------------------------------

Although you should be able to call the BrowserHawk4J JavaBean from ASP
pages using various Java to COM wrappers, it is highly recommended instead
that you use the native BrowserHawk ActiveX or .NET component, available
separately, for use under ASP or .NET.  The ActiveX/.NET versions of
BrowserHawk are specifically made and optimized for using under ASP and
ASP.NET respectively and will provide best overall results under that
environment.


--------------------------------------------------------
PERFORMING EXTENDED PROPERTY DETECTION FROM A SERVLET
--------------------------------------------------------

BrowserHawk4J has the ability to determine many extra properties about
the browser such as whether JavaScript and Java are enabled, the
current width and height of the browser desktop, the available width
and height of the browser window, the color depth of the client, and
whether various plugins are installed or not (and often what version
of each plugin).  The connection speed and whether permanent and
session cookies are enabled are alaos available as extended
properties.  Performing extended property detection is done as
follows:

1. Install BrowserHawk as described above.

2. Import the BrowserHawk package.

import com.cyscape.browserhawk.*;

3. Create an ExtendedOptions object.

ExtendedOptions opts = new ExtendedOptions("complete");  // test all props
opts.setRequestType(opts.REQUEST_TYPE_COOKIE);           // AUTO is default
// The following is needed to test the JavaVersion, JavaVendor, and MSJVMBuild
// properties.
// Set the virtual directory where the applet class is found, for example
// "/" if it's in the document root.
opts.setJVMCodeBase("/");      // location of JVMDetector.class applet

4. Get a ExtendedBrowserInfo object.

ExtendedBrowserInfo einfo = BrowserHawk.getExtendedBrowserInfo(req, res, opts);

There are also forms of getExtendedBrowserInfo() which allow for
various convenience calls.  See the Javadoc documentation for details.

5. If the value returned is null, you should return immediately from
the doGet() method.  A null value indicates a response has been sent
to the client by BrowserHawk4J and the client will immediately be
making another request to this servlet that will include information
about its properties.

if (einfo == null) return;

6. If the value returned is the ExtendedBrowserInfo.UNSUPPORTED
constant, that means this feature is not supported on the current
client.  Currently all Netscape, IE, and Opera browsers are supported.

if (einfo == ExtendedBrowserInfo.UNSUPPORTED) {
  // Deal with unsupported browser
}

7. If the object returned has getJavaScriptEnabled() return false,
that means that JavaScript is disabled on the current client and very
few properties will be available (such as cookies).

if (einfo.getJavaScriptEnabled() == false) {
  // Deal with limited availability
}

8. If the browser is supported and JavaScript is enabled, you can
extract the information from the ExtendedBrowserInfo instance.

boolean javaEnabled = einfo.getJavaEnabled();
String javaVersion = einfo.getJavaVersion();
int timeZoneDiff = einfo.getTimeZoneDiff();
int connectionSpeed = einfo.getConnectionSpeed();
int height = einfo.getHeight();
int heightAvail = einfo.getHeightAvail();
int width = einfo.getWidth();
int widthAvail = einfo.getWidthAvail();
int flash = einfo.getPluginFlash();
String flashVerEx = einfo.getPluginFlashVerEx();
int director = einfo.getPluginDirector();
String directorVerEx = einfo.getPluginDirectorVerEx();
int qt = einfo.getPluginQuickTime();
int acrobat = einfo.getPluginAcrobat();
int acrobatVerEx = einfo.getPluginAcrobatVerEx();
int real = einfo.getPluginRealPlayer();
int media = einfo.getPluginMediaPlayer();
String mediaVerEx = einfo.getPluginMediaPlayerVerEx();
String connectionType = einfo.getConnectionType();
int colorDepth = einfo.getColorDepth();
String referrer = einfo.getReferrer();
// etc...

For details on what each property represents, see the Javadoc
documentation.


----------------------------------------------------
PERFORMING EXTENDED PROPERTY DETECTION FROM A JSP
----------------------------------------------------

BrowserHawk4J has the ability to determine many extra properties about
the browser such as whether JavaScript and Java are enabled, the
current width and height of the browser desktop, the available width
and height of the browser window, the color depth of the client, and
whether various plugins are installed or not (and often what version
of each plugin).  The connection speed and whether permanent and
session cookies are enabled are alaos available as extended
properties.  Performing extended property detection is done as
follows:

1. Install BrowserHawk as described above.

2. Import the BrowserHawk package.

<%@ page import = "com.cyscape.browserhawk.*" %>

3. Create an ExtendedOptions object.

<%
ExtendedOptions opts = new ExtendedOptions("complete");  // test all props
opts.setRequestType(opts.REQUEST_TYPE_COOKIE);           // AUTO is default
// The following is only needed if the JVMDetector.class is in a different
// directory than the calling JSP
//opts.setJVMCodeBase("/");
%>

4. Get a ExtendedBrowserInfo object.

<%
ExtendedBrowserInfo einfo =
  BrowserHawk.getExtendedBrowserInfo(request, response, opts);
%>

There are also forms of getExtendedBrowserInfo() which allow for
various convenience calls.  See the Javadoc documentation for details.

5. If the value returned is null, you should return immediately from
the JSP.  A null value indicates a response has been sent to the
client by BrowserHawk4J and the client will immediately be making
another request to this JSP that will include information about its
properties.

<% if (einfo == null) return; %>

6. If the value returned is the ExtendedBrowserInfo.UNSUPPORTED
constant, that means this feature is not supported on the current
client.  Currently Netscape, IE, and Opera browsers are supported.

<%
if (einfo == ExtendedBrowserInfo.UNSUPPORTED) {
  // Deal with unsupported browser
}
%>

7. If the object returned has getJavaScriptEnabled() return false,
that means that JavaScript is disabled on the current client and very
few properties will be available (such as cookies).

<%
if (einfo.getJavaScriptEnabled() == false) {
  // Deal with limited availability
}
%>

8. Any other value means the extra information is available and you can
extract the information from the ExtendedBrowserInfo instance.

<%
boolean javaEnabled = einfo.getJavaEnabled();
String javaVersion = einfo.getJavaVersion();
int timeZoneDiff = einfo.getTimeZoneDiff();
int connectionSpeed = einfo.getConnectionSpeed();
int height = einfo.getHeight();
int heightAvail = einfo.getHeightAvail();
int width = einfo.getWidth();
int widthAvail = einfo.getWidthAvail();
int flash = einfo.getPluginFlash();
String flashVerEx = einfo.getPluginFlashVerEx();
int director = einfo.getPluginDirector();
String directorVerEx = einfo.getPluginDirectorVerEx();
int qt = einfo.getPluginQuickTime();
int acrobat = einfo.getPluginAcrobat();
int acrobatVerEx = einfo.getPluginAcrobatVerEx();
int real = einfo.getPluginRealPlayer();
int media = einfo.getPluginMediaPlayer();
String mediaVerEx = einfo.getPluginMediaPlayerVerEx();
String connectionType = einfo.getConnectionType();
int colorDepth = einfo.getColorDepth();
String referrer = einfo.getReferrer();
// etc...
%>

For details on what each property represents, see the Javadoc documentation.

An example demonstrating extended property detection from a JSP is available
as showbrow.jsp in the webapps/bhawk/jsp subdirectory.


----------------------------
INCLUDED EXAMPLES/SAMPLES
----------------------------

Several ready to use examples are included with this software in the
folders within webapps/bhawk in the .zip distribution of BH4J.  These
examples serve as a great way to verify that your installation of
BrowserHawk4J was successful.

webapps/bhawk/cfmx
  CFMX examples.  Copy the cfmx folder and all its contents from the
  .zip distribution to a web directory of your choice (such as
  \inetpub\wwwroot).  Then point your browser at the index.html file
  in its destination web location, such as
  http://localhost/cfmx/index.html.

webapps/bhawk/jsp
  JSP examples, ready to run!  Execute jsp/index.html to get started.

webapps/bhawk/java
  Servlet controller examples.  Require placing in WEB-INF/classes or other
  executable environment.



---------------------------------------------
BROWSERHAWK4J REPORTS WEB SERVICE (BRWS4J) 
---------------------------------------------

The BrowserHawk4J Reports Web Service allows you to easily collect and log
detailed, unique statistics about the browser capabilities and settings of
your site visitors.  The BrowserHawk4J Reports Web Services is implemented as
a servlet, known as the BRWS4J.

How BRWS4J works is that the BrowserHawk.logData() method creates an 
<img src="xxx"> tag that is written back to the browser as part of the page
you want to log statistics from.  This tag contains name/value pairs that
instruct the BRWS4J what data to log for each property.  When the browser
makes a request to retrieve this image, it is actually making a request to the
BRWS4J servlet.  The BRWS4J servlet returns a transparent 1x1 pixel GIF to
satisify the browser's request for image, and then proceeds to insert the
statistics to your database.  Therefore to make use of the feature you must
capture the returned img src tag string from the logData() method and write it
into the response. For example:

  <%= BrowserHawk.logData(info, einfo) %>

Use of the BRWS4J requires the Enterprise Edition of BrowserHawk.  Settings
for the default properties to log and the URL of the logging server can be
found in browserhawk.properties and can also be set at run-time using the
ExtendedOptions.setBrwsURL() method or as an extra argument to the logData()
method.

Before you can use the BRWS4J you must install and configure the BRWS4J
servlet, as well as create the database and table where the stats will be
logged.

To assist you with this we have provided the SQL scripts for creating the
database schemas using several popular databases, as well as provided sample
configuration files and a sample BrowserHawk page that logs stats to the
database.  See the brws4j.txt documentation file in the "brws4j" directory.
The BRWS4J servlet and supporting files are in the brws4j.zip within the
"brws4j" directory.


----------------------------------
NOTES ON POST DATA PASS-THROUGH
----------------------------------

BrowserHawk has the ability to retain POST parameter information even during
the two request cycle required for extended property detection.  This
important feature means that if you call getExtendedBrowserInfo() from a page
in a POST request, you won't lose the original POST data.

There is one caveat to be aware of however: If JavaScript is disabled on the
client then BrowserHawk can't add the parameters back to the POST body and
instead attaches them to the query string.  This retains the parameter
information but note that it does alter the mechanism by which the parameters
come in.  For example, this might cause problems if you used POST because the
parameter data was larger than a query string could handle.


---------------
KNOWN ISSUES
---------------

You may notice a ";jsessionid=xxx" added to the request URL as part of
extended property detection if the first request to your site does extended
property detection.  This is an artifact from how servlets and JSPs track
sessions before it's known if cookies are enabled.  When cookies are enabled,
this will disappear after the first request.  You can also avoid it entirely
by turning off session tracking.  Servlets by default have session tracking
turned off until you call request.getSession().  JSPs by default have session
tracking turned on unless you add to your page the special directive: 
<%@ page session="false" %>

Under CFMX under Microsoft IIS the ";jsessionid=xxx" can confuse the server
and causing a 404 Not Found error.  This is an issue with IIS that prevents it
from mapping the URL correctly (due to the semi-colon).  Although not
considered a CFMX bug, Macromedia has issued an enhancement request #46874 for
moving jsessionid to the url query string so that it comes after the ?
delimiter which should resolve the issue.  In the meantime, the suggested work
around by Macromedia is to edit the jrun.ini file and change the
ignoresuffixmap setting to false. The jrun.ini file can be found by default in
the subdirectories located in x:\cfusionmx\runtime\lib\wsconfig.  After
updating this file (or multiple copies of it, as found in the subdirectories)
you must restart your CFMX services.

Under CFMX selecting the POST request type during extended browser detection
can cause looping requests.  This is a known issue with CFMX 6.1 and may be
resolved in a future CFMX version.

Also note that testing "COMPLETE" includes tests for ConnectionSpeed,
Plugin_JavaVer, and PopupsEnabled, each of which can take a little extra
time to complete and when used together can add up to a few seconds.
Furthermore, "COMPLETE" includes tests for OpenPorts, Plugin_Custom,
and FontsInstalled which require special configuration to indicate
which ports, plugins, and fonts to test. 

If the JVMDetector.class applet is not made available to the client, Mozilla
browser clients that have the Java plugin installed may fail to detect client
properties and stall on the special page sent to detect the properties.  The
solution is to ensure the JVMDetector.class is properly installed as per the
instructions above in this file, and to use the
ExtendedOptions.setJVMCodeBase() to specify its location if necessary.  With a
proper install and usage the problem does not happen.


-------------------------------
FILE AND DIRECTORY STRUCTURE
-------------------------------

Here is an overview of the directory structure and file contents of the
BrowserHawk4J distribution:

docs/
  Documentation: This README, Javadocs, CFMX installation notes, BRWS4J
  installation notes, licensing documents, and rules engine details.

webapps/bhawk/
  The directory holding the BrowserHawk classes and configuration, held.
  in a web application folder structure.  See below...

webapps/bhawk/WEB-INF/lib/bhawk4j.jar
  The JAR containing public and private BrowserHawk4J classes.

webapps/bhawk/WEB-INF/classes/bhawk_sp.dat
  A data file to support speed detection.
  
webapps/bhawk/WEB-INF/classes/bhawk_bb.dat
  A data file to support broadband detection.

webapps/bhawk/WEB-INF/classes/browserhawk.properties
  A configuration file where you can specify BrowserHawk default values and
  the license key location.

webapps/bhawk/WEB-INF/classes/maindefs.bdd
  A data file holding information about web browsers and their capabilities.
  You should update this file regularly to stay current with new browser
  versions.

webapps/bhawk/WEB-INF/classes/bh_evalkey.lic
  The license key required for BrowserHawk4J to execute.  This file must
  be obtained separately from the distribution.  The name of the file is
  specified in browserhawk.properties.

webapps/bhawk/webfiles/JVMDetector.class
  An applet class, used to detect the properties JavaVendor, JavaVersion,
  OSName, OSArch, OSVersion, BrowserBitSize, MSJVMBuild, and
  MSBuildIncrement.

webapps/bhawk/webfiles/bhawkp1.gif
  A graphic file, used to detect the properties OpenPorts and SSLEnabled.

webapps/bhawk/webfiles/bhawkcap.swf
  A Flash file, used to detect Plugin_FlashBlocked and OSBitSize.

webapps/bhawk/jsp/
  A samples directory holding numerous JSP samples and an index.html that
  explains each.  The directory also holds a copy of JVMDetector.class,
  so that the examples directory can be self-contained.

webapps/bhawk/java/
  A samples directory holding simple servlet samples.

webapps/bhawk/cfmx/
  A samples directory holding numerous ColdFusion MX samples and an index.html
  that explains each.  The directory, like the jsp directory, holds a copy of
  JVMDetector.class, so that the examples directory can be self-contained.

webapps/bhawk/ssl/
  A directory holding a pair of scripts, one ASP and one JSP, that can be
  used for advanced SSL KeySize detection.

brws4j/
  Location for the BrowserHawk Web Service component.



----------
CHANGES
----------

12.01 to 14.0

(See above introduction.)

12.0 to 12.01

* Enhanced Plugin_JavaVer property to properly recognize Java 1.6 and higher
  for the newer versions of Java. Previously in some cases this resulted in
  the property returning "1.4+" or "2".

* Resolved an issue that caused the tiny popup test window to remain after the
  popup test completed when popups are not blocked.

* Enhanced plugin detection accuracy, including QuickTime version detection
  when Flip4Mac is also present.

* Resolved an issue that caused the Acrobat plug-in version to sometimes be
  returned with a trailing double quote with Chrome.

* Resolved an issue when logging certain fields with "UNSUPPORTED" browsers.

* Resolved an issue in BRWS4J where database connections weren't being
  properly pooled in some circumstances.

* Added the ability to seamlessly recover from attempting to reload a BDD
  data file that is only partially written or otherwise corrupt.

* Removed a dependency on Java 1.5, restoring compatibility with Java 1.4.

* Added additional resilency to the core routines that handle the plugin
  checks.

* Fixed a typo in the showbrow.jsp example.


11.04 to 12.0

* New and improved detection and handling of mobile devices: The new
  MobileDevice and DeviceName properties were added to greatly improve and
  simplify mobile device detection.  MobileDevice returns True for mobile
  devices, and False otherwise.  The one exception is that the iPad is not
  considered a mobile device by design because several customers provided us
  feedback that they do not want to treat it as such.  The DeviceName property
  is set to the name of the device. For example, "iPhone", "iPod Touch",
  "iPad", "Pre", "Pixi", "Droid", "Nexus One", or "Blackberry".

* New and improved connection speed measurement: The ConnectionSpeed test
  was completely rewritten.  Accuracy and consistency of results has been
  greatly improved as a result.  Note that you must explictly tell BH to
  perform the new ConnectionSpeed test.  Otherwise it will continue to use the
  old testing method to ensure backward compatibility.  This more advanced
  test is known as a "Progressive" speed test.  To use a Progressive speed
  test instead of the old-style speed check you must first set the
  SpeedCheckType and SupportFilesRoot properties. See the documentation or
  the "speed.jsp" sample that ships with BH for more information.  You will
  also need to download the supporting data files from
  http://www.cyscape.com/download/speed-supportfiles.zip.

* New connection latency testing: The new ConnectionLatency property
  measures the user's network latency in milliseconds between the user's
  machine and your web server.

* New upload connection speed testing: The new UploadConnectionSpeed and
  UploadConnectionLatency properties measure the upload connection speed and
  latency between the user's machine and your web server.  Requires IE 8+,
  Firefox 3.5+, Safari 4+, or Chrome 5+.  Also requires BrowserHawk Enterprise
  Edition.  Note that upload speed and latency testing will consume bandwidth
  on your server and may increase your hosting bill.  See the SPEED_README.txt
  for details.

* New finer grain control of speed tests: Several new properties were added
  to provide for very fine grain control over the download and upload speed
  measurement tests.  These OPTIONAL properties are SpeedCheckTestSeconds,
  SpeedCheckMaxBpsCutoff, SpeedCheckMaxWait, UploadSpeedCheckTestSeconds,
  UploadSpeedCheckFirstDatasize, UploadSpeedCheckMaxDatasize,
  UploadSpeedCheckMaxWait, and UploadSpeedCheckTargetURL. See the
  documentation for more information.

* Support for new browsers: Added support for IE 9 Preview, Google Chrome 5
  beta, and Opera 10.5+.

* Improved Adobe Flash detection: Detection of Adobe Flash 10.1 is now
  supported.

* Improved Adobe Acrobat version detection: The Plugin_AcrobatVerEx property
  was improved to provide greater accuracy in detection of the Acrobat
  plug-in and to detect the version for IE users which in some cases could not
  be detected with earlier versions of BrowserHawk.

* Improved popup blocker detection: The PopupsBlocked property has been
  rewritten to provide instant detection of blocked popups (previously this
  test took 3 seconds to detect blocked popups) and greater resiliency across
  different blockers.

* Improved BrowserHawk Reports Web Service (BRWS): Several enhancements were
  made to the BRWS, including logging of the new properties (MobileDevice,
  DeviceName, ConnectionLatency, UploadConnectionSpeed,
  UploadConnectionLatency), logging the PersistentCookies property, logging
  optional user data, improved logging for Firefox users, and several fixes
  and enhancements for greater resiliency of the logging.

* Improved Silverlight detection: The Plugin_Silverlight and
  Plugin_SilverlightVerEx properties have been improved to detect the latest
  versions of Silverlight, including Silverlight 4.

* Improved plug-in detection: Various improvements were made to our plug-in
  detection code.

* Expanded Page Load Time (PLT) analytics support: PLT is now supported for
  users with Safari 4+ and Chrome 5+.

* Improved support for Chrome: General improvements were made to the
  handling of the Chrome browser.

* Improved Rules Enforcement Technology (RET) engine: The RET engine now
  supports alternating class styles for alternating rows, and setting
  additional properties in the extended-options setting within the XML.

* Updated and new samples: Several samples were updated and added to
  demonstrate the new features and options in BrowserHawk 12.0.

* Updated documentation: The documentation was updated to reflect changes in
  BrowserHawk 12 and for various edits and improvements.

* Improved Translate method: The translate() method has been enhanced to
  output connection speeds in Mbps or Kbps instead of bits/sec. The
  connection latency is now also included. Other misc improvements.

* Resolved issues with BRWS that caused some proxies to munge the request,
  resulting in no logged data for certain users.

* Resolved an issue that caused BRWS to not log results from some browsers
  due to longer GeckoBuildDate and BrowserDateTime values.

* Resolved issues that caused newer versions of Silverlight to be detected
  as older versions or to be not detected at all.

* Resolved an issue that caused XMLHttpRequest to return False for Google
  Chrome.

* Resolved an issue with the Acrobat plug-in that caused the version number
  not to be detectable under IE in some circumstances.

* PopupTimeout is now depreciated - this property is no longer used as of
  BrowserHawk 12 because of the new, streamlined popup detection no longer
  requires it.

* Resolved an issue with Safari cookie handling that could result in some
  properties not being detected as expected.

* MobileDevice (boolean): Assigned to True for mobile devices (except iPad),
  False otherwise.

* DeviceName (string): Contains the brand name for popular devices (i.e.
  "iPhone", "iPod Touch", "iPad", "Pre", "Pixi", "Droid", "Nexus One",
  or "Blackberry".

* ConnectionLatency (int): Download connection latency in milliseconds
  between the user and your web server.

* UploadConnectionSpeed (int): Upload connection speed in bits per second
  between the user and your web server.

* UploadConnectionLatency (int): Upload connection latency in milliseconds
  between the user and your web server.

* SpeedCheckType (int): Must set to SPEED_CHECK_TYPE_PROGRESSIVE prior to
  calling the extended browser check in order for BH to use the new
  Progressive speed check to measure download speed.

* SupportFilesRoot (string): Must set this to a location on your web server
  where you stored files used by the download connection speed test. See
  docs or samples for details.

* SpeedCheckTestSeconds (int): Desired number of seconds for speed test to
  complete (default 2). Advanced setting.

* SpeedCheckMaxBpsCutoff (int): Desired point to end speed test once
  measured over this threshold, in bits per second (default 0 = fully
  measure). Advanced setting. Do not change without good reason.

* SpeedCheckMaxWait (int): Maximum number of seconds to wait for speed test
  in the event of a connection issue before timing out (default 30).

* UploadSpeedCheckTestSeconds (int): Same as SpeedCheckTestSeconds, except
  controls the Upload speed check instead of download speed check.

* UploadSpeedCheckFirstDatasize (int): Initial data size used in upload
  speed check (default 50,000 bytes). Advanced setting. Do not change
  without good reason.

* UploadSpeedCheckMaxDatasize (int): Maximum data size to use when
  dynamically testing upload speed (default 2,000,000 bytes). Advanced
  setting. Do not change without good reason.

* UploadSpeedCheckMaxWait (int): Same as SpeedCheckMaxWait, except controls
  the Upload speed check instead of download speed check.

* UploadSpeedCheckTargetURL (string): URL target for the browser to POST
  data to as part of the upload speed check (defaults to the page where BH
  is used with a special bhspc=up parameter causing BH to consume the POST
  data). Advanced setting. Do not change without good reason.


11.03 to 11.04

* Updated to detect Flash 10

11.03 to 11.03a

* Resolved an issue with Java detection on IE5 and IE6.

11.02 to 11.03

* Added support for the Google Chrome beta browser.

11.0 to 11.02

* Enhanced Silverlight detection to detect recent releases of the plug-in

10.01 to 11.0

* Rules Enforcement Technology (RET) feature introduced.  RET
  provides an easy way to ensure that each web site visitor meets your
  site's minimum browser and system requirements, and to provide
  automated self-help to those users who do not, based on an XML file
  rather than code logic.  Extensive RET documentation is available
  at www.cyscape.com/download/RETUsersGuide.pdf and included with this
  distribution.  To support RET the RuleEngine and RuleEnginerResult
  classes were added.  See www.cyscape.com/ret for more on RET information.
  Requires Enterprise Edition.

* Added support for detection of the Microsoft Silverlight plug-in
  (new PluginSilverlight and PluginSilverlightVerEx properties in
  ExtendedBrowserInfo class).

* Migrated to Java 1.4 as a base platform instead of Java 1.2.

* Added a workaround for a Safari bug that caused BrowserHawk to
  always detect cookies as enabled in Safari browsers if the user
  first has cookies enabled and later disables their cookies.

* Enhancements were made that provide improved error handling when testing
  for Flash and other plug-ins, as well as the ServicePack property.

* You can now extend BrowserHawk to add your own properties by executing
  any custom JavaScript as part of the BrowserHawk testing. The results are
  then available through the BrowserHawk API, just as if natively provided
  by BrowserHawk. See the new setJSEval(), method on the ExtendedOptions class
  and the new getJSEval() method on the ExtendedBrowserInfo class for more
  info.

* BrowserHawk can now automatically monitor your site for any JavaScript
  errors that users experience, and log these errors to your database. You
  can associate the user ID and session ID for which the error occurred for
  easy troubleshooting. It also provides the ability to log your own custom
  error messages back to the database from your JS code or error handlers.
  See the bhawk_errortracker.js distributed with BH4J for more information.

* Enhancements were made that provide improved error handling when testing
  for Flash and other plug-ins, as well as the ServicePack property.

* Added several new samples which demonstrate how to use Page Load Time
  (www.cyscape.com/plt) and Rules Enforcement Technology (www.cyscape.com/ret).

* Updated the BrowserHawk4J Reports Web Service (BRWS4J) to add support for
  the new BrowserErrors table (used to log JS errors sent by the
  bhawk_errortracker.js script) and to add support for logging the new
  Silverlight properties. Also updated the BRWS4J SQL scripts accordingly.


10.0 to 10.01

* Enhanced Java detection to support Java 1.6.

* Extended the coverage of Java plug-in detection, particularly for Linux
  based browsers.

* Fixed: Extended property tests on IE 5.x on Mac did not execute properly
  under certain conditions.

* Fixed: Extended property caused IE 7 to trigger a message in the InfoBar
  under certain conditions, such as 'The previous webpage might require the
  following add-on: MSXML service pack X, and other such messages.

* Fixed: Testing for Windows Media Player caused IE 7 to trigger a message
  in the InfoBar such as 'The previous webpage might require the following
  add-on: Windows Media 6.4 Player Shim' or 'Windows Media Player Extension'.

* Fixed: Testing for ActiveXEnabled and/or VBScriptEnabled was dependent on
  the user clicking to allow a control to run in order to get a proper test
  result.

* Fixed: Extended property tests under certain conditions caused IE 7 to
  prompt the user to install Java.

* Fixed: Java based tests
  (JavaVendor/JavaVersion/MSJVMBuild/Plugin_JavaVer/OSName/OSArch/OSVersion)
  would cause IE 7 to display the message: 'Click or press enter to activate
  this control'.

* Fixed: Extended property tests did not execute properly for URLs that
  contained multiple semi-colons.

* Fixed: Extended property tests did not execute properly under Netscape 4.x
  and earlier when using the POST requestType.


9.01 to 10.0 (see http://www.cyscape.com/products/bhawk/new.aspx):

* Page Load Times (PLT) feature introduced.  Detailed information about
  this powerful new feature at http://cyscape.com/plt.

* Added support for IE 7.0 and Firefox 2.0.

* Improved Java detection.

* Improved handling of character encodings.

* Added BRWS support for UserID and SessionID columns, as well as a
  new table for Page Load Time recordings.

* New LogOptions class for more flexibility and ease of use, and a PLTOptions
  class to support page load time recording.

* New method signature to getExtendedBrowser() that accepts PLTOptions.

* Added detection of Flip4Mac plug-in.

* Added ability to use JavaScript in the temporary web page displayed during
  an extended property test.

* Resolved an issue that caused an error in the browser when performing a
  connection speed test with the browser set to a non-typical encoding
  preference.

* Resolved an issue that caused Java not to be detected as expected when the
  Java Cocoa or Java Embedding Plugin was used. 

* Resolved an issue that caused an extended property test page to loop under a
  set of rare conditions.

* Resolved an issue that caused the XMLHttpRequest property to always return
  False for Gecko-based browsers.

* Resolved an issue that caused the RealPlayer 10 plug-in to not always be
  detected on Macintosh systems.


9.0 to 9.01:

* Added detection of the Flash 9 plug-in.

* Improved Flash version detection with IE on Windows XP SP2.  Previously
  with IE on XP SP2 only the major version of the Flash plug-in was available.
  Now the complete build is returned.

* Improved detection of RealPlayer 10 on Mac OS X.

* BrowserHawk now looks for a special bhRefresh=1 parameter in the query
  string.  When present, BH will automatically retest the browser even if the
  results are in the ASC.

* Added a new setting options.setSuppressOriginalQueryString(true) to tell
  BrowserHawk not to preserve the original query string during extended
  detection as is done by default.  Only needed in special advanced
  deployments.

* Increased resolution of BrowserDateTimeMs from the nearest second to the
  nearest millisecond.

* Improved handling of any user-provided query string data.

* Updated the BrowserHawk4J Reports Web Service (BRWS4J) installation sample
  XML files to correct the servlet class name shown.

* Optional setBroadbandImageUrl() method now supports relative URLs.

* brws4jtest.jsp sample now included in the distribution.

* Extended property results pages (typically seen with bhcp=1 in the
  querystring) are now set to be non-cachable by the browser.

* Updated handling of PageMessage paramater to support inclusion of custom
  JavaScript in the page.

* Updated image tag used for BrowserHawk4J Reports Web Service logging to be
  XHTML compliant.

* Enhanced extended property detection to prevent non-IE browsers from
  displaying a blank page under rare circumstances when an extended property
  test was performed with a hash character (#) in the query string.


8.03 to 9.0:

* Now includes the BrowserHawk4J Reports Web Service (BRWS4J).  BRWS4J
  can be used to automatically log the BrowserHawk results into a database
  of your choice, without any programming or database schema design
  required.  BRWS4J is implemented as a servlet which listens from requests
  made by BrowserHawk to log its BrowserHawk results. This information
  is set to the BRWS4J servlet as the result of calling BrowserHawk's
  logData() method.  The logData() method has been around for a while, but
  previously required that you had a Windows machine running IIS and the
  ISAPI version of the BrowserHawk Reports Web Service to perform the logging.
  Starting with this release, you now have full native database logging
  available without any requirement for Windows or IIS (although certainly you
  can use BRWS4J on Windows/IIS - you just are no longer required to do so.)
  This is a major enhancement and we encourage all users to explore how easy
  it is to put the power of the BRWS4J to use.  This information proves
  INVALUABLE for troubleshooting end user reported issues, as you can tag a
  user's log in ID or any other information you wish to be recorded with the
  logged data for easy retrieval later.  This information also provides
  very useful analytics, beyond what other web analytics software provides,
  which is very helpful for guiding future development efforts.
  See the brws4j.txt file in the brws4j folder within the BH4J .zip file
  for detailed information on how to configure and use the BRWS4J.
  Note that BRWS4J requires the Enterprise Edition of BrowserHawk.

* Added detection of the Broadband property in ExtendedBrowserInfo, available
  under the Professional license.  This reports if the client is connected on
  a high-speed broadband connection.  It's different than ConnectionSpeed in
  that it imposes a maximum time to wait for detection which improves the
  testing time it takes for dial-up users compared to the ConnectionSpeed
  property.  You can change the maximum wait time via the ExtendedOptions
  BroadbandMaxWait setting, or optionally via the external broadband.max.wait
  property in the browserhawk.properties file (although the default setting
  should be sufficient for most purposes).

* Added detection of the XMLHttpRequest property in BrowserInfo, available 
  under the Standard license.  This reports if the client supports the 
  XMLHttpRequest object used for AJAX.

* Added ContainerBrowser, ContainerVersion, and ContainerFullversion
  properties in BrowserInfo and ExtendedBrowserInfo, available under the
  Standard license.  These properties give details on the container
  browser when one browser wraps another (such as Netscape 8 wrapping IE 6).

* Added OSName, OSVersion, and OSArch properties in ExtendedBrowserInfo,
  available under the Enterprise license.  These report details on the client
  operating system as derived from the JVMDetector applet.  They can be used,
  for example, to determine the precise Mac OS X version installed.

* Added DisplayXDPIActual, DisplayYDPIActual, DisplayXDPILogical, and
  DisplayYDPILogical properties to expose the browser's actual and logical
  screen resolution settings.

* Enhanced logic to continue detection even when the client is in HighSecurity
  mode (where JavaScript and auto-refreshes are disabled), and provided a new
  HighSecurity property to report when the client is in this mode.  Added
  HighSecurityMessage and HighSecurityLink features in ExtendedOptions to
  customize the behavior, or for external configuration the
  high.security.message and high.security.link properties.

* Added a convenient session caching option to save the ExtendedBrowserInfo
  object in the user's session to be immediately available across multiple
  pages.  This is enabled with the CacheToken and CacheForceRefresh features
  in ExtendedOptions.  The saved value is automatically used during later
  testing, or can be fetched using the static 
  ExtendedBrowserInfo.getFromCache() method. However this getFromCache()
  method is primarily for advanced usage.  Typically you do not need to do
  anything other than set the CacheToken to have BH4J automatically cache
  results and retrieve results from the cache.  In situations where the
  CacheToken is set and the information is already in the cache, BH4J
  automatically retrieves the cached ExtendedBrowserInfo object for you
  when you call getExtendedBrowserInfo() instead of actually performing the
  test (since it already has the answers).  You can also use the
  ExtendedBrowserInfo isFromCache() method to determine whether an answer
  came from the cache.

* Resolved an issue whereby fragment identifiers (#anchor) on a page are now
  retained during extended property detection.

* Added JavaVendor and JavaVersion support under Opera 7+.

* Added detection support for Flash 8.

* Added an options.setBrwsURLComplete() method to provide full control
  over the reporting URL used for the BrowserHawk Reports Web Service.

* Added a BrowserInfo.get(String) method for retrieving a property value by
  string name. Note that this is generally not recommended, but provided
  for advanced users should dynamic property access prove useful for a
  specific purpose.

* Resolved an issue where a request type of POST would fail if the
  application's posting form included a submit button named "submit".

* Resolved an issue where speed detection could fail with browsers using
  esoteric default character sets.
  
* Improved the user experience on Firefox when a Java test is performed and
  the Java Plugin is not present.

* Added page.message and page.title as externally configurable properties.



8.02 to 8.03:

* Resolved an issue where BrowserHawk Reports Web Service logging wasn't
  possible when client-side JavaScript was disabled.

* Resolved an issue introduced with 8.02 that caused some plugin information
  to be unavailable under Firefox.

* Resolved an issue that caused an issue under IE 4.x when testing for the
  Acrobat plugin version.


8.01 to 8.02:

* Added detection of the Adobe Acrobat 7.0 plugin installed with the
  Acrobat 7.0 basic edition.  Previous versions of BrowserHawk 8 could
  only detect the Acrobat 7.0 plugin if the Acrobat 7.0 full edition
  was installed.

* Added detection of the Real Player 10 Enterprise Edition.  Previous
  versions of BrowserHawk 8 could not detect the Enterprise version of
  Real Player 10.

8.0 to 8.01:

* Modified behavior when receiving no User-Agent header so instead of
  generating an exception it's treated like an empty string User-Agent.

* No longer tests Java Vendor or Java Version for Mac AOL browser due to
  stability issues with the JVM used by AOL.

* Fixed an issue that caused testing of Acrobat version in some cases to
  popup a mixed security warning message in the browser when testing over
  https.

* Enhanced the detection code for extended properties to call
  getOutputStream() or getWriter() only on the first pass so user code can
  call either on the second pass without contention.  This supports those
  using servlets to call getOutputStream() to write binary data.

* Removed the default "Now determining extended properties of this
  browser, please wait..." message and title on the page displayed
  during extended property checks.  It now defaults to a blank page.
  Use ExtendedOptions setPageMessage() and setPageTitle() to write your
  own message and title.

* Suppressed a useless error log message that could be generated by the
  BrowserInfo.toString() method.

7.01 to 8.0:

* Added the ability to detect blocked pop-ups! Works with third party blockers,
  toolbars, and browsers with options to block popups.

* Added support for IE 6 SP 2 and Windows XP SP 2. Use of BH versions prior to
  8.0 can result in JavaScript errors and other such issues with IE 6 SP 2 due
  to changes introduced in SP 2. 

* Added full support for the Firefox browser, including support for extended
  property checks! 

* Added the ability to detect installed fonts on the browser.  You can check
  for one or more fonts, or retrieve a list of all installed fonts.

* Improved support for Safari, including the ability to detect Java information
  under Safari 1.2 and higher, and the ability to detect the Safari versions
  greater than 1.0.

* Added detection of the MediaPlayer version number under Netscape 7.1 and
  higher. Previously MediaPlayer version was only detectable under IE.

* Added detection of MediaPlayer 10.

* Added a convenience method BrowserHawk.compareVersions() method to support
  advanced version comparisons of complex plugin version numbers.  For example,
  "5.2.1b" is known to be less than "5.10.7a".

* Added support for detection of Acrobat 6.0.1 and higher and fixed an issue
  that caused some Acrobat versions prior to 6 from being detected. Previous
  versions of BH will not detect Acrobat 6.01 or higher or detect its version
  information incorrectly.

* Added detection of the Acrobat minor version number for Acrobat 5+ under IE.
  In previous BH versions only the major Acrobat version number could be
  returned. For example, under IE BH can now return "6.01" as the Acrobat
  version number instead of just "6". 

* Improved the NETCLRVersion detection to return the highest .NET CLR version
  available if multiple versions are installed.

* Added detection of RealPlayer 10.

* Made the brws.url property also settable on ExtendedOptions as setBrwsURL().

* Added the ability to control the cookie duration for the test cookie used in
  performing the test for persistent cookies. Use the setCookieDuration()
  method on ExtendedOptions for this or set it in the browserhawk.properties
  file.

* Updated the browserhawk.properties file to include several new configurable
  parameters specific to certain browser tests, such as blocked popups,
  installed fonts, and more.

* Enhanced the image detection in the ImagesEnabled test to use the secure
  server that's configured if this test is performed from an https page,
  in order to avoid a browser warning messages about mixed security content.

* Added detection for the J2SE 1.4 plug-in for IE 6+ and Netscape. Previous
  versions of BH cannot detect this or higher versions.

* Added the ability to detect the difference between the Java Plugin 1.3 and
  earlier Vs. 1.4 and later under IE. Previous versions of BH cannot
  differentiate between versions.

* Several improvements were made to the Java vendor, Java version, and Java
  plugin detection to provide greater accuracy and granularity in results.

* Added new Enhanced Automatic Version Detection (EAVD) engine. When used in
  conjunction with Browser Definition File (BDF) version 8 and higher, this
  results in smaller and more efficient BDFs with greater accuracy in browser
  version number detection.

* Resolved an issue with detection of Director (Shockwave) under IE Windows.

* Improved the error codes returned by JavaVersion and JavaVendor.

* Clarified the documentation around JavaVersion and JavaEnabled detection.

* Several new and updated JSP and ColdFusion MX samples have been added,
  including samples demonstrating detection of blocked popups and installed
  fonts. 

* Resolved an issue with BrowserHawk Reports and European locales.

* Added the ability to set the BrowserHawk Reports Web Service URL on a
  per-request basis using setBrwsURL() on ExtendedOptions.

* The placement of the TITLE tag sent by the BrowserHawk test page used to
  perform extended property checks was corrected to come inside the HEAD section
  of the HTML.

* Fixed an issue with extended property tests when using the POST or AUTO
  requestType on a form submission page with form field values containing spaces
  (such as those from textarea fields).  This resulted in those field values
  being truncated at the first space.  Affected ActiveX, .NET, and Java.


7.0 to 7.01:

* When there are more than one error conditions on startup, throw an
  exception based on the first encountered.

* Resolved issue involving Acrobat v4 detection with IE on Windows.
  
* Resolved an issue that can cause extended property testing to repeat
  in a loop.

* Removed the potential for double encoding preserved POST parameters.

6.02 to 7.0:

* New "WAR format" packaging for easy single web application deployment.

* Added detection for Adobe Acrobat version 6

* Added support for detection of extended properties under Opera 7 and
  higher.  Previous versions of BH4J cannot return extended property
  results for Opera 7 and may cause a JavaScript error in the browser
  while attempting to do so.  This now works as expected in BH4J 7.0.

* Added support for extended property checks with the MacOS X Safari
  browser.  Previous versions of BH4J cannot return extended property
  results for Safari.

* Added BrowserHawk.getDashCacheStats() method to observe DashCache
  statistics.

* Added ExtendedOptions.addQueryStringParam() feature to preserve extra
  information during an extended property redirect.

* Changed the getTimeZoneDiff() method to return a double rather than an int,
  to account for time zones that aren't at even hour boundaries.

* Improved the getMSJVM() method to retrieve a more accurate build number
  using the JVMDetector.class applet.

* Added the getWinInstallerMinVer() method to return the minimum version of the
  Windows Installer that is installed on the client.

* Added support for ensuring detection of J2SE 1.5.

* Added native support for use in ColdFusion MX, along with the
  CF_BrowserHawk4J custom tag (browserhawk4j.cfm), and the following CFMX
  samples: bh4jtagtest.cfm, showbrow.cfm, and showextbrow.cfm.

* Improved the translate() method output.

* Eliminated the use .bds cache files.

* Resolved several small issues.

6.01 to 6.02:

* Fixed bug where TextSize translate() code could say "Not tested" instead of
  "Not detectable with this browser".

* Added a workaround for a bug in BroadVision regarding User-Agent detection.

6.0 to 6.01:

* Fixed bug where JavaScript could generate a "plugV is not defined" error.

* Fixed bug where QuickTimeVerEx could improperly report "N.a.N".

* Updated the cyScape contact number to 1-301-424-8200.

5.02 to 6.0:

NEW METHODS:

* Added getSSLEnabled() to determine if SSL is disabled or blocked.  Also
  added ExtendedOptions.setSSLCheckURL() and setSSLCheckResource() to
  customize this behavior.

* Added getSSLKeySize() to determine the browser's SSL key size support even
  outside an HTTPS connection and even when the main production server doesn't
  expose this capability.  Also added ExtendedOptions.setSSLCheckURL() and
  setSSLCheckResource() to customize this behavior.

* Added getServicePack() to determine browser service packs and Q patches.

* Added getOpenPorts() to determine which outgoing ports are open.  Also
  added ExtendedOptions.setPortsToCheck(), setPortCheckURL(), and
  setPortCheckResource() to customize this behavior.

* Added getFirewall() to determine if the browser is behind a firewall
  blocking most outgoing connections.  Also added
  ExtendedOptions.setFirewallTimeout() to customize this behavior and other
  port check behavior.

* Added getImagesEnabled() to determine if image loading is enabled.

* Added getPluginCustom() to support searching for any plug-in not otherwise
  recognized by BrowserHawk.  Also added ExtendedOptions.setPluginCustomID()
  to customize this behavior.

* Added ExtendedOptions.setSpeedCheckAdjustment() to allow integer multiples
  of the standard speed test data set to be sent for increased accuracy or
  half to be sent for faster responses.

* Added ExtendedOptions.setServerURL() to programmatically expose a capability
  that had previously existed in browserhawk.properties.

* Added getDownloadTimeSec() and getDownloadTimeDesc() to estimate the time
  required for a given download.

* Added getGecko() and getGeckoBuildDate() for Gecko-based browsers.

* Added getNETCLRInstalled() and getNETCLRVersion() for .NET enabled browsers.

* Added getProxyString() for returning the name of the proxy used by the
  browser.

* Added getCountry() for returning the country location of the client.
  (Requires the CountryHawk product be installed.)

UPDATED LOGIC:

* Updated plug-in detection for Flash, Shockwave, RealOne, and Java.

* Added support for Mozilla browsers.

* Added integration with CountryHawk.

* Added support for preserving jsessionid information in URLs.

* Fixed issue where Plugin_JavaVer might not return the highest numbered
  plug-in if multiple plug-ins were installed.

5.01 to 5.02:

* Added a getResolveIP() method to BrowserInfo, to quickly determine the
  client's hostname.

5.0a to 5.01:

* Suppressed warning when a .bds file is not saved.  It's only a warning and 
  has no effect on runtime behavior.

* Added support for %u decoding, as needed with IE browsers running in a
  Japanese locale.

5.0 to 5.0a:

* Fixed bug in ConnectionSpeed detection that had caused the speed to always
  return "0".

* Fixed bug in the reading of properties files where a classpath directory
  permission problem (SecurityException) could halt the search prematurely.

* Added BrowserHawk.getVersion() method to return the current version.

* Enhanced the extended property examples to perform better for Professional
  licensees.

4.03b to 5.0:

* Many, many new properties were added.  See
    http://www.cyscape.com/products/bhawk/new.aspx

* Cookie and speed detection was migrated into the comprehensive
  ExtendedBrowserInfo check, and the CookieInfo and SpeedInfo classes
  were deprecated.

4.03a to 4.03b:

* Improved cookie detection logic to work better with servers that have 
  their clocks wrongly set.

4.03 to 4.03a:

* Added new getCharHeightAvail() and getCharWidthAvail() attributes to report
  on screen resolution for wireless devices.

* Fixed issue where getHDML() property wasn't properly recognized.

* Incorporated a regular update of browser information in maindefs.bdd.


---------
NOTICE
---------

Includes a small portion of Jetty software licensed under the Apache License,
Version 2.0.  You may obtain a copy of the License at 
http://www.apache.org/licenses/LICENSE-2.0.
The Jetty Web Container is Copyright Mort Bay Consulting Pty Ltd
unless otherwise noted. It is licensed under the apache 2.0
license.



<end>

