# WebServerBundles class documentation

### Authors

Richard Frith-Macdonald (`rfm@gnu.org`)

Version: 28737

Date: 2009-09-25 11:17:32 +0100 (Fri, 25 Sep 2009)

Copyright: (C) 2009 Free Software Foundation, Inc.

# Software documentation for the WebServerBundles class

## WebServerBundles : NSObject

> Declared in:
>   WebServerBundles.h

> Conforms to:
>   WebServerDelegate

WebServerBundles is an example delegate for the WebServer class.
This is intended to act as a convenience for a scheme where the WebServer instance in a program is configured by values obtained from the user defaults system, and incoming requests may be handled by different delegate objects depending on the path information supplied in the request. The WebServerBundles instance is responsible for loading the bundles (based on information in the WebServerBundles dictionary in the user defaults system) and for forwarding requests to the appropriate bundles for processing.
If a request comes in which is not an exact match for the path of any handler, the request path is repeatedly shortened by chopping off the last path component until a matching handler is found.
The paths in the dictionary must not end with a slash... an empty string will match all requests which do not match a handler with a longer path.

Instance Variables
Method summary

- -defaultsUpdate:
- -handlerForPath:info:
- -handlers
- -http
- -initAsDelegateOf:
- -processRequest:response:for:
- -registerHandler:forPath:
- -webAlert:for:
- -webAudit:for:
- -webLog:for:

### defaultsUpdate:

- (BOOL) defaultsUpdate: (NSNotification*)aNotification;
Handle a notification that the defaults have been updated... change WebServer configuration if necessary.

- WebServerPort must be used to specify the port that the server listens on. See [WebServer -setPort:secure:] for details.
- WebServerSecure may be supplied to make the server operate as an HTTPS server rather than an HTTP server. See [WebServer -setPort:secure:] for details.
- WebServerBundles is a dictionary keyed on path strings, whose values are dictionaries, each containing per-handler configuration information and the name of the bundle containing the code to handle requests sent to the path. NB. the bundle name listed should omit the `.bundle` extension.

Returns `YES` on success, `NO` on failure (if the port of the WebServer cannot be set).

### handlerForPath: info:

- (id) handlerForPath: (NSString*)path info: (NSString**)info;
Returns the handler to be used for the specified path, or `nil` if there is no handler available.
If the info argument is non-null, it is used to return additional information, either the path actually matched, or an error string.

### handlers

- (NSMutableDictionary*) handlers;
Return dictionary of all handlers by name (path in request which maps to that handler instance).

### http

- (WebServer*) http;
Return the WebServer instance that the receiver is acting as a delegate for.

### initAsDelegateOf:

- (id) initAsDelegateOf: (WebServer*)http;
This is a designated initialiser for the class.
Initialises the receiver as the delegate of HTTP and configures the WebServer based upon the settings found in the user defaults system by using the -defaultsUpdate: method.

### processRequest: response: for:

- (BOOL) processRequest: (GSMimeDocument*)request response: (GSMimeDocument*)response for: (WebServer*)http;

Handles an incoming request by forwarding it to another handler.
If a direct mapping is available from the path in the request to an existing handler, that handler is used to process the request . Otherwise, the WebServerBundles dictionary (obtained from the defaults system) is used to map the request path to configuration information listing the bundle containing the handler to be used.

The configuration information is a dictionary containing the name of the bundle (keyed on 'Name'), and this is used to locate the bundle in the applications resources.
Before a request is passed on to a handler, two extra headers are set in it... `x-http-path-base` and `x-http-path-info` being the actual path matched for the handler, and the remainder of the path after that base part.

We handle the incoming requests here.

### registerHandler: forPath:

- (void) registerHandler: (id)handler forPath: (NSString*)path;
Registers an object as the handler for a particular path.
Registering a `nil` handler destroys any existing handler for the path.

### webAlert: for:

- (void) webAlert: (NSString*)message for: (WebServer*)http;
Just write to stderr using NSLog.

### webAudit: for:

- (void) webAudit: (NSString*)message for: (WebServer*)http;
Log an audit record as UTF8 data on stderr.

### webLog: for:

- (void) webLog: (NSString*)message for: (WebServer*)http;
Just discard the message... please subclass or use a category to override this method if you wish to used the logged messages.

## Instance Variables for WebServerBundles Class

### _handlers

@protected NSMutableDictionary* _handlers;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _http

@protected WebServer* _http;
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.