com.cyscape.browserhawk
Class BrowserHawk

java.lang.Object
  extended by com.cyscape.browserhawk.BrowserHawk

public class BrowserHawk
extends java.lang.Object

Class to locate and return appropriate BrowserInfo instances. Uses the factory pattern.

Constructor Summary
BrowserHawk()
           
 
Method Summary
static int compareVersions(java.lang.String first, java.lang.String second)
          Compares two version strings.
static BrowserInfo getBrowserInfo(javax.servlet.http.HttpServletRequest req)
          Gets information on the capabilities of a browser, based on the browser's HttpServletRequest.
static BrowserInfo getBrowserInfo(java.lang.String userAgent)
          Gets information on the capabilities of a browser, based on the browser's User-Agent HTTP header.
static DashCacheStats getDashCacheStats()
          Returns a DashCacheStats instance which can view the DashCache statistics including current and peak size, hit and miss counts, last clean time and total clean count, and more.
static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, ExtendedOptions options)
          Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately.
static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, ExtendedOptions options, PLTOptions pltOptions)
          Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately.
static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, long pluginTypes)
          Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately.
static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, long pluginTypes, boolean keepReferer)
          Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately.
static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res, long pluginTypes, boolean keepReferer, java.lang.String bodyTag, java.lang.String pageTitle, java.lang.String pageMessage)
          Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately.
static java.lang.String getVersion()
          Returns the BrowserHawk version and license version.
static java.lang.String logData(BrowserInfo info, ExtendedBrowserInfo einfo)
          Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database.
static java.lang.String logData(BrowserInfo info, ExtendedBrowserInfo einfo, LogOptions logOptions, javax.servlet.http.HttpServletRequest req)
           
static java.lang.String logData(BrowserInfo info, ExtendedBrowserInfo einfo, java.lang.String propertiesToLog)
          Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database.
static java.lang.String logData(BrowserInfo info, ExtendedBrowserInfo einfo, java.lang.String propertiesToLog, java.lang.String bhud, java.lang.String bhu2, java.lang.String bhu3)
          Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database.
static java.lang.String logData(BrowserInfo info, ExtendedBrowserInfo einfo, java.lang.String propertiesToLog, java.lang.String bhud, java.lang.String bhu2, java.lang.String bhu3, java.lang.String bhu4, java.lang.String bhu5)
          Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database.
static java.lang.String pltHead(javax.servlet.http.HttpServletRequest req, PLTOptions pltOptions)
          Returns a JavaScript block (which should be inserted in the page's head section) in order to perform page load time detection.
static java.lang.String toXML(BrowserInfo info, ExtendedBrowserInfo einfo)
          Returns an XML representation of all the BrowserInfo properties and their associated values, plus all the tested extended properties and their associated values for the ExtendedBrowserInfo.
static java.lang.String toXML(BrowserInfo info, ExtendedBrowserInfo einfo, java.util.Properties props)
          Returns an XML representation of all the BrowserInfo properties and their associated values, plus all the tested extended properties and their associated values for the ExtendedBrowserInfo.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BrowserHawk

public BrowserHawk()
Method Detail

getVersion

public static java.lang.String getVersion()
Returns the BrowserHawk version and license version. For example, "5.0a Enterprise". This method is most useful for debugging and sending in problem reports.

Returns:
A String representation of the BrowserHawk version and license version.

getBrowserInfo

public static BrowserInfo getBrowserInfo(javax.servlet.http.HttpServletRequest req)
                                  throws BrowserHawkException
Gets information on the capabilities of a browser, based on the browser's HttpServletRequest. This method provides more complete and accurate information than getBrowserInfo(String userAgent).

Parameters:
req - The servlet request made by the browser
Returns:
A BrowserInfo object encapsulting browser capabilities information, or an exception on configuration or license error.
Throws:
BrowserHawkException

getBrowserInfo

public static BrowserInfo getBrowserInfo(java.lang.String userAgent)
                                  throws BrowserHawkException
Gets information on the capabilities of a browser, based on the browser's User-Agent HTTP header. This method should only be used when a request object is not available since more detail is available when a request object is present.

Parameters:
userAgent - A browser's User-Agent HTTP header
Returns:
A BrowserInfo object encapsulting browser capabilities information, or null on configuration or license error.
Throws:
BrowserHawkException

getExtendedBrowserInfo

public static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req,
                                                         javax.servlet.http.HttpServletResponse res,
                                                         long pluginTypes)
Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately. Returns ExtendedBrowserInfo.UNKNOWN if the user isn't using any of the currently supported browsers Netscape, IE, or Opera. The pluginTypes is a bitmask for which plugins should be detected, with a value such as (ExtendedBrowserInfo.PLUGIN_DIRECTOR | ExtendedBrowserInfo.PLUGIN_ACROBAT). Each plugin detected requires a little more client-side execution time. The PLUGIN_ACROBAT option also requires launching Acrobat in some situations. This call makes no attempt to save the original Referer header value; use the other forms of this method for that.

Requires BrowserHawk Professional or Enterprise Edition.

Parameters:
req - The servlet request made by the browser
res - The servlet response going to the browser
pluginTypes - Which plugins to detect, based on constants in ExtendedBrowserInfo
Returns:
An ExtendedBrowserInfo object encapsulting the browser information, or null if no information can yet be determined.

getExtendedBrowserInfo

public static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req,
                                                         javax.servlet.http.HttpServletResponse res,
                                                         long pluginTypes,
                                                         boolean keepReferer)
Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately. Returns ExtendedBrowserInfo.UNKNOWN if the user isn't using any of the currently supported browsers Netscape, IE, or Opera. The pluginTypes is a bitmask for which plugins should be detected, with a value such as (ExtendedBrowserInfo.PLUGIN_DIRECTOR | ExtendedBrowserInfo.PLUGIN_ACROBAT). Each plugin detected requires a little more client-side execution time. The PLUGIN_ACROBAT option also requires launching Acrobat in some situations. If keepReferer is true the original Referer header will be stored as the "bhref" parameter during a redirect. For control over the JavaScript page, see the seven-argument version of this method.

Requires BrowserHawk Professional or Enterprise Edition.

Parameters:
req - The servlet request made by the browser
res - The servlet response going to the browser
pluginTypes - Which plugins to detect, based on constants in ExtendedBrowserInfo
keepReferer - Whether to make the original referer available as a bhref parameter
Returns:
An ExtendedBrowserInfo object encapsulting the browser information, or null if no information can yet be determined.

getExtendedBrowserInfo

public static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req,
                                                         javax.servlet.http.HttpServletResponse res,
                                                         long pluginTypes,
                                                         boolean keepReferer,
                                                         java.lang.String bodyTag,
                                                         java.lang.String pageTitle,
                                                         java.lang.String pageMessage)
Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately. Returns ExtendedBrowserInfo.UNKNOWN if the user isn't using any of the currently supported browsers Netscape, IE, or Opera. The bodyTag is placed in the body of the JavaScript page, and could be used to set things like the background color to avoid any flash. The pageTitle is the title of the page. The pageMessage is what the user sees. A null value for these parameters indicates the defaults should be used. The pluginTypes is a bitmask for which plugins should be detected, with a value such as (ExtendedBrowserInfo.PLUGIN_DIRECTOR | ExtendedBrowserInfo.PLUGIN_ACROBAT). Each plugin detected requires a little more client-side execution time. The PLUGIN_ACROBAT option also requires launching Acrobat in some situations. If keepReferer is true the original Referer header will be stored as the "bhref" parameter during a redirect.

Requires BrowserHawk Professional or Enterprise Edition.

Parameters:
req - The servlet request made by the browser
res - The servlet response going to the browser
pluginTypes - Which plugins to detect, based on constants in ExtendedBrowserInfo
keepReferer - Whether to make the original referer available as a bhref parameter
bodyTag - HTML to put in the JavaScript test page body
pageTitle - Title of the JavaScript test page
pageMessage - Text for the user to see in the JavaScript test page
Returns:
An ExtendedBrowserInfo object encapsulting the browser information, or null if no information can yet be determined.

getExtendedBrowserInfo

public static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req,
                                                         javax.servlet.http.HttpServletResponse res,
                                                         ExtendedOptions options)
Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately. Returns ExtendedBrowserInfo.UNKNOWN if the user isn't using any of the currently supported browsers Netscape, IE, or Opera.

Requires BrowserHawk Professional or Enterprise Edition.

Parameters:
req - The servlet request made by the browser
res - The servlet response going to the browser
options - The options on which properties to examine and other settings
Returns:
An ExtendedBrowserInfo object encapsulting the browser information, or null if no information can yet be determined.

getExtendedBrowserInfo

public static ExtendedBrowserInfo getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest req,
                                                         javax.servlet.http.HttpServletResponse res,
                                                         ExtendedOptions options,
                                                         PLTOptions pltOptions)
Returns information on browser properties which are determined through interaction with the client, or returns null if properties can't yet be determined and it has to send a page to test the client, in which case the calling servlet should end the response immediately. Returns ExtendedBrowserInfo.UNKNOWN if the user isn't using any of the currently supported browsers Netscape, IE, or Opera.

Requires BrowserHawk Professional or Enterprise Edition.

Parameters:
req - The servlet request made by the browser
res - The servlet response going to the browser
options - The options on which properties to examine and other settings
pltOptions - The PLTOptions containing the preferences and options to be used for the page load time test
Returns:
An ExtendedBrowserInfo object encapsulting the browser information, or null if no information can yet be determined.

logData

public static java.lang.String logData(BrowserInfo info,
                                       ExtendedBrowserInfo einfo)
Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database. Returns the IMG tag string to include in the response. The properties logged will be those listed in browserhawk.properties.

Requires BrowserHawk Enterprise Edition.

Parameters:
info - The BrowserInfo data, required
einfo - The ExtendedBrowserInfo data, if any
Returns:
A string containing an IMG tag that should be included in the response body

logData

public static java.lang.String logData(BrowserInfo info,
                                       ExtendedBrowserInfo einfo,
                                       java.lang.String propertiesToLog)
Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database. Returns the IMG tag string to include in the response.

Requires BrowserHawk Enterprise Edition.

Parameters:
info - The BrowserInfo data, required
einfo - The ExtendedBrowserInfo data, if any
propertiesToLog - The properties to be logged; if null the default from browserhawk.properties is used
Returns:
A string containing an IMG tag that should be included in the response body

logData

public static java.lang.String logData(BrowserInfo info,
                                       ExtendedBrowserInfo einfo,
                                       java.lang.String propertiesToLog,
                                       java.lang.String bhud,
                                       java.lang.String bhu2,
                                       java.lang.String bhu3)
Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database. Returns the IMG tag string to include in the response.

Requires BrowserHawk Enterprise Edition.

Parameters:
info - The BrowserInfo data, required
einfo - The ExtendedBrowserInfo data, if any
propertiesToLog - The properties to be logged; if null the default from browserhawk.properties is used
bhud - A user-defined value to be stored as the "bhud" property; if null then no value is entered
bhu2 - A user-defined value to be stored as the "bhu2" property; if null then no value is entered
bhu3 - A user-defined value to be stored as the "bhu3" property; if null then no value is entered
Returns:
A string containing an IMG tag that should be included in the response body

logData

public static java.lang.String logData(BrowserInfo info,
                                       ExtendedBrowserInfo einfo,
                                       java.lang.String propertiesToLog,
                                       java.lang.String bhud,
                                       java.lang.String bhu2,
                                       java.lang.String bhu3,
                                       java.lang.String bhu4,
                                       java.lang.String bhu5)
Creates and returns an IMG tag that when sent to the client will cause the client to access a logging server for the purpose of logging statistics to a database. Returns the IMG tag string to include in the response.

Requires BrowserHawk Enterprise Edition.

Parameters:
info - The BrowserInfo data, required
einfo - The ExtendedBrowserInfo data, if any
propertiesToLog - The properties to be logged; if null the default from browserhawk.properties is used
bhud - A user-defined value to be stored as the "bhud" property; if null then no value is entered
bhu2 - A user-defined value to be stored as the "bhu2" property; if null then no value is entered
bhu3 - A user-defined value to be stored as the "bhu3" property; if null then no value is entered
bhu4 - A user-defined value to be stored as the "bhu4" property; if null then no value is entered
bhu5 - A user-defined value to be stored as the "bhu5" property; if null then no value is entered
Returns:
A string containing an IMG tag that should be included in the response body

logData

public static java.lang.String logData(BrowserInfo info,
                                       ExtendedBrowserInfo einfo,
                                       LogOptions logOptions,
                                       javax.servlet.http.HttpServletRequest req)

getDashCacheStats

public static DashCacheStats getDashCacheStats()
Returns a DashCacheStats instance which can view the DashCache statistics including current and peak size, hit and miss counts, last clean time and total clean count, and more.

The DashCache feature is available only in BrowserHawk Professional and Enterprise Editions.

compareVersions

public static int compareVersions(java.lang.String first,
                                  java.lang.String second)
Compares two version strings. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second. The logic tokenizes each argument string by periods and commas, then compares the individual tokens. Leading integers in each token are compared as ints. Trailing characters are compared as strings. Example: 5.1b.7 is less than 5.2a.1. 5,9,0 is less than 5,10b,7. The method also treats version numbers with "r" values such as "6.0 r15" as equivalent to "6.0.15" which it should be noted is also equivalent to "6.0.15.0". Null parameter values are not allowed.

toXML

public static java.lang.String toXML(BrowserInfo info,
                                     ExtendedBrowserInfo einfo)
Returns an XML representation of all the BrowserInfo properties and their associated values, plus all the tested extended properties and their associated values for the ExtendedBrowserInfo. The root element includes metadata about the capture including the BrowserHawk version, license level installed, edition, BDD version, and timestamp in the ISO 8601 format. See also BrowserInfo.toXML(), ExtendedBrowserInfo.toXML(), and toXML(BrowserInfo, ExtendedBrowserInfo, Properties).)

toXML

public static java.lang.String toXML(BrowserInfo info,
                                     ExtendedBrowserInfo einfo,
                                     java.util.Properties props)
Returns an XML representation of all the BrowserInfo properties and their associated values, plus all the tested extended properties and their associated values for the ExtendedBrowserInfo. The root element includes metadata about the capture including the BrowserHawk version, license level installed, edition, BDD version, and timestamp in the ISO 8601 format. By passing a Properties object you can add additional attributes on the root, for example a user's login ID or department. It's left to the caller to ensure each key is a valid XML attribute name. See also BrowserInfo.toXML(), ExtendedBrowserInfo.toXML(), and toXML(BrowserInfo, ExtendedBrowserInfo, Properties).)

pltHead

public static java.lang.String pltHead(javax.servlet.http.HttpServletRequest req,
                                       PLTOptions pltOptions)
Returns a JavaScript block (which should be inserted in the page's head section) in order to perform page load time detection.

Requires BrowserHawk Enterprise Edition.

Parameters:
req - The servlet request made by the browser
pltOptions - The PLTOptions containing the preferences and options to be used for the page load time test
Returns:
A string containing JavaScript code to be inserted in the page's head section