[JK2] urimap RFC

[Mladen Turk <mt...@apache.org>]

Hi,

There is IMO some confusion (missunderdending would be put better)
regarding host/context/uri configuration and processing that I would
like to clear out.
Having some RFC would make that subject once and for all clear ;).

1. General inheritance table:
|HOST|->|CONTEXT'S|->|URIS'S|

1.1 There is a default HOST named '*:*' 
1.2 For each HOST entry there is a CONTEXT table.
1.3 For each HOST there is a default CONTEXT table entry named '/'
1.4 For each HOST there is a URI table.

2. Host name parsing:

General host configuration setting is in the form:

2.1 [host:hostname[:port]]
This will create HOST table 'hostname' entry with optional 'port'
If the 'port' isn't specified it's name is set to '*' and the 'hostname'
entry is
marked as 'wildmatch'.

2.2 [uri:hostname[:port]/mappeduri]
This is a shortened version that combines two directive settings:
[host:hostname[:port]]
[uri:/mappeduri]
host=hostname[:port]
In the case the 'hostname' entry wasn't found, the one is created.

2.3 Host naming:
Host's can be specified as 'proper' or 'wildmatch'.
Wildmatch names are the one having one or more star '*' or question-mark
'?' symbols.
Star symbol replaces any number of characters, while the question-mark
replaces single character.

2.4 Inheriting globals
Each newly created host inherits all the 'global' setting.
The global settings are the one inside default ('*:*') host entry, and
are actually duplicated
for each newly created host entry.
If there is 'inheritglobals=0' directive when the newly host is about to
be created, then the
'global' settings are not copied from default host.


3. Context name parsing:

General context configuration directive:

3.1 [context:hostname[:port]/contextname]
This will create CONTEXT table '/contextname' inside the 'hostname'
entry.
Each new [uri] directive will match against that entry:
[uri:/contextname/mappeduri]
will set the uri's context to the '/contextname' CONTEXT's table entry;

4. Uri name parsing:

Each uri has to start with the slash '/' or with the dollar '$' sign.
Uri's starting with the dollar sign are regular expression statements.

General uri configuration directive:

4.1 [uri:/mappeduri]
This is a general uri mapping directive that sets the URI's entry of the
longest-matched context
inside default host.

4.2 Overriding host:
The host can be overridden by specifying hostname[:port] entry inside
the uri path or as a specific entry.
[uri:hostname[:port]/mappeduri]
or
[uri:/mappeduri]
host=hostname[:port]

The specified host table entry is created if not found.

4.3  Overriding context:
All the uri's has the corresponding context either default, or
longest-match matched
You can override that context stating:
[uri:/mappeduri]
context=/othercontextname

This will set the uri's context to the /othercontextname CONTEXT's table
entry.
If the /othercontextname entry is not fount the one is created.

5. Uri naming:

5.1 Proper uri names - exact matches
Proper uri names are the one starting with '/' symbol and having no
wildmatch characters.
Those names are checked first during uriMap phase and are called 'exact
matches'.

5.2 Wildmatch uri names
Wildmatch names are the one having one or more star '*' or question-mark
'?' symbols.
Star symbol replaces any number of characters, while the question-mark
replaces single character.

5.3 Regular expression names
The regular expression uri directives starts with the '$' sign.
They are compiled during configuration phase, and each are matched
against request uri as last.

6. Uri matching:

Uri matching involves two basic steps:

6.1 Host matching
Hosts are matched first to give the corresponding host table entry.

6.1.1 First look for the exact entry.
6.1.2 Second we look for the exact hostname match.
6.1.3 Then we look for the wildmatch hostname and exact port.
6.1.4 Finally the default host ('*:*') is returned.

6.2 Uri matching

Uri matching has tree phases:

6.1.1 Found exact match first.
6.1.2 Found wildmatch next.
6.1.3 Finally check the regular expression.
6.1.4 There is a special case when the configured uri entry is 'proper'
(having no wildmatch entices),
and doesn't ends with slash '/'. If the matched uri ends with slash and,
it will match to that uri if that
ending slash is the only difference.
This enables that the '/examples' and '/examples/' are matched against
the '/examples', and are used for
default directory index matches, during directory rewrite phase.


Suggestions and corrections (quoted smartly ;) are very welcomed.

MT. 


---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org