cvs commit: jakarta-velocity/proposals loader-unification

[jv...@locus.apache.org]

jvanzyl     00/12/15 08:27:10

  Added:       proposals loader-unification
  Log:
  - a template loader unification proposal: use the same underlying
    mechanism for template text and static text.
  
  Revision  Changes    Path
  1.1                  jakarta-velocity/proposals/loader-unification
  
  Index: loader-unification
  ===================================================================
  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 :-)
  
  jvz.