Table of Contents

OIL2 Class Standard.URLdirectory

class Standard . URLdirectory {
        oid     blockedThread;
        assoc   cachedObjects;
        assoc   cgiEnv;
        oid     defaultLoader;
        assoc   directoryHandler;
        set     extraFeatureHeaders;
        assoc   handlerOwner;
        string  logicalSiteName;
        assoc   permanentObjects;
        oid     profileObj;
        set     serviceNames;
        int32   timeOfLastSend;
        assoc   validRequests;
inherits from Object;


A URLdirectory object is created by the HTTPdaemon object for each distinct web site. The URLdirectory object maintains the registration information associated with cached objects and various services that handle portions of the site's document tree.



URLdirectory:create(oid profileObject, assoc initEnv)

Method Description

A URLdirectory object is created by an HTTPdaemon object and is not normally created manually. It creates a URLfileLoader object to process the root of the tree ("/") and create HTTPcachedFile to cache referenced files. The directories that are searched for files are obtained from the "directoryRoot" attribute of the ParseParameterFile profileObject.


URLdirectory:registerNewFeature(any announceHeader, string method1, string method2)

Method Description

Sometimes the addition of new HTTP server capabilities has to be announced by providing special HTTP headers in every response. Such headers can be added to the normal set by passing a non-nil value for the announceHeader argument. Either a string or set of strings is appropriate. The HTTP 1.1 specification (RFC 2616) defines a core set of protocol commands which are always recognized by the HTTPdaemon. The most common such command by far is GET; POST is also commonly used by HTML forms. The following are the standard commands recognized:

CommandImplementation Method

The HTTP 1.1 protocol also makes provision for additional commands that are not defined. As an example, the Web-based Distributed Authoring and Versioning (RFC 2518) utilizes several non-standard commands, such as PROPFIND, PROPPATCH, MKCOL, etc. See the class WebDAVfacility for details about enabling WebDAV support. Recognition of such new methods is enabled by the registerNewFeature method. The second and any subsequent arguments identify the new methods that are to be recognized. New methods are processed using an extensionRequest method.

Note: older client applications may not tolerate headers that they were not prepared to recognize.

Return Value

If fromObject is not nil, then zero is returned.



Method Description

Returns the set of standard headers and extension headers that should be returned by most HTTP reponses. An "Allow:" and "Server:" header are always included in the result.



Method Description

The getEnvironment method returns an associative array containing the default environment variables for the web site asssociated with the URLdirectory object. This method takes no arguments.


URLdirectory:getErrorPageSource(any errorCode, string message, any errCodeText)

Method Description

The getErrorPageSource method returns the body of a custom web page that should be displayed when the runtime error corresponding to errorCode occurs. It is made available to a Server-Side-Include processor (e.g., see HTTP_SSIprocessor) as the variable HTTP_ERROR_CODE. A server-generated explanatory message is made available as the variable HTTP_ERROR_MESSAGE. If available, the short text from the HTTP RFC that corresponds to the error code is provided in the HTTP_ERROR_CODE_TEXT variable. Any default environment variables are also made available at the time the SSI-processor (see HTTP_SSIprocessor) is invoked.

Return Value

If no custom page is defined for the indicated error, then nil is returned. Otherwise, a string representing the processed body of the custom HTML page is returned.


URLdirectory:registerDirectoryHandler(string path, oid obj, optional any ownerToken)

Method Description

Processing for a section of the web site's document tree can be delegated to special handlers. The method registerDirectoryHandler creates such a delegation point. It takes two mandatory arguments:

A handler object should be allomorphic to the URLfileLoader class.


URLdirectory:unregisterDirectoryHandler(string path, oid obj, optional any ownerToken)

Method Description

The unregisterDirectoryHandler method removes the delegation point previously created by a registerDirectoryHandler invocation.

Return Value

If fromObject is not nil, this method returns 0.


URLdirectory:getDirectoryHandlerForPath(string s)

Method Description

The getDirectoryHandlerForPath method returns the object Id of the handler object associated with the path name that is passed as an argument.


URLdirectory:listRegisteredObjects(optional int32 cachedOnly)

Method Description

The listRegisteredObjects method normally returns the set of unique object Ids that reference all permanent and cached objects associated with the site. If the optional Boolean argument cachedOnly is set to 1, then permanent objects are also included in the result.

Return Value

A set of oids.


URLdirectory:locateCachedURL(string url, optional string host, optional any exactMatchOnly)

Method Description

A previously cached web page object can be located using the locateCachedURL method. The first argument is an HTTP URL that identifies the web page/logical service. The second argument specifies the implied hostname/port address of the web server that would be filled in for unqualified URLs. It is optional. The final argument is an optional Boolean flag that indicates whether or not the search process should stop at an exact match for the request object or continue searching for the referenced object. For example, HTTP-based applications that perform form processing often pass arguments as parameters of a URL (e.g., ""). If the exactMatchOnly flag is set, only an object representing the cached result of the operation will be returned; otherwise, the cached result takes precedence, but in the absence of such a cached result, the object implementing the application ("/cgi/prog") will be returned.

Return Value

If the requested object is already cached, then its object Id is returned. This usually corresponds to an instance of of some subclass of HTTPcachedObject. It is important to note that no attempt is made to load the referenced object (that functionality is provided by the loadURL method), so if it is not already resident, then nil is returned.


URLdirectory:loadURL(any requestOrURL, string host, int32 cacheResult, assoc substVars)

Method Description

The loadURL method is nearly identical to loadURLinfo, but returns a simplified result.

Return Value

The object Id of the loaded object will be returned; if no such object can be found or loaded, then nil is returned.


URLdirectory:loadURLinfo(any requestOrURL, string host, int32 cacheResult, assoc substVars)

Method Description

The loadURLinfo method implements the underlying logic necessary to locate an HTTP-accessible object. It takes four arguments:

Return Value

If no such object can be found or loaded, then nil is returned. If the object was previously cached, then the appropriate object Id is returned. If the object must be loaded, then an array containing information about the object will be returned.
object Id of cached object
set of names
if set to 1, the names are automatically registered
if subscript 0 is nil, HTTP error code
if subscript 0 is nil, HTTP error text message
if subscript 0 is nil, error HTML body


URLdirectory:registerObject(string name, oid obj, optional int32 permanent)

Method Description

The registerObject method adds a mapping for a service or cached object within the server's document tree. If an existing object is already registered with the name, the existing object is sent a noteReplaced message and passed the name under which it was registered. If the optional Boolean argument permanent is set to 1, the object is denoted as being permanent, which means that well-behaved services such as HTTPpurgeCache will not attempt to check if the cached object should be deleted.

Return Value

If fromObject is not nil, then 0 is returned.


URLdirectory:removeFromCache(oid objToDelete, string name)

Method Description

The removeFromCache method performs the inverse of the registerObject method. It takes a minimum of two arguments. The first (and optional) argument may be an object Id of a cached object. Any arguments that are strings are treated as representing the name or aliases for the object within the server's document tree. If the first argument was an object Id, the cached object is deleted after the registration information is removed.

Return Value

If fromObject is not nil, then 0 is returned.