public class NbPacHelperMethods extends PacHelperMethods
This implementation aims to be as complete and compatible as possible. It implements both the original specification from Netscape, plus the additions from Microsoft.
Modifier and Type | Field and Description |
---|---|
static int |
DNS_TIMEOUT_MS
Timeout (milliseconds) used for name service lookups.
|
Constructor and Description |
---|
NbPacHelperMethods() |
Modifier and Type | Method and Description |
---|---|
void |
alert(String message)
Writes something to log or elsewhere.
|
boolean |
dateRange(Object... args)
Tests if current date is within a date range.
|
boolean |
dnsDomainIs(String host,
String domain)
Returns true if the domain of hostname matches.
|
int |
dnsDomainLevels(String host)
Returns the number of DNS domain levels (number of dots)
in the hostname.
|
String |
dnsResolve(String host)
Resolves the given DNS hostname into an IPv4 address,
and returns it in the dot separated format as a string.
|
String |
dnsResolveEx(String host)
Resolves the given host name into its address or addresses.
|
String |
getClientVersion()
Gets the version of the PAC script processing engine.
|
boolean |
isInNet(String host,
String pattern,
String mask)
True if the IP address of the host matches the specified IP address
pattern.
|
boolean |
isInNetEx(String ipAddress,
String ipPrefix)
True if the IP address of the host matches the specified IP address
pattern.
|
boolean |
isPlainHostName(String host)
True if there is no domain name in the hostname (no dots).
|
boolean |
isResolvable(String host)
Tries to resolve the hostname.
|
boolean |
isResolvableEx(String host)
Tries to resolve the hostname.
|
boolean |
localHostOrDomainIs(String host,
String hostdom)
Is true if the hostname matches exactly the specified hostname, or if
there is no domain name part in the hostname, but the unqualified
hostname matches.
|
String |
myIpAddress()
Returns the IPv4 address of the host that the application is running on,
as a string in the dot-separated integer format.
|
String |
myIpAddressEx()
Returns the IP addresses the local host is known by.
|
boolean |
shExpMatch(String str,
String shexp)
Returns true if the string matches the specified shell expression.
|
String |
sortIpAddressList(String ipAddressList)
Sorts a list of IP addresses in ascending order.
|
boolean |
timeRange(Object... args)
Tests if current time is within a time range.
|
boolean |
weekdayRange(Object... args)
Tests if current day is within a day-of-week range.
|
public static final int DNS_TIMEOUT_MS
public boolean isPlainHostName(String host)
PacHelperMethodsNetscape
Examples:
isPlainHostName("www") is true. isPlainHostName("www.netscape.com") is false.
host
- host namepublic boolean dnsDomainIs(String host, String domain)
PacHelperMethodsNetscape
Examples:
dnsDomainIs("www.netscape.com", ".netscape.com") is true. dnsDomainIs("www", ".netscape.com") is false. dnsDomainIs("www.mcom.com", ".netscape.com") is false.
host
- the host name from the URL.domain
- the domain name to test the host name against.public boolean localHostOrDomainIs(String host, String hostdom)
PacHelperMethodsNetscape
Examples of usage from JavaScript:
localHostOrDomainIs("www.netscape.com", "www.netscape.com") is true (exact match). localHostOrDomainIs("www", "www.netscape.com") is true (hostname match, domain not specified). localHostOrDomainIs("www.mcom.com", "www.netscape.com") is false (domain name mismatch). localHostOrDomainIs("home.netscape.com", "www.netscape.com") is false (hostname mismatch).
host
- the hostname from the URL.hostdom
- fully qualified hostname to match against.public boolean isResolvable(String host)
PacHelperMethodsNetscape
true
if the argument can be
resolved into an IPv4 address.
Examples of usage from JavaScript:
isResolvable("www.netscape.com") is true (unless DNS fails to resolve it due to a firewall or some other reason). isResolvable("bogus.domain.foobar") is false.
public String dnsResolve(String host)
PacHelperMethodsNetscape
Example of usage from JavaScript:
dnsResolve("home.netscape.com") returns the string "198.95.249.79".
public String myIpAddress()
PacHelperMethodsNetscape
Example of usage from JavaScript:
myIpAddress() would return the string "198.95.249.79" if you were running the the application on that host.
public boolean isInNet(String host, String pattern, String mask)
PacHelperMethodsNetscape
Examples of usage from JavaScript:
isInNet(host, "198.95.249.79", "255.255.255.255") is true if the IP address of host matches exactly 198.95.249.79. isInNet(host, "198.95.0.0", "255.255.0.0") is true if the IP address of the host matches 198.95.*.*.
host
- a DNS hostname or IPv4 address. If a hostname is passed, it
will be resolved into an IP address by this function.pattern
- an IPv4 address pattern in the dot-separated format.mask
- mask for the IP address pattern informing which parts of the
IP address should be matched against. 0 means ignore, 255 means match.public int dnsDomainLevels(String host)
PacHelperMethodsNetscape
Examples of usage from JavaScript:
dnsDomainLevels("www") returns 0. dnsDomainLevels("www.netscape.com") returns 2.
host
- hostnamepublic boolean shExpMatch(String str, String shexp)
PacHelperMethodsNetscape
Examples of usage from JavaScript:
shExpMatch("http://home.netscape.com/people/ari/index.html", "*/ari/*") is true. shExpMatch("http://home.netscape.com/people/montulli/index.html", "*/ari/*") is false.
shexp
- shell expressionpublic boolean weekdayRange(Object... args)
PacHelperMethodsNetscape
There are several forms of this method from JavaScript:
weekdayRange(wd1) weekdayRange(wd1, gmt) weekdayRange(wd1, wd2) weekdayRange(wd1, wd2, gmt)Parameters:
wd1
and wd2
are weekday specifications. gmt
is either the string "GMT", which makes time comparison
occur in GMT timezone; or if not present, times are taken to
be in the local timezone. If this parameter exists it
must always be the last parameter.
If only wd1
is present, the function yields a true value on the
weekday that the parameter represents. If both wd1
and
wd2
are specified, the condition is true if the current weekday
is in between those two weekdays. Bounds are inclusive.
The weekday abbreviations used in wd1
and wd2
must be
one of the following:
MON TUE WED THU FRI SAT SUN
Examples of usage from JavaScript:
weekdayRange("MON", "FRI") Returns true Monday through Friday (local time zone). weekdayRange("MON", "FRI", "GMT") Returns true Monday through Friday, in Greenwich Mean Time. weekdayRange("SAT") Returns true on Saturdays, local time. weekdayRange("SAT", "GMT") Returns true on Saturdays, in Greenwich Mean Time. weekdayRange("FRI", "MON") Returns true Friday through Monday (the order is important) weekdayRange("WED", "TUE") Returns true always, all 7 days a week (although an alien way of specifying it)
args
- up to max 3 argumentsPacUtilsDateTime.WEEKDAY_NAMES
public boolean dateRange(Object... args)
PacHelperMethodsNetscape
There are several forms of this method from JavaScript:
dateRange(day) dateRange(day1, day2) dateRange(mon) dateRange(month1, month2) dateRange(year) dateRange(year1, year2) dateRange(day1, month1, day2, month2) dateRange(month1, year1, month2, year2) dateRange(day1, month1, year1, day2, month2, year2) dateRange(day1, month1, year1, day2, month2, year2, gmt)Even if not shown above, the
gmt
parameter can always be
added as an (optional) last parameter.
day
is the day of month between 1 and 31 (as an integer).
month
is one of the month strings: JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC
year
is the full year number with 4 digits, for example 1995. (as an integer)
gmt
is either the string "GMT", which makes time comparison
occur in GMT timezone; or if not present, times are taken to
be in the local timezone. If this parameter exists it
must always be the last parameter.
Examples of usage from JavaScript:
dateRange(1) true on the first day of each month, local timezone. dateRange(1, "GMT") true on the first day of each month, GMT timezone. dateRange(1, 15) true on the first half of each month. dateRange(24, "DEC") true on 24th of December each year. dateRange(24, "DEC", 1995) true on 24th of December, 1995. dateRange("JAN", "MAR") true on the first quarter of the year. dateRange(1, "JUN", 15, "AUG") true from June 1st until August 15th, each year (including June 1st and August 15th). dateRange(1, "JUN", 15, 1995, "AUG", 1995) true from June 1st, 1995, until August 15th, same year. dateRange("OCT", 1995, "MAR", 1996) true from October 1995 until March 1996 (including the entire month of October 1995 and March 1996). dateRange(1995) true during the entire year 1995. dateRange(1995, 1997) true from beginning of year 1995 until the end of year 1997.
PacUtilsDateTime.MONTH_NAMES
public boolean timeRange(Object... args)
PacHelperMethodsNetscape
There are several forms of this method from JavaScript:
timeRange(hour) timeRange(hour1, hour2) timeRange(hour1, min1, hour2, min2) timeRange(hour1, min1, sec1, hour2, min2, sec2) timeRange(hour1, min1, sec1, hour2, min2, sec2, gmt)Even if not shown above, the
gmt
parameter can always be
added as an (optional) last parameter.
hour
is the hour from 0 to 23. (0 is midnight, 23 is 11 pm.)
min
minutes from 0 to 59.
sec
seconds from 0 to 59.
gmt
is either the string "GMT", which makes time comparison
occur in GMT timezone; or if not present, times are taken to
be in the local timezone. If this parameter exists it
must always be the last parameter.
Examples of usage from JavaScript:
timeRange(12, 13) This statement is true from noon to 1:00 p.m. timeRange(12, "GMT") This statement is true noon to 12:59 p.m. GMT. timeRange(9, 17) This statement is true from 9:00 a.m. to 5:00 p.m. timeRange(0, 0, 0, 0, 0, 30) true between midnight and 30 seconds past midnight.
args
- anywhere between 1 and 7 argumentspublic boolean isResolvableEx(String host)
PacHelperMethodsMicrosoft
isResolvable()
, this function supports
both IPv4 and IPv6 addresses, meaning it should return true
if the
input can be resolved to any type of IP address.
Examples of usage from JavaScript:
isResolvable("www.netscape.com") is true (unless DNS fails to resolve it due to a firewall or some other reason). isResolvable("bogus.domain.foobar") is false.
public String dnsResolveEx(String host)
PacHelperMethodsMicrosoft
Example of usage from JavaScript:
dnsResolveEx("testmachine1"); returns the string "2001:4898:28:7:982d:a3b3:97ad:7dd0;192.168.1.99"
public String myIpAddressEx()
PacHelperMethodsMicrosoft
Example of usage from JavaScript:
myIpAddressEx() would return the string "2001:4898:28:7:982d:a3b3:97ad:7dd0;198.95.249.79" if you were running the application on that host.
public String sortIpAddressList(String ipAddressList)
PacHelperMethodsMicrosoft
Example of usage from JavaScript:
sortIpAddressList("10.2.3.9;2001:4898:28:3:201:2ff:feea:fc14;::1;127.0.0.1;::9"); returns "::1;::9;2001:4898:28:3:201:2ff:feea:fc14;10.2.3.9;127.0.0.1";
NOTE: Microsoft Internet Explorer 11 (tested on 11.608.15063.0) doesn't
give correct results on this function. For example the result of
sortIpAddressList("10.2.3.9;2001:4898:28:3:201:2ff:feea:fc14;::1;127.0.0.1;::9")
is
"[::1];10.2.3.9;127.0.0.1;[2001:4898:28:3:201:2ff:feea:fc14];[::9]"
which is incorrect in more ways than one. In contrast, Chrome does it as
expected and as in the example above. In summary the following problems
are seen with the IE 11 implementation of this function:
fe80::5efe:157.59.139.22
doesn't seem to be working. This is strange as it is used in the
example in Microsoft's own documentation.
Such an IP literal seems to throw an error which means
the PAC script will not return a result, which means IE will choose
its default option, namely "DIRECT".
"1080:0:0:0:8:800:200c:417a"
in the input will become
"[1080:0:0:0:8:800:200c:417a]"
in the output.
This too is in contrast to the documentation.
ipAddressList
- a semi-colon delimited string containing IP addressespublic String getClientVersion()
PacHelperMethodsMicrosoft
Microsoft added this function to allow IT administrators to update their PAC scripts to use different versions of the PAC processing engine without causing breaks to their existing deployment. For example, if Microsoft added a function to the 2.0 version of the the Microsoft PAC processing engine, then administrators can check the version before attempting to call that function. This allows their script to work with client running versions 1.0 and 2.0 of the engine.
Note to implementers: Currently this function should simply return "1.0" in order retain compatibility with Microsoft world.
public boolean isInNetEx(String ipAddress, String ipPrefix)
PacHelperMethodsMicrosoft
Microsoft's documentation is vague / contradictory on what the pattern
argument, ipPrefix
, is, meaning is it a list of patterns
or is it a singular pattern?. We err on the side of caution and decide that
the ipPrefix
is a semi-colon separated list of patterns and that
the method must return true
if the supplied ipAddress
matches any of the patterns in the list.
Similarly, the interpretation of the first argument, host
,
is open for discussion. In the sibling function, isInNet
, it
is clearly stated that this argument can be either a host name or a
literal IP address. But Microsoft's documentation on isInNetEx
limits the argument to only being a literal IP address. Again we err
on the side of caution and decide that this argument can be either. If
it is a host name then the method must do a name service lookup first
(to convert to IP), before the actual comparison can begin.
Examples of usage from JavaScript:
isInNetEx(ipAddress, "198.95.249.79/32"); true if the IP address of host matches exactly 198.95.249.79 isInNetEx(ipAddress, "198.95.0.0/16"); true if the IP address of the host matches 198.95.*.* isInNetEx(ipAddress, "3ffe:8311:ffff/48"); true if the IP address of the host matches 3ffe:8311:fff:*:*:*:*:* isInNetEx(ipAddress, "198.95.249.0/24;198.122.0.0/16"); true if the IP address of host matches 198.95.249.* or matches 198.122.*.*
ipAddress
- a string containing an IPv6/IPv4 addresses or a host name.ipPrefix
- a string containing semi-colon delimited IP prefixes with
top n bits specified in the bit field
(i.e. 3ffe:8311:ffff::/48 or 123.112.0.0/16).true
if the IP address matches the specified IP address
pattern ({code ipPrefix}). Also returns false
if the prefix
is not in the correct format or if addresses and prefixes of different
types are used in the comparison (i.e. IPv4 prefix and an IPv6 address).public void alert(String message)
PacHelperMethods
alert()
function.
Note that the JavaScript alert()
function should not be used in
a production PAC script. It is only intended for debugging and
unit test purpose.
The default implementation simply writes to stderr.
alert
in class PacHelperMethods
message
- text to log