Flow of Control in obj.conf

                                                                                                                                                                                                                                                                                                                                      *Back to [[Book|Administrator's Configuration File Reference#cfr]]     [[Topic|Administrator's Configuration File Reference#chap6]]*
h2. Flow of Control in {{obj.conf}}
Before the server can process a request, it must direct the request to the correct virtual server. After the virtual server is determined, the server executes the {{obj.conf}} file of the specified virtual server. This section discusses how the server decides which directives to execute in {{obj.conf}}.

h3. {{AuthTrans}} {anchor:auth}

When the server receives a request, it executes the {{AuthTrans}} directives in the {{default}} object to check if the client is authorized to access the server. If there is more than one {{AuthTrans}} directive, the server executes them in sequence until one succeeds in authorizing the user, unless one of them results in an error. If an error occurs, the server skips all other directives except for the {{Error}} directive.

{{AuthTrans}} directives work in conjunction with the {{PathCheck}} directives. The {{AuthTrans}} directive checks if the user name and password associated with the request are acceptable, but it does not allow or deny access to the request; that is done by the {{PathCheck}} directive.

The authorization process is split into two steps to incorporate multiple authorization schemes easily and provide the flexibility to have resources that record authorization information.

When a client initially makes a request, the user name and password are unknown. The {{AuthTrans}} directive gets the user name and password from the headers associated with the request. The {{AuthTrans}} and {{PathCheck}} directives work together to reject the request if they cannot validate the user name and password. When a request is rejected, the server displays a dialog box. The client includes the user name and password in the headers and resubmits the request.

h3. {{NameTrans}} {anchor:name}

The server executes a {{NameTrans}} directive in the {{default}} object to map the logical URL of the requested resource to a physical path name on the server’s file system. For example, the URL {{http://www.test.com/some/file.html}} could be translated to the full file system path:
{code}
/usr/sun/webserver7/https-server/docs/some/file.html
{code}

The server looks at each {{NameTrans}} directive in the {{default}} object in turn, until it finds one that can be applied.

Because the server might not execute all {{NameTrans}} directives, the order in which the directives appear is important. For example:
{code}
NameTrans fn="document-root"
root="D:/sun/webserver7/https-server/docs"
NameTrans fn="pfx2dir"
from="/cgi"
dir="D:/sun/webserver7/https-server/docs/mycgi"
name="cgi"
{code}

In this example, the directive that calls {{pfx2dir}} will never be executed because the previous directive always establishes the physical path name for the resource. For the {{/cgi}} prefix to work, the directive that calls {{pfx2dir}} must be moved before the directive that calls {{document-root}}.

If no directive sets the physical path name, the server translates the logical URL to a file system path relative to the document root. The document root is specified by the {{document-root}} element in {{server.xml}}. For more information on the {{document-root}} element, see [{{virtual-server}}|V & W#v2].

h4. How and When the Server Processes Other Objects

As a result of executing a {{NameTrans}} directive, the server might start processing directives in another object. This happens if the {{NameTrans}} directive that was successfully executed specifies a name or generates a partial path that matches the {{name}} or {{ppath}} attribute of another object.

If the successful {{NameTrans}} directive assigns a name by specifying a {{name}} argument, the server starts processing directives in the named object (defined with the {{object}} tag) before processing directives in the {{default}} object for the rest of the request-handling process.

For example, the following {{NameTrans}} directive in the {{default}} object assigns the name {{cgi}} to any request whose URL starts with {{http://_server_name_/cgi/}}.
{code}
<Object name="default">
...
NameTrans fn="pfx2dir"
from="/cgi"
dir="D:/sun/webserver7/https-server/docs/mycgi" name="cgi"
...
</Object>
{code}

When the {{NameTrans}} directive is executed, the server starts processing directives in the object named {{cgi}}:
{code}
<Object name="cgi">

</Object>
{code}

When a {{NameTrans}} directive is successfully executed, there is a physical path name associated with the requested resource. If the resultant path name matches the {{ppath}} (partial path) attribute of another object, the server starts processing directives in the other object before processing directives in the {{default}} object for the rest of the request-handling process.

For example, assume {{obj.conf}} contains an object as follows:
{code}
<Object ppath ="*internal*">

</Object>
{code}

Consider that a successful {{NameTrans}} directive translates the requested URL to the path name {{D:/sun/webserver7/https-server/docs/internalplan1.html}}. In this case, the partial path {{* internal *}} matches the path {{D:/sun/webserver7/https-server/docs/internalplan1.html}}. Hence, the server will process the directives in this object before processing the remaining directives in the {{default}} object.

h3. {{PathCheck}} {anchor:path}

After converting the logical URL of the requested resource to a physical path name in the {{NameTrans}} step, the server executes {{PathCheck}} directives to verify that the client is allowed to access the requested resource.

If there is more than one {{PathCheck}} directive, the server executes all directives in the order in which they appear, unless one of the directives denies access. If access is denied, the server switches to executing directives in the {{Error}} section.

If the {{NameTrans}} directive assigned a name or generated a physical path name that matches the {{name}} or {{ppath}} attribute of another object, the server first applies the {{PathCheck}} directives in the matching object before applying the directives in the {{default}} object.

h3. {{ObjectType}} {anchor:object}

Assuming that the {{PathCheck}} directives approve access, the server next executes the {{ObjectType}} directives to determine the MIME type of the request. The MIME type has three attributes: {{type}}, {{encoding}}, and {{language}}. When the server sends the response to the client, the {{type}}, {{language}}, and {{encoding}} values are transmitted in the headers of the response. The {{type}} also frequently helps the server to determine which {{Service}} directive to execute to generate the response to the client.

If there is more than one {{ObjectType}} directive, the server applies all directives in the order in which they appear. However, once a directive sets an attribute of the MIME type, further attempts to set the same attribute are ignored. The reason why all {{ObjectType}} directives are applied is that one directive may set one attribute, for example {{type}}, while another directive sets a different attribute, such as {{language}}.

As with the {{PathCheck}} directives, if another object has been matched to the request as a result of the {{NameTrans}} step, the server executes the {{ObjectType}} directives in the matching object before executing the {{ObjectType}} directives in the {{default}} object.

{code}
type=text/html exts=htm,html
{code}

which indicates that all files with the extension {{.htm}} or {{.html}} are text files formatted as HTML, and the {{type}} is {{text/html}}.

{info:title=Note - }If you make changes to the MIME types file, you must reconfigure the server for the changes to take effect.
{info}

h4. Forcing the Type

If no {{ObjectType}} directive has set the type and the server does not find a matching file extension in the {{MIME}} types table, the type still has no value even after {{type-by-expression}} has been executed. Usually if the server does not recognize the file extension, it is a good idea to force the type to be {{text/plain}}, so that the content of the resource is treated as plain text. There are also other situations where you might want to set the type regardless of the file extension, such as forcing all resources in the designated CGI directory to have the MIME type {{magnus-internal/cgi}}.

The function that forces the type is {{force-type}}.

For example, the following directives first instruct the server to look in the MIME types table for the MIME type, then if the {{type}} attribute has not been set (that is, the file extension was not found in the MIME types table), set the {{type}} attribute to {{text/plain}}.
{code}
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
{code}

If the server receives a request for a file {{abc.date}}, it looks in the MIME types table, does not find a mapping for the extension {{.date}}, and consequently does not set the {{type}} attribute. As the {{type}} attribute has not already been set, the second directive is successful in forcing the {{type}} attribute to {{text/plain}}.

The following example illustrates another use of {{force-type}}. In this example, the {{type}} is forced to {{magnus-internal/cgi}} before the server gets a chance to look in the MIME types table. In this case, all requests for resources in {{http://}}_server_name_{{/cgi/}} are translated into requests for resources in the directory {{D:/sun/webServer7/https-server/docs/mycgi/}}. As a name is assigned to the request, the server processes the {{ObjectType}} directives in the object named {{cgi}} before processing the ones in the {{default}} object. This object has one {{ObjectType}} directive, which forces the {{type}} to be {{magnus-internal/cgi}}.
{code}
NameTrans fn="pfx2dir"
from="/cgi"
dir="D:/sun/webserver7/https-server/docs/mycgi" name="cgi"
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>
{code}

The server continues processing all {{ObjectType}} directives including those in the {{default}} object, but as the {{type}} attribute has already been set, no other directive can set it to another value.

h3. {{Input}} {anchor:input}

The {{Input}} directive selects filters that will process incoming request data read by the {{Service}} step. {{Input}} directives are invoked when the server or plug-in first attempts to read entity body data from the client. You can add the NSAPI filters that process incoming data by invoking the {{insert-filter}} SAF in the {{Input}} stage of the request-handling process. NSAPI filters enable a function to intercept and potentially modify the content presented to or generated by another function. The {{Input}} directives are executed once per request.

The order of {{Input fn="insert-filter"}} and {{Output fn="insert-filter"}} directives in {{obj.conf}} is important if two or more filters are defined to occupy the same location in the filter stack. Filters that were inserted later will appear higher than filters that were inserted earlier.

h3. {{Output}} {anchor:output}

The {{Output}} directive selects filters that will process outgoing response data generated by the {{Service}} step. The {{Output}} directive allows you to invoke the {{insert-filter}} SAF to install NSAPI filters that process outgoing data. NSAPI filters enable a function to intercept and potentially modify the content presented to or generated by another function. {{Output}} directives are executed when the server or a plug-in first attempts to write entity body data from the client. The {{Output}} directives are executed once per request.

The order of {{Input fn="insert-filter"}} and {{Output fn="insert-filter"}} directives in {{obj.conf}} is important if two or more filters are defined to occupy the same location in the filter stack. Filters that were inserted later will appear higher than filters that were inserted earlier.

h3. {{Route}} {anchor:route}

If a {{Service}} directive requires that the HTTP request be sent to another server, the server executes {{Route}} directives to determine how the request should be routed. Routing a request can involve selecting the server that will ultimately service the request and selecting a proxy through which the request is sent.

h3. {{Service}} {anchor:service}

The server executes a {{Service}} directive to generate the response to send to the client. The server looks at each {{Service}} directive to find the first one that matches the type, method, and query string. If a {{Service}} directive does not specify type, method, or query string, then the unspecified attribute matches anything.

If there is more than one {{Service}} directive, the server applies the first one that matches the conditions of the request and ignores all remaining {{Service}} directives.

For the {{PathCheck}} and {{ObjectType}} directives, if another object has been matched to the request as a result of the {{NameTrans}} step, the server considers the {{Service}} directives in the matching object before considering the ones in the {{default}} object. If the server successfully executes a {{Service}} directive in the matching object, it will not execute the {{Service}} directives in the {{default}} object, because it only executes one {{Service}} directive.

h4. Service Examples

Consider an example where the server receives a request for the URL {{D:/}}_server_name_{{/jos.html}}. In this case, all directives executed by the server are in the {{default}} object.

1. The following {{NameTrans}} directive translates the requested URL to {{D:/sun/webserver7/https-server/docs/jos.html}}:
{code}
NameTrans fn="document-root"
root="D:/sun/webserver7/https-server/docs"
{code}
2. Assume that the {{PathCheck}} directives succeed.
3. The following {{ObjectType}} directive tells the server to look up the resource&rsquo;s MIME type in the MIME types table:
{code}
ObjectType fn="type-by-extension"
{code}
4. The server finds the following entry in the MIME types table, which sets the {{type}} attribute to {{text/html}}:
{code}
type=text/html exts=htm,html
{code}
5. The server invokes the following {{Service}} directive. The value of the {{type}} parameter matches anything that does _not_ begin with {{magnus-internal/}}.
{code}
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*"
fn="send-file""
{code}
For a list of all wildcard patterns, see [Appendix&nbsp;B: Using Wildcard Patterns|Administrator's Configuration File Reference#appB].

Here is an example that involves using another object:
\\
1. The following {{NameTrans}} directive assigns the name {{personnel}} to the request.
{code}
NameTrans fn=assign-name name=personnel from=/personnel
{code}
2. As a result of the name assignment, the server switches to processing the directives in the object named {{personnel}}. This object is defined as:
{code}
<Object name="personnel">
Service fn="index-simple"
</Object>
{code}
3. The personnel object has no {{PathCheck}} or {{ObjectType}} directives, so the server processes the {{PathCheck}} and {{ObjectType}} directives in the {{default}} object. Assume that all {{PathCheck}} and {{ObjectType}} directives succeed.
4. When processing {{Service}} directives, the server starts by considering the {{Service}} directive in the {{personnel}} object, which is:
{code}
Service fn="index-simple"
{code}
5. The server executes this {{Service}} directive, which calls the {{index-simple}} function.
As a {{Service}} directive has now been executed, the server does not process any other {{Service}} directives. However, if the matching object did not have a {{Service}} directive that was executed, the server would continue looking at {{Service}} directives in the default object.

h4. Default Service Directive

There is usually a {{Service}} directive that does the default task (sends a file) if no other {{Service}} directive matches a request sent by a browser. This default directive should come last in the list of {{Service}} directives in the default object to ensure that it only gets called if no other {{Service}} directives have succeeded. The default {{Service}} directive is usually:
{code}
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
{code}

This directive matches requests whose method is {{GET}}, {{HEAD}}, or {{POST}}, which covers nearly all requests sent by browsers. The value of the {{type}} argument uses special pattern-matching characters.

The characters *{{~}} mean anything that does not match the following characters, so the expression *{{~magnus-internal/}} means anything that does not match {{magnus-internal/}}. An asterisk by itself matches anything, so the whole expression *{{~magnus-internal/}} * matches anything that does not begin with {{magnus-internal/}}.

So if the server has not already executed a {{Service}} directive when it reaches this directive, it executes the directive as long as the request method is {{GET}}, {{HEAD}}, or {{POST}}, and the value of the {{type}} attribute does not begin with {{magnus-internal/}}. The invoked function is {{send-file}}, which simply sends the contents of the requested file to the client.

h3. {{AddLog}} {anchor:add}

After the server generates the response and sends it to the client, it executes {{AddLog}} directives to add entries to the log files. All {{AddLog}} directives are executed. The server can add entries to multiple log files.

h3. {{Error}} {anchor:error}

If an error occurs during the request-handling process, for example, if a {{PathCheck}} or {{AuthTrans}} directive denies access to the requested resource or the requested resource does not exist, the SAF sets the HTTP response status code and returns the value {{REQ_ABORTED}}. When this happens, the server stops processing the request. Instead, it searches for an {{Error}} directive matching the HTTP response status code or its associated reason phrase and executes the directive&rsquo;s function. If the server does not find a matching {{Error}} directive, it returns the response status code to the client.