Uttu - web interface driver
In httpd.conf:
PerlModule Uttu
PerlTransHandler Uttu
<Location "/some/uri">
UttuDefine variable value
UttuConf conf/uttu.conf conf/my.conf
</Location>
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.
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 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 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 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.
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 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).
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.
This is the table in which the uri-to-filename mapping resides.
The default value is `functions'.
This is the name of the field containing the component (or file) name.
The default value is `file'.
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 +{ 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.
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.
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).
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").
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.
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.
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.
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.
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).
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.
This allows resource configuration to be done via an XML file. See Uttu::Resource for more information on the XML schema. This requires XML::XPath and some of the ResourcePool modules, which will not be loaded unless this variable is set.
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.
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.
This is the Cache::Cache namespace to use for the uri-to-filename map cache.
The default is $framework:global_uri_map.
This is the default expiration time for items in the cache.
The default is never.
This is how often items are checked for expiration.
The default is never.
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.
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.
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.
$u -> clear_components($key)
This will clear the list of components associated with $key. This will only be for the current request.
<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.
<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.
This method returns the current AppConfig object.
my $c = Uttu -> config; or my $c = $u -> config;
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).
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') ));
$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.
$dbh = $u -> query_dbh($config_prefix);
This will return a database handle previously configured in the resources configuration file.
It will return undef if it can not establish a connection.
This function leaves caching of database connections to ResourcePool.
The database handle will be freed at the end of the current Apache request handling phase.
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.
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 sets (the default), then $comp should be uttu/init instead of /sets/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.
$pool = Uttu -> resource($key); $handle = $pool -> get(); # do stuff $pool -> free($handle) # or (if an error) $pool -> fail($handle)
This method will return the ResourcePool::LoadBalancer object managing the specified resource.
$component = $u -> uri_to_comp($uri);
This will return the file the given URI maps to. This does not take into consideration internationalization.
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.
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.
Please report bugs to either the request tracker for CPAN (http://rt.cpan.org/|http://rt.cpan.org/) or on the SourceForge project (http://sourceforge.net/projects/gestinanna/|http://sourceforge.net/projects/gestinanna/>).
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 but it just isn't always graceful about doing so.
This may be related to the next bug.
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.
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.
Apache must be started while in the root (/) directory. Otherwise, Uttu may be unable to find certain modules or files. This doesn't show up when running the tests. This may be fixed already. This notice will be removed in a future release when it has been more thoroughly tested.
AppConfig, DBIx::Abstract, Locale::Maketext, ResourcePool, Uttu::Manual, Uttu.TAMU.Edu website.
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.
James G. Smith <jsmith@cpan.org>
Copyright (C) 2002-2003 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.14 2003/04/16 19:43:22 jgsmith Exp $
