[PROPOSAL] Unification of Loaders

[jv...@periapt.com]

This is a proposal for the unification of text resource nabbing
in Velocity :-) For this proposal I will call a text resource text 
that is either parsed or #include'd by Velocity. This proposal
I would like to throw out to list to see if there are any takers:
if someone decides to try this and successfully implements
it then you get CVS write access and your name gets put on
the contributors' list. I would just like to encourage others
to become core developers: the reworking of the text resource
loaders is something that needs to be done before I release
so hopefully someone will step forward to give it a whirl!

What follows is a brief sketch of what needs to be done
to rework the resource loading mechanism.

---

Parsed text is pulled in via the Runtime.getTemplate(name) method: 
this method is used in application code, like servlets, and this 
method is also used internally by the #parse directive.

The Runtime.getTemplate(name) method can search multiple sources
for templates based on the configuration of what are now called
template loaders. Typically the FileTemplateLoader is used and
its configuration looks something like the following:

template.loader.1.public.name = File
template.loader.1.description = Velocity File Template Loader
template.loader.1.class = org.apache.velocity.runtime.loader.FileTemplateLoader
template.loader.1.template.path = .
template.loader.1.cache = false
template.loader.1.modificationCheckInterval = 2

Although this is typically the configuration, you can have multiple
template loaders configured and Velocity will query all the
template loaders looking for a specified template. So in
theory you could have a DBTemplateLoader, a JARTemplateLoader, or
whatever else you desire.

Right now #include'd text is pulled in from the filesystem. This
is handled inside the org.apache.velocity.runtime.directive.Include
class and the configuration for the include paths looks like the
following:

include.path=.
include.cache = false
include.output.errormsg.start = <!-- include error : 
include.output.errormsg.end   =  see error log -->

The Velocity Runtime will actually store multiple include paths,
but the properties listed above are not set up for this to work
properly for caching. For example you could have the following:

include.path = /path1
include.path = /path2

But the caching property isn't being looked at right now, and the
paths are all file based.

What I propose is that the same loading mechanism used for the templates
right now be expanded to allow for the loading of static content from
multiple sources.

So this would probably involve a some reworking of what is now the
template loader system. If the template loader system was reworked
then you could pull in static content from any source like a DBStaticLoader,
or JARStaticLoader, or something like that.

What the template loaders actually do is provide an InputStream so
'template loader' is a bit of a misnomer because the template loaders
don't actually do any template parsing i.e. template loaders don't
actually return a parsed template object but rather an InputStream. So
a more appropriate name would be something like TextResourceLoader,
or StreamSource or something like that. And because the loaders
currently return an InputStream the #include directive could 
easily adapted to use the same mechanism. Then all the caching,
and general management of these text resources can be dealt with
in a single place. 

Another benefit would be that input filters (another proposal) could 
be used to modify any text resource. You might want to use 
an input filter to convert a WM template to a Velocity template before
being handed off to the Velocity parser, or you might want to strip
out certain elements of the template like <% %> tags: this would allow
the templates to be played with by designers in DreamWeaver, yet the
tags would be stripped out before the templates were parsed.

These filters could also be used on #include'd content: you might
want to use an input filter to replace profanity with #$@!$ on a discussion
forum or simply remove it, or a spelling correction filter, or anything
else you wanted.

The org.apache.velocity.runtime.loader.TemplateLoader class could
probably be used as the basis for this new system, so really what
might be involved in reworking the loading system would be the
following:

1) Pick better names for the loaders :-)
2) Create a decent interface/baseclass for a loader
3) Create a single property set for loaders:

resource.loader.1.public.name = File
resource.loader.1.description = Velocity File Resource Loader
resource.loader.1.class = org.apache.velocity.runtime.loader.FileResourceLoader
resource.loader.1.path = .
resource.loader.1.cache = false
resource.loader.1.modificationCheckInterval = 2

There is some code for instantiating/managing multiple loaders in the
Runtime now, but you'll probably want to differentiate between loaders
used for static text and loaders used for templates. So the properties
might have to change a bit: you could probably list all the loaders
and then have a list which states what loaders are to be used for
templates, and what loaders are to be used for static #include'd text.
You could probably use the public.name for this:

## Load templates from the File resource loader
## and the JAR resource loader.
template.loader=File
template.loader=JAR

## Load templates from the File resource loader
## and the Database resource loader.
static.loader=File
static.loader=DB

There are two places in the Velocity Runtime that you would want
to look to see how the properties for the loaders are currently
dealt with:

assembleSourceInitializers()
initTemplateLoader() [ this should be renamed :-) ]

If anyone is interested just post to the list and we'll
figure it out. I would be more then happy to help anyone
get started :-)

The text of this proposal is also in CVS if anyone
wants to make any corrections. It's in the proposals
directory :-)

jvz.