NAME Image::Delivery - Efficient transformation and delivery of web images INTRODUCTION Many web applications generate or otherwise deliver graphics as part of their interface. Getting the delivery of these images right is tricky, and developers usually need to make trade-offs in order to get a usable mechanism. Image::Delivery is an extremely sophisticated module for delivering these generated images. It is designed to be powerful, flexible, extensible, scalable, secure, stable and correct, and use a minimum of resources. DESIGN Because it can take a little bit of work to set up Image::Delivery, we will start with a quick once-over of the design of the API, and the reasons and use cases that drove it. Preventing Multiple Server Calls Use Case 1: CVS Monitor The initial idea for Image::Delivery was due to some problems with the design of CVS Monitor (L path mapping First, you need to become aquainted with HTML::Location. This is used as the basis for the mapping between the disc and a URI. You should also make sure that whatever process will be running will have write permissions to the appropriate directory. For starters, we would suggest creating the cache directory just under the root of a website, at "$ROOT/cache", which will be linked to "http://yourwebsite.com/cache/". This will let you create your HTML::Location. # Set up the location of the cache my $Location = HTML::Location->new( "$ROOT/cache", "http://yourwebsite.com/cache" ); This gives you the absolute minimum Image::Delivery itself needs to get rolling. With a location to manage, you can then start to fire images at it, and it will store them and hand you back a HTML::Location for the actual file. # Create the Image::Delivery object my $Delivery = Image::Delivery->new( Location => $Location, ); However, the tricky bit is probably setting up your Provider class. Although the abstract class implements much of the details and defaults for you, you are probably still going to need to do some work to tie the two together. STATUS While the concept and design are fairly well understood and unlikely to change, there is an unfortunate situation with regards to the Cache:: family of modules. Although originally written to live at Cache::Web and to be a little more general, it was felt by the maintainer that Cache::Web would represent the module as being a full member of the Cache:: family, which it is not. However, during the first few releases I hope to at least try to move the API of Image::Delivery as close to Cache:: as possible, possibly under a common Cache::Interface class, to gain some potential benefits from code written on top of it. Until these comments are updated, you should assume that the API may undergo some changes. METHODS new %params The "new" constructor creates a new Image::Delivery object. It takes a number of required and optional parameters, provided as a set of key/value pairs. Location The required Location parameter Location The "Location" method returns the HTML::Location that was used when creating the Image::Delivery. filename $TransformPath | $Provider The "filename" method determines, for a given $TransformPath or $Provider, the file name that the Image should be written to, excluding the file type. This is the method most likely to be overloaded, so enable a different naming scheme. exists $TransformPath | $Provider For a given Digest::TransformPath, or a ::Provider which contains one, check to see the a file exists for it in the cache already. Returns the HTML::Location of the image if it exists, false if it does not exist, or "undef" on error. get $TransformPath | $Provider The "get" methods gets the contents of a cached file from the cache, if it exists. You should generally check that the image "exists" first before trying to get it. Returns a reference to a SCALAR containing the image data if the image exists. Returns "undef" if the image does not exist, or some other error occurs. set $Provider The "set" method stores an image in the cache, shortcutting if the image has already been stored. Returns the HTML::Location of the stored image on success, or "undef" on error. clear $TransformPath The "clear" method allows you to explicitly delete an image from the cache. This would generally be done for security purposes, as the cache cleaners will generally harvest files directly, rather than going via TransformPaths. Returns true if the image was removed, or did not exist. Returns "undef" on error. TO DO - Add ability to mask indexes with empty HTML files - Add cache clearing capabilities - Add file locking to prevent race conditions in the cache - Add pluggable cache cleaners SUPPORT All bugs should be filed via the bug tracker at For other issues, contact the author AUTHORS Adam Kennedy COPYRIGHT Copyright 2004 - 2007 Adam Kennedy. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module.