## org.w3c.www.protocol.http.proxy
Class ProxyDispatcher

    java.lang.Object
      |
      +--org.w3c.www.protocol.http.proxy.ProxyDispatcher

public class ProxyDispatcher
extends java.lang.Object
implements PropRequestFilter, PropertyMonitoring

The proxy dispatcher applies some rules to a request. The goal of that filter is to allow special pre-processing of requests based, on their target host, before sending them off the net.

The filter is configured through a rule file whose format is described by the following BNF: `rule-file=(record)*
record=EOL|comment|rule
comment=#(^EOL)*EOL
rule=rule-lhs(SPACE)*rule-rhs
rule-lhs=(token) |(token (. <strog>token)*
rule-lhr=forbid|direct|redirect |proxy|authorization|proxyauth
forbid=FORBID|forbid
direct=DIRECT|direct
redirect=(REDIRECT|proxy) url
proxy=(PROXY|proxy) url
url=any valid URL authorization=(AUTHORIZATION|authorization user password
proxyauth=(PROXYAUTH|proxyauth user password url
`

A sample rule file looks like this: `# Some comments edu proxy http://class.w3.org:8001/ org proxy http://class.w3.org:8001/ fr direct www.evilsite.com redirect http://www.goodsite.com/warning.html www.w3.org direct 138.96.24 direct www.playboy.com forbid default proxy http://cache.inria.fr:8080/`

The algorithm used to lookup rules is the following:

- Split all rules left hand side into its components, eg H1.H2.H3 is splitted into { H1, H2, H3 }, then reverse the components and map that to the rule. In our example above, { org, w3, www} would be mapped to direct.
- Split the fully qualified host name into its components, eg, A.B.C is splitted into { A, B, C } and reverse it.
- Find the longest match in the mapping table of rules, and get apply the given rule.

In our example, a request to www.isi.edu would match the edu rule, and a request for www.w3.org would match the direct rule, for example.

Three rules are defined:

direct
  Run that request directly against the target host.
forbid
  Emit a forbid message, indicating that the user is not allowed to contact this host.
proxy
  Run that request through the given proxy.
proxyauth
  Run that request through a proxy with the right proxy credentials.

For numeric IP addresses, the most significant part is the beginning, so {A, B, C} are deducted directly. In the example { 138, 96, 24 } is mapped to direct.

If no rules are applied, then the default rule (root rule) is applied. See the example.

Field Summary
`protected boolean` | `check_rules`
`static java.lang.String` | `CHECK_RULES_LAST_MODIFIED_P` Name of the property turning that filter in debug mode.
`protected boolean` | `debug` Are we in debug mode ?
`static java.lang.String` | `DEBUG_P` Name of the property turning that filter in debug mode.
`protected static java.lang.String` | `disabled`
`protected long` | `lastParsingTime`
`protected ObservableProperties` | `props` The properties we initialized ourself from.
`static java.lang.String` | `RULE_P` Name of the property giving the rule file URL.
`protected RuleNode` | `rules` The current set of rules to apply.

Constructor Summary
`ProxyDispatcher()` Empty constructor, for dynamic instantiation.

Method Summary
`boolean` | `exceptionFilter(Request request, HttpException ex)` Filter requests when an error occurs during the process.
`Reply` | `ingoingFilter(Request request)` Filter requests before they are emitted.
`void` | `initialize(HttpManager manager)`
`protected boolean` | `needsParsing()`
`Reply` | `outgoingFilter(Request request, Reply reply)` Filter requests after processing.
`protected void` | `parseRules()` Parse the default set of rules.
`protected void` | `parseRules(java.io.InputStream in)` Parse the given input stream as a rule file.
`boolean` | `propertyChanged(java.lang.String name)` PropertyMonitoring implementation - Commit property changes.
`void` | `sync()` We don't maintain cached infos.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### RULE_P

    public static final java.lang.String RULE_P

  Name of the property giving the rule file URL.

### DEBUG_P

    public static final java.lang.String DEBUG_P

  Name of the property turning that filter in debug mode.

### CHECK_RULES_LAST_MODIFIED_P

    public static final java.lang.String CHECK_RULES_LAST_MODIFIED_P

  Name of the property turning that filter in debug mode.

### props

    protected ObservableProperties props

  The properties we initialized ourself from.

### rules

    protected RuleNode rules

  The current set of rules to apply.

### debug

    protected boolean debug

  Are we in debug mode ?

### check_rules

    protected boolean check_rules

### disabled

    protected static final java.lang.String disabled

### lastParsingTime

    protected long lastParsingTime

Constructor Detail

### ProxyDispatcher

    public ProxyDispatcher()

  Empty constructor, for dynamic instantiation.

Method Detail

### parseRules

    protected void parseRules(java.io.InputStream in)
                       throws java.io.IOException,
                              RuleParserException

  Parse the given input stream as a rule file.
  Parameters:
    `in` - The input stream to parse.
  Throws:
    java.io.IOException - if an IO error occurs.
    RuleParserException - if parsing failed.

### parseRules

    protected void parseRules()

  Parse the default set of rules.

  IOf the rules cannot be parsed, the filter emits an error message to standard error, and turn itself into transparent mode.

### needsParsing

    protected boolean needsParsing()

### ingoingFilter

    public Reply ingoingFilter(Request request)

  Filter requests before they are emitted. Look for a matching rule, and if found apply it before continuing the process. If a forbid rule was apply, this method will return with a forbidden message.
  Parameters:
    `request` - The request to filter.
  Returns:
    A Reply instance, if processing is not to be continued, falseotherwise.

### exceptionFilter

    public boolean exceptionFilter(Request request,
                                   HttpException ex)

  Filter requests when an error occurs during the process. This filter tries to do a direct connection if it is needed
  Parameters:
    `reques` - The request to filter.
    `reply` - It's associated reply.
  Returns:
    Always null.

### outgoingFilter

    public Reply outgoingFilter(Request request,
                                Reply reply)

  Filter requests after processing. This filter doesn't do any post-processing.
  Parameters:
    `reques` - The request to filter.
    `reply` - It's associated reply.
  Returns:
    Always null.

### propertyChanged

    public boolean propertyChanged(java.lang.String name)

  PropertyMonitoring implementation - Commit property changes.
  Specified by:
    propertyChanged in interface PropertyMonitoring
  Parameters:
    `name` - The name of the property that has changed.
  Returns:
    A boolean true if change was commited, false otherwise.

### initialize

    public void initialize(HttpManager manager)

  Specified by:
    initialize in interface PropRequestFilter

### sync

    public void sync()

  We don't maintain cached infos.