NAME

Uttu - web interface driver

SYNOPSIS

In httpd.conf:

PerlModule Uttu
PerlTransHandler Uttu
<Location "/some/uri">
    UttuDefine variable value
    UttuConf conf/uttu.conf conf/my.conf
</Location>

DESCRIPTION

Uttu is a web interface driver that works with a framework and function sets to build an application. Support is provided for building the infrastructure for a site -- no demands are made for doing sessions in a particular way, or authenticating against a particular database. The actual specifics are defined by the framework. This allows you to create your own flavor of Uttu, if you desire, without having to muck around in the Uttu module. Think of LPC and LPMuds with their driver and mudlib.

Uttu itself sets up a particular environment in which a content handler such as HTML::Mason handles requests. Thus, the full capabilities of the content handler are available. In addition, the global $u variable is available at all times (in Mason - methods of access may vary with the content handler environment). This is a Uttu object that contains the current configuration as well as notes for the current request.

The content handler as well as other aspects of the request handling are configured with a configuration file specified by the UttuConf Apache configuration directive. The framework and function sets may all define variables for the configuration file.

APACHE DIRECTIVES

UttuConf

UttuConf configuration/file

This will read in the specified file(s) and set up the content handler object. If the file is given with a relative path, it is understood to be relative to the current server root. Files are read in the order they are listed.

UttuDefine

UttuDefine variable value

This will set the particular variable to have the specified value for use in the configuration files. This allows such things as general configuration files that change with a username, for example, that is defined in the httpd.conf file.

Values are scalars.

UttuDefineList

UttuDefineList variable value1 value2 ...

This will set the particular variable to have the specified list of values for use in the configuration files.

Multiple uses of UttuDefineList with the same variable name will merge values.

UttuDefineMap

UttuDefineMap variable key value

This will set the particular variable to have the specified mapping of keys and values for use in the configuration files.

Multiple uses of UttuDefineMap with the same variable name will merge values.

CONFIGURATION

The configuration file is read using AppConfig. See AppConfig for file format details. This file is broken into sections, each module or function set having its own section. See the individual documentation for each module, framework, or function set for the variables defined by that module.

[global] variables

Global configuration variables directly affect how Uttu handles requests before handing off to the content handler. Some of these configuration variables may be used by function sets as defaults, for example, the database connection parameters.

Specifying the [global] section is optional (though may be required if using sections in the configuration file). If not using a [global] section, prepend <global_> to the variable names listed here, as has been done when referencing them as variables for substitutions (e.g., $global_content_handler).

content_handler

This is the content handler to use when processing pages. For example, mason is included with the standard Uttu distribution and creates an HTML::Mason::ApacheHandler object to handle pages. See Uttu::Handler for what a content handler should provide.

Uttu comes with support for AxKit (axkit), HTML::Mason (mason), and the Template Toolkit (template). See the documentation for Uttu::Handler::$global_content_handler for configuration information.

db_database, db_const_database

This is a string denoting the database, etc., hosting the database used especially by the uri-to-filename mapping. This is also the default database other modules may use.

The $dsn string used in the DBI->connect call is constructed from this.

$dsn = "dbi:$global_dbi_driver:$global_db_database"

The default is none.

db_database should allow modifications as well as read-only access. Uttu itself only neads read access. db_const_database implies that the database will not be modified.

db_driver, db_const_driver

This is the DBI driver to use. DBD::$global_db_driver (and DBD::$global_db_const_driver) must be loadable.

The default is undefined.

db_const_driver may be used to define the driver used for read-only access.

db_host, db_const_host

This is the host where the database is located.

If multiple db_host lines are present, Uttu will cycle through them until it exhausts all available hostnames, or it finds one that allows a connection. This allows failover to alternate hosts.

db_host should allow modifications as well as read-only access. Uttu itself only neads read access. db_const_host implies that the database will not be modified.

db_password, db_const_password

This is a single string which is the password to use when connecting to the database.

The default is undefined.

db_const_password is the password to use for read-only access.

db_password_file, db_const_password_file

This is the name of a file, relative to the server root if not an absolute path, which contains the password on its first line. The first line is read in, chomp'd, and then used to set db_password above. This is useful if you want to keep the password out of the configuration file.

The default is undefined.

db_const_password_file may be used to define db_const_password.

db_username, db_const_username

This is a single string which is the username to use when connecting to the database.

The default is undefined.

db_const_username defines the username for read-only access.

db_uri_map_table

This is the table in which the uri-to-filename mapping resides.

The default value is `functions'.

db_uri_map_field_file

This is the name of the field containing the component (or file) name.

The default value is `file'.

db_uri_map_field_uri

This is the name of the field containing the uri relative to the site root (the <Location> directive, for example).

The default value is `uri'.

db_uri_map_where

db_uri_map_where +{ uid => $u->note("uid") }

This should be a snippet of code returning a hash or array reference defining additional terms for the where clause used in selecting entries from the uri-to-filename mapping. $u is provided and is a reference to the current Uttu object.

See DBIx::Abstract for how to construct a where clause as a hash or array reference.

The default is undefined.

framework

This is the framework to use. This is not a required variable, but it can be useful to know during configuration which framework is being used.

The value is valid if and only if the module Uttu::Framework::$global_framework is loadable and its init function returns a true value.

A framework can set certain default values for configuration variables. For example, the Uttu::Framework::Uttu framework sets the content_handler to mason.

function_set_base

Most content handlers have directories under which the files should reside. For example, with HTML::Mason, there are component roots. This is the directory under those directories in which the web pages for function sets are installed. If multiple root directories are configured, then this is appended to all of them when looking for a page in a function set.

The default is sets. Be careful changing this. Uttu::MakeMaker expects this to be sets (for now).

handle

This is a list of file extensions that Uttu should handle. Otherwise, it will decline to rewrite the URL to point to the component (but see "translate_uri").

hostname

This is the hostname of the server. This is useful if the virtual server answers on several hostnames but the configuration is only stored with one of them. Use this if there are problems with some hostnames but not others and they are all configured with one virtual server directive.

index

This is the name of the directory index. This is added to the end of the URI if the URI is for a directory (ends in a slash - /).

Default is index.html.

internationalization

This may also be referred to as i18n.

If this is true, general support for internationalization is enabled.

If this is true and Locale::Maketext is not loadable, it will revert to false.

See Uttu::L10N for more information on internationalization.

The default is false.

lib

This is an additional directory to add to @INC when looking for Perl modules, especially during configuration. These directories are also added to @INC for each request.

map_uri

This is a mapping of URIs to filenames that overrides the database. This is also useful if the database is not setup yet, but the base modules are installed. See the documentation for the base module set for the configuration information to map URIs to filenames so documentation can be read.

This variable can appear multiple times, once per URI-to-filename mapping. The format is as follows:

map_uri /some/uri = /some/file

Only URIs that are in the mapping will be visible to the client. See the content handler documentation for exceptions (such as dhandlers and Uttu::Handler::mason).

port

This sets the port at which the virtual server is listening. This does not affect Apache, but informs Uttu of which port it should expect the connection to appear to be on. Use this if the port at request time is different than that set in the virtual host configuration directive.

translate_uri

This is a list of file extensions that Uttu should not handle yet map the uri to a filename. Uttu will handle uri-to-filename translation but not set the content handler. This is useful for graphic images that are distributed with a framework or function set.

uri_mapping

If this is true, then the URI will be mapped to a component using the map_uri information from the configuration file as well as the URI-to-filename database mapping, if available. If this is false, then the components referred to by the URIs are expected to be in the document root under the location where the configuration is read.

The default is false.

uri_map_namespace

This is the Cache::Cache namespace to use for the uri-to-filename map cache.

The default is $framework:global_uri_map.

uri_map_expiration

This is the default expiration time for items in the cache.

The default is never.

uri_map_auto_purge_interval

This is how often items are checked for expiration.

The default is never.

uri_map_size_limit

This is the maximum size of the cache. If items are added to the cache, old items are removed. This may be specified as a number followed by the letters k, g, or m (e.g., 10 M).

The default is NO_MAX_SIZE.

uri_map_sharedmemory

If this is true, then Cache::Cache will be directed to use shared memory. If this fails, the cache will not be used. It will not fall back to a non-shared memory cache.

The default is not to use shared memory.

UTTU METHODS

The following methods and functions are defined by this module and are available either via the $u global variable (in Mason components) or the Uttu package.

clear_components

$u -> clear_components($key)

This will clear the list of components associated with $key. This will only be for the current request.

comp_to_rel_uri

<a href="<% $u -> comp_to_rel_uri($comp) %>">Link Text</a>

This will translate the filename to the URI corresponding to that file. The URI that matches the current URI closest will be returned if more than one URI matches the file. $function_set_base should already be removed from the filename.

This is just like comp_to_uri except the returned URI is relative to the current URI.

comp_to_uri

<a href="<% $u->comp_to_uri($comp) %>">Link Text</a>

This will translate the filename to the URI corresponding to that file. The URI that matches the current URI closest will be returned if more than one URI matches the file. $function_set_base should already be removed from the filename.

config

This method returns the current AppConfig object.

my $c = Uttu -> config;
or
my $c = $u -> config;

define

This defines configuration variables. If no configuration file is being read, then these are cached for later use. Otherwise, they are added only to the configuration currently being read.

The arguments are almost identical to the define function in AppConfig. Uttu->define expects an even number of arguments (basically a hash).

query_cache

$cache = $u -> query_cache($config_prefix);

This will return a Cache::Cache object configured by the configuration file.

The call $u -> query_cache("global_uri_map"), for example will use the following configuration items.

[global]
  uri_map_namespace            (string)
  uri_map_expiration           (string)
  uri_map_auto_purge_interval  (string)
  uri_map_size_limit           (string)
  uri_map_sharedmemory         (boolean)

It will return undef if it can not create the cache.

query_dbh

$dbh = $u -> query_dbh($config_prefix, %options);

This will return a database handle (result of a DBIx::Abstract->connect call) for the connection configured in the configuration file.

The call $u -> query_dbh("global_db"), for example will first look for the following configuration items.

[global]
  db_const_driver    (string)
  db_const_database  (list)
  db_const_username  (string)
  db_const_password  (string)
  db_const_option    (hash)

For those of these that it can't find, it will look for the following.

[global]
  db_driver    (string)
  db_database  (list)
  db_username  (string)
  db_password  (string)
  db_option    (hash)

This function expects the *_database_* variable to be a list of suitable strings. If the string last used to make a connection does not return a valid database handle, then it will go through the rest of the list in order until either it returns to the most recently used database configuration or establishes a successful connection.

It will return undef if it can not establish a connection.

This function leaves caching of database connections to Apache::DBI.

The following options are available:

NoDefault

If this option is true, then the "global_db_*" configuration settings are not used if the equivalent settings for the requested database coniguration cannot be found.

Write

If this option is true, then the _const part of the prefix will not be considered. This is useful for specifying a database for reading and another for writing, with round robin access to either as desired.

note

This is a handy way to track information during a request. The notes are cleared at the end of each request.

Called with one argument retrieves the note. Called with two arguments sets the note.

my $context = $u -> note('context');
$u -> note('context', new My::Context ( session => $u->note('session') ));

query_components

Uttu -> query_components($key);

Returns a list of Mason components or web pages (if the content handler is not HTML::Mason, then these should be considered strings specifying pages or other functions to be called -- basically, the meaning of the return value is framework-defined). These should be called in the order returned. The key ($key) is framework-defined.

register_component

Uttu -> register_component($key, $priority, $comp);

This method registers a component in a list named by $key. The priority gives a relative ordering in which to call the components. The significant values of $key are defined by the framework.

The component $comp should be relative to the $function_set_base. For example, if $function_set_base is set to modules (the default), then $comp should be uttu/init instead of /modules/uttu/init.

Calling register_component during server startup will register the component for all requests. Otherwise, it will be removed from the list at the end of the current request.

uri_to_comp

$component = $u -> uri_to_comp($uri);

This will return the file the given URI maps to. This does not take into consideration internationalization.

URI MAPPING

Uttu looks in two places for the URI to component mapping information: internal cache, external database. The configuration file is used to provide a minimal mapping in case the database is not available.

The content handler is used to find the file in the filesystem after the URI has been mapped to a filename. That is, the content handler may use a series of directories as a path to find the file.

INTERNATIONALIZATION

Uttu has minimal support for internationalization. The reason for this is that there are already good ways to handle language choice without rewritting it all in Perl again.

Uttu lets Apache handle the choice of which file to serve after it has translated the URI to a filename. This is subject to change since it doesn't handle well the case of HTML::Mason with different component roots where one component root has working files masking some of the files in a more general or production component root.

Uttu uses Locale::Maketext as the basis for its language translation services.

If internationalization is enabled, Uttu will search through several Perl modules, using the first one it finds. These are, in order of preference and following the suggested @ISA chain,

Uttu::Framework::$framework::L10N::Local::$function_set,
Uttu::Framework::$framework::L10N::$function_set,
Uttu::Framework::$framework::L10N::Local,
Uttu::Framework::$framework::L10N,
Uttu::L10N.

BUGS

Handling Apache Restarts

This isn't so much a bug as a situation with an ugly workaround. Before 0.03, Uttu would delete all Uttu:: modules from %INC when loaded. Otherwise, certain Uttu:: modules would not be loaded into the symbol tables by Perl during an Apache restart.

This appears to not be a problem on FreeBSD 4.6 using Perl 5.6.1 and mod_perl 1.27. So the munging of %INC has been removed. If you experience problems, let me know (or better yet, send a patch that fixes them).

So, Uttu can handle an Apache restart, it just isn't always graceful about doing so.

This may be related to the next bug.

Apache::Status, Symbol Tables, and Solaris

This bug hasn't shown up on FreeBSD 4.4 and Perl 5.6.1, but with Solaris 2.7 and Perl 5.6.1, trying to dump the symbol table with Apache::Status results in a core dump if this module is loaded.

Internationalization and mod_negotiation

mod_negotiation doesn't get to see the directory in which the component or file resides until after Uttu has done the uri-to-filename conversion.

Database connections disappear

For some reason, if a website is left idle for a long time (on the order of days), the uri-to-filename mapping code will be unable to read the database (it seems). This will result in pages not being found on the server. The fix for now is to stop and restart the web server.

SEE ALSO

AppConfig, DBIx::Abstract, Locale::Maketext, Uttu::Manual, Uttu.TAMU.Edu website.

WHY UTTU?

Uttu is the Sumerian goddess of the weaving arts and is closely associated with spiders. While the Uttu module is not acting as a spider, it does weave a web.

AUTHOR

James G. Smith <jsmith@cpan.org>

COPYRIGHT

Copyright (C) 2002 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

$Id: Uttu.pod,v 1.9 2002/08/06 19:26:45 jgsmith Exp $

cpanm Uttu

perl -MCPAN -e shell
install Uttu