BrowserHawk4J Rules Documentation

This documentation provides an introduction to BrowserHawk4J "Rules", along 
with a description of the syntax and a few examples to demonstrate how 
Rules can be used.

Note: Rules are only available to users with an Enterprise license version.

Introduction
-----------------
Rules in BrowserHawk4J provide a highly efficient and easy way for you to 
extend and maintain the power of BrowserHawk4J to include your own rules 
for what browsers are acceptable or unacceptable for parts or all of your 
web site.  If you require that a browser meets certain minimum 
capabilities, for example, you can define these minimum requirements in a 
"rules" file.  Then at run-time you simply call BrowserHawk4J's applyRules() 
method to determine whether the browser is acceptable based on these 
requirements.

The real power of Rules is that they allow you to centralize your browser 
capability requirements.  This approach results in tremendous power and 
flexibility, allowing you to maintain your rules independent of your Java 
servlets and JSP.  Rules are written in an English-like predefined syntax, 
making it easy for non-technical personnel to maintain your Rules if 
need-be.  Rules are also highly efficient to execute because they are 
compiled into Java classes which are loaded dynamically at run-time.  You 
simply write the rule conditions, and our Rules Compiler generates all the 
code and classes for you!

Rules are only available to users with an Enterprise license version.
The files referred to here are in the "rules" subdirectory.

Syntax of a Rule
------------------------
IF property expr value [ [AND propertyN expr valueN] ...] THEN returnString

Summary:
Each Rule must start with the IF keyword, followed by a property name, 
expression (as defined below), and value.  You may then add one or more 
sets of comparisons by using the AND keyword and providing another property 
and value. The THEN keyword must follow the property/expr/value entry, 
followed by the string value you want returned if the Rule matches.

Details on each part of the Rule are provided below:

"property" - this must be one of the predefined method names available in 
BrowserHawk, without the "get" prefix that is part of each method.  See the 
BrowserHawk javadocs for a listing.

"expr" - this is an expression that is used to compare the property with a 
value.  Valid expressions are as follows:
  "=" or " ==" - determines whether the property is equal to a 
                 specified value
  ">" - determines whether the property is greater than a specified value
  ">=" - determines whether the property is greater than or equal to a 
         specified value
  "<" - determines whether the property is less than a specified value
  "<=" - determines whether the property is less than or equal to a 
         specified value
  "<>" or "!=" - determines whether the property is not equal to a 
                 specified value

"value" - this is the value that you are comparing the property to.  This 
value must be quoted if the property you are checking is a string based 
property, such as comparing the Browser property for "IE".  Otherwise the 
value should *not* be quoted, such as comparing Version for 3.0.  The value
*cannot* contain spaces.

"returnString" - this is the string value to be returned if the Rule 
matches.  It must be in double quotes.  It *cannot* contain spaces.

Example 1:
This example demonstrates a basic rule that checks to see if the browser 
supports Frames.  If it does, the applyRules method will return "PASS", 
otherwise it returns an empty string (""):

IF frames = true THEN "PASS"

Example 2:
This example demonstrates a basic Rule that checks to see if the browser 
supports Frames and is not Internet Explorer version 3.0.  If these 
conditions are met, the applyRules method will return "PASS", otherwise it 
returns an empty string (""):

IF frames = true AND browser <> "IE" AND version <> 3.0 THEN "PASS"

Rules must be used within the context of a Rules file, as described next.

Understanding Rules files
-------------------------------------
A Rules file is a .rls file that contains one or more Rules (as described 
above), and an optional OTHERWISE clause.  You can create as many Rules 
files as you wish.  For example, you could have one rules file used when a 
user enters a site to ensure they have a browser which supports cookies and 
frames.  Then you could have another rules file which checks their browser 
for minimum security requirements before allowing them into the shopping 
area of your site.

A Rules file can be created using any text editor.  After creating the file
you simply run the Rules Compiler (rulecomp.sh or rulecomp.bat) which parses
the Rules file and generates a corresponding .java source file.  Be sure
*not* to include the .rls extension.

Windows> rulecomp rulefile
Unix% rulecomp.sh rulefile

This file is then compiled in the second stage of the Rules Compiler process
using your Java compiler of choice, and the resulting .class file is copied
to the same directory as the .rls file.  To be found, it must be a directory
in your CLASSPATH.  The file name of the .java and .class files generated by
the Rules Compiler is taken from the name of the .rls file.  For example,
sslcheck.rls becomes sslcheck.java and sslcheck.class.  The .class files
generated by the Rules Compiler becomes the actual .class files that will be
dynamically loaded at run-time when you call the applyRules() method for that
named rules file.

The syntax for a rules file is as follows:
Rule1
[Rule2]
[RuleN]
[OTHERWISE defaultStringResult]

As can be seen above, a Rules file must contain at a minimum a single Rule, 
but can contain as many additional rules as you want.  Each rule must be 
defined using the Rules syntax as defined in the Syntax of a Rule section 
above.  The OTHERWISE clause is optional. It can be used to specify the 
value that should be returned by the rule if none of the rules specified in 
the rules file match.

Each rule must be on a line of its own.  Comment lines begin with # in the
first column.

For example, consider the following SecureBrowser rules file:

SecureBrowser.rls file:

# This is an example comment
IF ssl = false then "FAIL"
IF browser = "Netscape" AND version > 3.02 AND platform = "Win95" then "FAIL"
IF browser = "IE" AND version >= 4.0 AND platform = "WinNT" THEN "PASS"
IF browser = "IE" AND version >= 4.0 AND platform = "Win98" THEN "FAIL"
OTHERWISE "UNKNOWN"

[Note: The rules used above are fictitious and listed for demonstration 
purposes only]

In this example, the developer has listed explicit conditions for which a 
browser is either approved or rejected for use in the commerce part of 
their web site (in a real-world application the Rules listed would 
obviously be much more detailed).  The OTHERWISE clause catches anything 
not explicitly matched.  When the applyRules method is called, the returned 
result will either be "PASS", "FAIL" or "UNKNOWN".

How to call the applyRules method
--------------------------------------------------
Assuming you have created the appropriate .rls file and compiled it with the
Rules Compiler, you MUST now make sure the .class file is contained in your
server's CLASSPATH so as to be dynamically loaded as needed at run-time by
BrowserHawk4J.

The following code snippet continues with the SecureBrowser.rls file 
presented in the previous section, and demonstrates how to call the 
applyRules method and check its return value.  After creating the above 
.rls file, it would then have been compiled by the Rules Compiler to create 
SecureBrowser.class and placed in your CLASSPATH:

[servlet/JSP snippet]

  String ruleResult = browser.applyRules("SecureBrowser");
  if (ruleResult.equals("FAIL")) {
    // Send user to a page explaining that their browser does not meet the 
    // required standards
  }
  else if (ruleResult.equals("UNKNOWN")) {
    // Warn user their browser has not been tested and there may be 
    // unexpected results
  }
  else {
    // Browser is in the approved list ("PASS") was returned.  Continue as 
    // normal
  }

When this code executes, BrowserHawk4J automatically loads the
SecureBrowser.class, and then begins checking the browsers capabilities
against what is defined in the Rules file.  Once a match is made, the return
value specified by the matching Rule's THEN clause is returned.  If no Rules
in the library match, then the value specified in the OTHERWISE clause is
returned.  If there is no OTHERWISE clause then an empty string is returned.

[end]
