NAME

Uttu - web interface driver

SYNOPSIS

In httpd.conf:

PerlModule Uttu
PerlTransHandler Uttu
<Location "/some/uri">
    UttuConf conf/uttu.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 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.

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.

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::mason for more information on the Mason handler. See Uttu::Handler for what a content handler should provide.

db_database, db_const_database

This is a string denoting the database, hostname, 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.

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

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::$db_driver must be loadable.

The default is undefined.

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

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_select_comp

This is the SQL statement for selecting the component that corresponds to a uri. Only one component should match. There should only be one place holder (?) which is where the uri will be inserted.

The default is SELECT file FROM functions WHERE uri=?.

db_uri_map_select_uri

This is the SQL statement for selecting a uri that corresponds to a component. Multiple uris may match. There should only be one place holder (?) which is where the component name will be inserted.

The default is SELECT uri FROM functions WHERE file=?.

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 the init function returns a true value.

This is one way function sets can know how to interact with the framework, or if they can work with it at all.

Be aware that function sets that share the same name but require different frameworks will not be able to run on the same server.

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.

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.

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.

map_uri

This is a mapping or 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. A special case is if a path at the beginning of a URI is mapped to a file. This allows the use of dhandlers.

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.

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.

file_to_uri

<a href="<% $u->file_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;

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 DBI->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)

Currently, only the Write option is supported. 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.

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.

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).

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_file

$component = $u -> uri_to_file($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.

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. Currently, Uttu will delete all Uttu:: modules from %INC when loaded. Otherwise, certain Uttu:: modules will not be loaded into the symbol tables by Perl during an Apache restart.

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

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.

SEE ALSO

AppConfig, Locale::Maketext, Uttu::Manual.

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.5 2002/03/20 17:53:30 jgsmith Exp $

cpanm Uttu

perl -MCPAN -e shell
install Uttu