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.

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:

   NameTrans fn="document-root" 
   root="D:/sun/webserver7/https-server/docs"

2. Assume that the PathCheck directives succeed.

3. The following ObjectType directive tells the server to look up the resource’s MIME type in the MIME types table:

   ObjectType fn="type-by-extension"

4. The server finds the following entry in the MIME types table, which sets the type attribute to text/html:

   type=text/html exts=htm,html

5. The server invokes the following Service directive. The value of the type parameter matches anything that does not begin with magnus-internal/.

   Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" 
   fn="send-file""

   For a list of all wildcard patterns, see Appendix B, Using Wildcard Patterns.

Here is an example that involves using another object:

1. The following NameTrans directive assigns the name personnel to the request.

   NameTrans fn=assign-name name=personnel from=/personnel

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:

   <Object name="personnel">
    Service fn="index-simple"
   </Object>

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:

   Service fn="index-simple"

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.

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:

Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"

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.