com.cyscape.browserhawk
Class ExtendedOptions

java.lang.Object
  com.cyscape.browserhawk.ExtendedOptions

All Implemented Interfaces:

java.lang.Cloneable

public class ExtendedOptions

extends java.lang.Object

implements java.lang.Cloneable

Class to control the behavior of BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, ExtendedOptions).

REQUEST_TYPE_AUTO

public static final int REQUEST_TYPE_AUTO

This setting instructs BrowserHawk to choose the most appropriate requestType for you, given the content in which your page is running. If your page is accessed via a GET request, it will use the REQUEST_TYPE_COOKIE. If the user has cookies disabled, however, it will sense this on-the-fly and instead use a requestType of REQUEST_TYPE_QUERY_STRING. If your page is accessed via a POST request, it uses a requestType of REQUEST_TYPE_POST. One special case is when doing a font 'all' check, where REQUEST_TYPE_POST is preferred in order to support the large amount of data that may be transferred. Using this auto-select mode is the recommended setting.

See Also:

Constant Field Values

REQUEST_TYPE_COOKIE

public static final int REQUEST_TYPE_COOKIE

This setting instructs BrowserHawk to have the test results passed from the browser back to BrowserHawk via a temporary session cookie.

If the user has session cookies disabled, or chooses not to accept the cookie (if their browser is set to prompt before accepting cookies), then BrowserHawk automatically downgrades itself on-the-fly to use REQUEST_TYPE_QUERY_STRING.

If using the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method from a script accessed via the GET method, this requestType is highly recommended and the most efficient. This approach gives you the best of both worlds - for users with cookies enabled, the test is completely silent and transparent and there is only one small token added to the query string regardless of how many properties you are checking. Yet at the same time, if the user has disabled their cookies, BrowserHawk adjusts this for you and falls back on the query string method.

Advantages / Disadvantages of this requestType:

Advantages:

• Completely transparent and silent testing 45 only one very minor change is made to the query string ("bhcp=1" is added) regardless of how many tests are performed. This assumes the user's cookies are enabled
• BrowserHawk internal processing of the results is very efficient
• Automatically falls back to REQUEST_TYPE_QUERY_STRING if the user's cookies are disabled

Disadvantages:

• You cannot use this requestType from a page POSTed to -- otherwise the posted data and request object will be lost.

See Also:

Constant Field Values

REQUEST_TYPE_QUERY_STRING

public static final int REQUEST_TYPE_QUERY_STRING

This setting instructs BrowserHawk to have the test results passed from the browser back to BrowserHawk via the query string. Any existing information in the query string is preserved.

Unlike previous versions of BrowserHawk, only the specific test results you ask for are adding to the query string. This helps to make the changes to the query string minimal. For example, if you just ask BrowserHawk to check the version of Flash installed, only one name/value pair is added to the query string.

Unless you have a specific reason why you want the results passed in the query string, we recommend that you use REQUEST_TYPE_COOKIE for a cookie-based test instead. In the event the user has cookies disabled, BrowserHawk automatically falls back to using this requestType so you will be covered either way.

Advantages / Disadvantages of this requestType

Advantages:

• You may prefer to have the results in the query string for other purposes. Please note however that the token names in the query string are subject to change with new versions of the product. Therefore it is recommended you get the results by accessing the object's property rather than reading it from the query string.

Disadvantages:

• BrowserHawk adds name/value pairs to the querystring for the properties you ask it to check. If you are only checking a few properties this change is minimal. For example, the URL shown in the browser after executing a test for screen resolution may become page.jsp?bhsw=800&bhsh=640. If you are checking several extended properties the URL can become quite long. This will not affect how your page works in any way, but some developers prefer not to have long querystrings shown in their URL.
• You cannot use this requestType from a page POSTed to 45 otherwise the posted data and request object will be lost.

See Also:

Constant Field Values

REQUEST_TYPE_POST

public static final int REQUEST_TYPE_POST

This setting instructs BrowserHawk to have the test results passed from the browser back to BrowserHawk via the POST method. Any values currently being POSTed in (from a form submission, for example) are preserved.

This method is only recommended if you need to use the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method from a page that is posted to, and you have no opportunity to execute the test in a page prior to the POST (for example if another web site or application is posting results to your page).

If it is possible to run the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method from the page displayed prior to where the post occurs, it is recommend you perform the test on a prior page. For example, perform the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method call from the page which displays the form fields, and set the results to hidden form fields. Then in your page that does the post processing, simply get the values from the hidden form field.

Note: If you are using this requestType and the user has JavaScript disabled, BrowserHawk will not be able to POST the results to the destination script. This is because JavaScript is required to perform the post. However, BrowserHawk wisely detects if this condition occurs, and passes in all posted values via the query string as a GET request if so.

Advantages / Disadvantages of this requestType

Advantages:

• All of the request data, including parameter data, is preserved. This makes it safe to use the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) from scripts which perform POST processing.
• Since the results of the test are POSTed in, BrowserHawk does not add to or modify the querystring in any way. This means that your original URL for the page remains.

Disadvantages:

• If the page containing the call to BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) is accessed via a POST (such as the target of a form submission), the user will receive a message from the browser saying that the page has expired if they press their back button.
• If the page containing the call to BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) is accessed via a GET instead of a POST, the user will bounce the user right back to the current page. This effectively renders the back button useless. You can however use the setBackDelay(int) property to add enough of a delay to allow users to press the back button a second time to break out of the loop.

See Also:

Constant Field Values

ExtendedOptions

public ExtendedOptions()

Constructs an instance of the ExtendedOptions class with the default properties.

ExtendedOptions

public ExtendedOptions(long props)

Deprecated. Due to 64-bit limitations please use the String-based property names instead

Constructs an instance of the ExtendedOptions class with a shortcut to set the specified properties. See setProperties(long) for details.

ExtendedOptions

public ExtendedOptions(java.lang.String props)
                throws java.lang.IllegalArgumentException

Constructs an instance of the ExtendedOptions class with a shortcut to set the specified properties, taking a comma-separated list. See setProperties(String) for a list of keywords. Throws an IllegalArgumentException if any name in the list is illegal.

getBodyTag

public java.lang.String getBodyTag()

Returns the congifured body tag

getPageTitle

public java.lang.String getPageTitle()

Returns the configured page title

getPageMessage

public java.lang.String getPageMessage()

Returns the configured page message

getTimeout

public int getTimeout()

Returns the configured timeout

getBackDelay

public int getBackDelay()

Returns the configured back delay

getJVMCodeBase

public java.lang.String getJVMCodeBase()

Returns the configured Java CODEBASE

getCookieDomain

public java.lang.String getCookieDomain()

Returns the configured cookie domain

getRequestType

public int getRequestType()

Returns the configured request type

getPortsToCheck

public java.lang.String getPortsToCheck()

Returns the ports to check for being open

getFirewallTimeout

public long getFirewallTimeout()

Returns the firewall timeout, in millis

getPluginCustomID

public java.lang.String getPluginCustomID()

Returns the custom plugin ID search string

getSSLCheckURL

public java.lang.String getSSLCheckURL()

Returns the URL for running an SSL check

getPortCheckURL

public java.lang.String getPortCheckURL()

Returns the URL for running the open port check

getSSLCheckResource

public java.lang.String getSSLCheckResource()

Returns the resource for running an SSL check

getPortCheckResource

public java.lang.String getPortCheckResource()

Returns the resource for running the open port check

getSpeedCheckAdjustment

public long getSpeedCheckAdjustment()

Returns the multiplier for speed check adjustments, where "2" means to send double the normal data size, "1" means to send the normal data size (recommended), and "0" is a special case meaning to send just half.

getServerURL

public java.lang.String getServerURL()

Returns the currently set server URL, or null if none.

getServerURLComplete

public java.lang.String getServerURLComplete()

Returns the currently set full server URL, or null if none.

getPopupFileName

public java.lang.String getPopupFileName()

Returns the currently set popup file name, or empty string by default which indicates the current URI should be used.

getPopupWindowName

public java.lang.String getPopupWindowName()

Returns the currently assigned popup window name, or the empty string by default.

getPopupWindowFeatures

public java.lang.String getPopupWindowFeatures()

Returns the currently assigned window features string. By default, "width=1,height=1,location=no,toolbar=no,status=no,menubar=no,scrollbars=no,resizable=no,top=3000,left=3000".

getPopupTimeout

public int getPopupTimeout()

Returns the currently assigned popup timeout, indicating how long to wait for a popup window before determining it was blocked. The default is 2000 indicating two seconds.

getFontsToCheck

public java.lang.String getFontsToCheck()

Returns the fonts to check

setProperties

public void setProperties(long props)

Deprecated. Due to 64-bit limitations please use the String-based property names instead

This method is used to tell BrowserHawk which tests you want it to execute when you call the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method, using the constant long values. Since this method can detect dozens of advanced properties, it is important to use this feature so that you can select only the tests you are interested in. For example, if you wish to detect the user's screen size, connection speed, and installed flash version, you pass the following: setProperties(ExtendedBrowserInfo.WIDTH | ExtendedBrowserInfo.HEIGHT | ExtendedBrowserInfo.CONNECTIONSPEED | ExtendedBrowserInfo.PLUGINFLASHVEREX);

The possible constant values are found in ExtendedBrowserInfo.

setProperties

public void setProperties(java.lang.String props)
                   throws java.lang.IllegalArgumentException

This method is used to tell BrowserHawk which tests you want it to execute when you call the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method, using String mneumonics. Since this method can detect dozens of advanced properties, it is important to use this feature so that you can select only the tests you are interested in. For example, if you wish to detect the user's screen size, connection speed, and installed flash version, you pass the following: setProperties("screensize, connectionspeed, pluginflashverex");

Possible keywords are: plugin_citrix, width, plugin_svgviewer, javaversion, fontsmoothing, activexenabled, msxml, plugin_mediaplayerverex, heightavail, netmeetingbuild, plugin_director, imagesenabled, textsize, browserdatetimems, connectiontype, cookie_perm, connectionspeed, plugin_flash, vbscriptbuild, plugin_crystalreports, plugin_acrobatverex, popupsblocked, plugin_flashverex, referrer, javaenabled, plugin_authorware, plugin_ipixviewer, plugin_directorverex, plugin_mapguide, vbscriptenabled, firewall, plugin_viewpoint, plugin_mediaplayer, javavendor, plugin_quicktime, plugin_realplayer, colordepth, plugin_custom, cookie_both, languser, height, plugin_realplayerbuild, javascriptbuild, fontsinstalled, plugin_acrobat, sslkeysize, widthavail, timezonediff, langsystem, sslenabled, servicepack, browserbuild, cookie_sess, plugin_javaver, openports, msjvmbuild, plugin_quicktimeverex, browserdatetime, javascriptenabled, highsecurity, cookiesenabled, browsersize, screensize, referer, all, plugin_default, plugin_all, plugin_netmeetingbuild, osname, osversion, osarch, containerbrowser, containerversion, containerfullversion, displayxdpiactual, displayydpiactual, displayxdpilogical, displayydpilogical, persistentcookies, sessioncookies, broadband, and plugin_flip4mac.

Throws:

java.lang.IllegalArgumentException

setBodyTag

public void setBodyTag(java.lang.String tag)

A body tag is used to tell BrowserHawk to add additional HTML to the tag which it sends as part of the test page it loads to detect the special properties. The most popular use of this parameter is to specify the BGCOLOR tag so that the test page has the same background color as the rest of your site. The default is "".

setPageTitle

public void setPageTitle(java.lang.String title)

A page title is used to tell BrowserHawk what text to insert in between the <TITLE> tags used by the test page it loads to detect the special properties. The default is "".

setPageMessage

public void setPageMessage(java.lang.String message)

A page message is used to display a message in the user's browser while the extended properties are detected. This is helpful for letting the user know to please wait while the test is performed. In many cases the test is performed so quickly that the message may only appear for a fraction of a second. However if you are testing a lot of properties or time intensive properties (such as connection speed 45 see the last section of this topic for more information) there could be a delay of several seconds, depending on their computer. You can also pass HTML in this parameter if you wish to display a temporary page or more advanced formatting. The default is the empty string. You may want to use "Now determining extended properties of this browser, please wait...".

setTimeout

public void setTimeout(int timeout)

This property is used to set how many seconds BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) should wait before the test times out due to JavaScript being disabled. This property is only needed for IE Mac browsers. In this case BrowserHawk uses a default of 5 seconds for IE Mac if you do not perform the speed detection, and 15 seconds if you do perform speed detection. For all other browsers, BrowserHawk users a value of 0 so that disabled JavaScript is detected instantly (this is not possible under IE/Mac, hence the purpose of this property is to give you control, should you need it, for IE/Mac over the cyScape chosen defaults). Remember BH automatically uses 0 for all browsers except IE Mac. However if you manually set this property BH will use that for all browsers. Therefore if you want to control the setting just for a particular browser type (such as IE/Mac) you should test to see if it is that browser prior to setting this property.

Why is all this important? On IE Mac the only way for BrowserHawk to detect whether JavaScript is disabled is based on how much time has elapsed since the test started. If it goes too long without the test finishing, BrowserHawk must assume its because JavaScript is disabled. The problem, however, that depending on the amount of testing you are performing, its difficult for BrowserHawk to know where to draw the line between a test that's taking a long time to execute, and a test that is not executing at all because JavaScript is disabled. In most cases you should find cyScape's default settings appropriate. If you receive reports from IE Mac users stating that their JavaScript as being detected as disabled when indeed it is enabled, then you should use this property to increase the timeout period.

Tip: In just about all circumstances the cyScape default settings should be sufficient. We only recommend you change this property if Mac IE users report incorrect JavaScript settings as mentioned above due to extensive testing you may be performing.

setBackDelay

public void setBackDelay(int delay)

This property instructs BrowserHawk to wait the number of milliseconds as specified by this property value after the page loads before the test functions should begin. In rare situations you may find it desirable to add this delay, so this property is provided for maximum flexibility and convenience for the developer. The default and recommended value of this property is 0. If you change it you must set it prior to calling getExtendedBrowserInfo().

setJVMCodeBase

public void setJVMCodeBase(java.lang.String codebase)

This property is used to specify the virtual directory that contains the cyScape supplied JVMDetector.class file used when testing the JavaVersion, JavaVendor, OSName, OSVersion, or OSArch properties. By default BrowserHawk assumes that this .class file resides in the same web directory as the script you are checking the JavaVersion or JavaVendor property from. Note: The location pointed to by the JVMCodeBase directory must be a relative web directory that is accessible to users through their web browser. For example, "./sharedfiles" or "/mysite/jars" and not "c:\inetpub\wwwroot\jars", etc.

setCookieDomain

public void setCookieDomain(java.lang.String domain)

This property is used to specify the domain of the cookies used by BrowserHawk. A cookie domain is the server or servers to which the cookie is sent, such as ".cyscape.com" for cyScape. Setting this property can be useful in a load balanced environment.

setRequestType

public void setRequestType(int type)

BrowserHawk communicates directly with the browser in order to collect the test results from the BrowserHawk.getExtendedBrowserInfo(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, long) method. You can control the way in which this communication is performed by setting the requestType to either REQUEST_TYPE_AUTO, REQUEST_TYPE_COOKIE, REQUEST_TYPE_QUERY_STRING, or REQUEST_TYPE_POST. If no value is specified, a default of 0 is used.

setTrueRequestType

public void setTrueRequestType(int type)

addProperty

public void addProperty(long prop)

Deprecated. Due to 64-bit limitations please use the String-based property names instead

Adds the given property to the current property list. See setProperties(long) for details.

addProperty

public void addProperty(java.lang.String prop)

Adds the given property to the current property list. See setProperties(String) for details. Only one property is allowed at a time. Use addProperties(java.lang.String) for multiple.

addProperties

public void addProperties(java.lang.String props)

Adds the given properties to the current property list. Similar to setProperties(String) except this is additive to the pre-existing state.

removeProperty

public void removeProperty(long prop)

Deprecated. Due to 64-bit limitations please use the String-based property names instead

Removes the given property from the current property list.

removeProperty

public void removeProperty(java.lang.String prop)

Removes the given property from the current property list. Only one property is allowed at a time. Use removeProperties(java.lang.String) for multiple.

removeProperties

public void removeProperties(java.lang.String props)

Removes the given properties from the current property list. Multiple properties are allowed.

setPortsToCheck

public void setPortsToCheck(java.lang.String ports)

Sets the ports to check for being open, as a comma-delimited list. Because the open port check will fail if the port check test server is down, it's recommended to always check for port 80 (or whatever port your service is running on) to confirm that at least the port for your service appears open and thus any closed ports must be truly closed.

setFirewallTimeout

public void setFirewallTimeout(long timeout)

Sets the time, in milliseconds, on which to wait for requests to go through the firewall during a firewall test. The default is set in browserhawk.properties to be 3000.

setPluginCustomID

public void setPluginCustomID(java.lang.String id)

Sets the custom plugin to test. The setting holds data in the format "xxxx,yyyy" where the "," must be present. "xxxx" represents the ActiveX Class ID, and "yyyy" represents the keyword for the plugin that we'll search the plugins array for. An example string is: "ShockwaveFlash.ShockwaveFlash.6,Flash". BrowserHawk then searches for the custom plugin and returns the value in the getPluginCustom() method. If there's no keyword for the plugins array, just end the string with a comma. If there's no comma, a BrowserHawkException will be thrown.

setSSLCheckURL

public void setSSLCheckURL(java.lang.String url)

Sets the URL of the server-side component to aid in the SSL check. The default is "https://schk.cyscape.com". This should be changed in production because the schk.cyscape.com server is not guaranteed to always be running. For instructions on setting up your own SSL check URL, see the documentation accompanying this library.

setPortCheckURL

public void setPortCheckURL(java.lang.String url)

Sets the URL of the server-side component to aid in the OpenPorts and ImagesEnabled checks. The default is "http://pchk.cyscape.com". This should be changed in production because the pchk.cyscape.com server is not guaranteed to always be running. Do not specify a port number in the URL. For more instructions on setting up your own port check URL, see the documentation accompanying this library.

setSSLCheckResource

public void setSSLCheckResource(java.lang.String resource)

Sets the server-side resource name that will be used to aid in the SSL check. The default is "/sslcheck.asp". You might want to use "/sslcheck.jsp" instead if you have a JSP installed. For instructions on setting up your own SSL check URL, see the documentation accompanying this library.

setPortCheckResource

public void setPortCheckResource(java.lang.String resource)

Sets the server-side resource name that will aid in the OpenPorts and ImagesEnabled checks. The default is "/bhawkp1.gif". This is good enough for most uses. Just make sure you have the file available on your "port check" and "ssl check" (if using SSL) servers.

setSpeedCheckAdjustment

public void setSpeedCheckAdjustment(long adj)

Sets a multiplier for the speed test so that fast connections can be more accurately timed. For example, "2" means to send double the data. The default is "1" which works fairly well for modem and DSL connections. Use a value like "10" to test cable or LAN speeds, if you know your users are primarily on fast connections or if getConnectionSpeed() returns 0 indicating the speed was too fast to test with the given multiple.

setServerURL

public void setServerURL(java.lang.String url)

Sets a server base URL to use on self-redirects. This is the base URL to use on self-redirects which occur during ExtendedBrowserInfo detection. BrowserHawk by default tries to determine this automatically based on HttpUtils.getRequestURL(req) and this works for almost all sites. However, some sites do load balancing in such a way that the host or port the server reports isn't the host or port which should be used. This causes clients to redirect to the wrong server. If you see this behavior, set this variable to your own URL base to override the automatic host/port detection. Include the protocol, host, and port, but nothing more. BrowserHawk will detect the URI path still. This can also be set system-wide using the server.url property in browserhawk.properties. The related method setServerURLComplete(java.lang.String) provides the ability to set a full URL including the path to override the automatic URI path detection also.

setServerURLComplete

public void setServerURLComplete(java.lang.String url)

Sets the full server URL to use on the extended property redirection. This method is similar to setServerURL(java.lang.String) except this method accepts a full URI for the redirect including the path. Use this method when a complex nested forward or internal server redirect causes BrowserHawk to auto-detect the wrong redirect path. This property can only be set dynamically.

setPopupFileName

public void setPopupFileName(java.lang.String filename)

Allows the use of a separate popup file for popup testing. By default no external file is necessary but by providing one a production popup window can be used as part of the test. The popup file must include the right JavaScript to enable the popup detection:

 <script>
 <!--
 function bhcheck() { }
 // -->
 </script>
 

If setting this property, you should also look at setting the window name and features to control its name and placement. This file name is used as the first argument to the JavaScript window.open() call with ?bhspc=1 appended to indicate it's a popup test.

setPopupWindowName

public void setPopupWindowName(java.lang.String windowName)

Allows the assignment of a specific name for the popup window. This can be helpful when specifying your own production popup file for popup testing via setPopupFileName(java.lang.String). This value is passed directly as the second argument to the JavaScript window.open() call.

setPopupWindowFeatures

public void setPopupWindowFeatures(java.lang.String features)

Allows the assignment of specific features to the popup window being tested. By default, "width=1,height=1,location=no,toolbar=no,status=no,menubar=no,scrollbars=no,resizable=no,top=3000,left=3000". This value is passed directly as the third argument to the JavaScript window.open() call.

setPopupTimeout

public void setPopupTimeout(int millis)

Sets the timehow for how long (in milliseconds) to wait before concluding the popup window is not reachable because popups are blocked. Since a popup window can take a second or two to load, it's wise to wait at least that amount before concluding popups are blocked. The default is 2000ms which equals 2 seconds. Longer waits are useful on slower connections to increase reliability but cause longer waits before popup blocks can be detected. Successful popups are detected immediately. Legal values are 0 to 120000 (0 to 2 minutes).

setFontsToCheck

public void setFontsToCheck(java.lang.String fonts)

Sets the fonts to check for installation on the client, as a comma-delimited list. For example: "arial,helvetica,courier". These fonts will be tested on the browser. Fonts from this list that are installed will then be returned via the ExtendedBrowserInfo.getFontsInstalled() method. You can then also use the ExtendedBrowserInfo.getFontInstalled(java.lang.String) method to test whether a particular font is installed. To obtain a list of all fonts installed, pass in "ALL" for this property.

getCookieDuration

public int getCookieDuration()

Returns the current value of the cookie duration property.

setCookieDuration

public void setCookieDuration(int days)
                       throws java.lang.IllegalArgumentException

Sets the max age (in days) for the test cookie used to test permanant cookies. The default value is 2 days. Legal values are between 1 and 1825 (365*5) inclusive. It's best to use as short a time as possible for expiration. The downside to too short a value is that if the visitor's clock is off significantly it can cause problems. For example if you use a value of 2 days and the visitor's clock is set accidentially 3 days ahead, the cookie will expire immediately and they will be see as having disabled persistent cookies even if they are enabled. Don't change this property unless you've experienced problems.

Throws:

java.lang.IllegalArgumentException

getBrwsURL

public java.lang.String getBrwsURL()

Returns the current BrowserHawk Reports Web Service URL.

getBrwsURLComplete

public java.lang.String getBrwsURLComplete()

Returns the current BrowserHawk Reports Web Service Complete URL.

setBrwsURL

public void setBrwsURL(java.lang.String url)

Specifies the URL where the BrowserHawk Reports Web Service resides. Normally this is set in the browserhawk.properties file as brws.url, but this property allows it to be set dynamically so it could for example vary depending on the request. The URL pointed to should be a server with BRWS4J installed. Relative URLs are allowed. The related method setBrwsURLComplete(java.lang.String) provides the ability to set a full URL including the scheme (http or https) to override the automatic scheme detection.

setBrwsURLComplete

public void setBrwsURLComplete(java.lang.String url)

Sets the full server URL where the BrowserHawk Reports Web Service resides. This method is similar to setBrwsURL(java.lang.String) except this method accepts a full URL for the service including the scheme (http or https). Use this method when you don't want automatic http/https alteration. This property can only be set dynamically.

setHighSecurityMessage

public void setHighSecurityMessage(java.lang.String msg)

This setting is for power-users only. This specifies an override for the message written to the browser in the extremely rare event the browser is in "high security" mode where automatic redirects back to the server won't execute. This message should instruct the user to click the message text in order to continue the detection. The link is specially crafted to indicate the high security mode is in effect, but can separately be overridden with setHighSecurityLink(String). The default high security message text is simply, "Please click here to continue." If you override this text you have the option to include HTML tags in your message. You don't have to include an HTML link, but if you do, you should call setHighSecurityLink(String) and pass a null value so your high security message won't be made into a link.

setHighSecurityLink

public void setHighSecurityLink(java.lang.String link)

This setting is for power-users only. This specifies an override for the link location used in the extremely rare event the browser is in "high security" mode and the setHighSecurityMessage(String) text must be written. The default high security link is dynamically calculated to redirect back to the server using a special "bhjs=-1" argument to indicate the high security state. Using this method you can instead point the user to a static page explaining they aren't able to continue with the site. Assigning a null or empty string value means to not make the high security message into a link. Note that if you provide your own link to a page running BrowserHawk, the link should include bhjs=-1 to indicate to BrowserHawk that the test was completed.

setCacheToken

public void setCacheToken(java.lang.String token)

Indicates that the ExtendedBrowserInfo result should be cached for this user under the token specified. For example, you might assign a token "flash" for a flash test, and this will save the ExtendedBrowserInfo to the user's session under the name "flash". A later request with the "flash" token will pull the value from the session rather than send any JavaScript detection code to the client. By default the value is null indicating there's no caching. You may want to use different tokens for different tests. For example, a quick "flash" test could be performed on every page (pulled from cache after the first detection) while a slower "java" test could be performed only on the few pages that need it (again doing the first detection only when necessary).

setCacheForceRefresh

public void setCacheForceRefresh(boolean forceRefresh)

Used in conjunction with setCacheToken(String), setting this value to true indicates that even if an existing value is found cached under the given token, it should be refreshed by performing another test. This is useful if you believe the client may have changed in the time since the last cached test (such as during testing).

setBroadbandMaxWait

public void setBroadbandMaxWait(int wait)

Used in the broadband test as the amount of time to wait before determining that the 50k of data should have loaded in order for the connection to be considered broadband. Value is given in milliseconds. Legal values are between 500ms and 300000ms (5 minutes). The default is 1500ms.

Parameters:

wait -

getBroadbandMaxWait

public int getBroadbandMaxWait()

Returns the currently assigned broadband wait period, indicating the amount of time to wait before determining that the 50k of data should have loaded in order for the connection to be considered broadband. Value is in milliseconds. Legal values are between 500ms and 300000ms (5 minutes). The default is 1500ms.

setBroadbandImageURL

public void setBroadbandImageURL(java.lang.String url)

Provides a location override for where to fetch the broadband image data. By default the data comes from a request back to the original page with a special "?bhspc=bb50" parameter which indicates for BrowserHawk to serve the bhawk_bb.dat file found in the server's classpath. This property provides an alternate location, useful for example if having problems serving an image through the test page or when that's not desirable. The value may be either a fully qualified URL (starting with http:// or https://) or a relative path.

getBroadbandImageURL

public java.lang.String getBroadbandImageURL()

Returns the currently set broadband image URL.

addQueryStringParam

public void addQueryStringParam(java.lang.String name,
                                java.lang.String value)

Adds a parameter with the given name and value to the query string of the URL used during the extended detection redirect. This method isn't generally necessary because BrowserHawk preserves parameters during its redirect, but this method can be useful if the original request had some non-parameter information, perhaps a header, that should be preserved. Note that BrowserHawk adds the specified parameter name and value even if a parameter with the same name already exists with another value. If you don't want the parameter to have two values (legal in HTTP and sometimes desirable), make sure you only call this method if the parameter isn't already in the query string.

getSuppressOriginalQueryString

public boolean getSuppressOriginalQueryString()

Returns the present value of the suppress original query string flag.

setSuppressOriginalQueryString

public void setSuppressOriginalQueryString(boolean suppress)

BrowserHawk by default attempts to preserve the original query string during the extended detection redirect. In some rare situations this may not be desirable, such as when using special server-side URL processing rules. This property lets you suppress the query string preservation. You can then if you desire fully control the query string handling using addQueryStringParam(String, String) or setServerURLComplete(String).

clone

public java.lang.Object clone()

toString

public java.lang.String toString()