## com.cyscape.browserhawk
Class BrowserHawk

    java.lang.Object
      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