There are a mountain of changes to the codebase coming (tues night,
2-Jan-2001) to change to our new Context mechanisms, so here is a heads
up to what is going to happen, and comments please :
Summary
-------
0) There is no change to application functionality! Everything will
work the same, with same performance. Really!
1) Except! The name of the class Context is changing, as we are going to
use it for the name of the Context interface since it's the most
fundamental. Therefore, wherever you use
import org.apache.velocity.Context;
Context c = new Context();
change to
import org.apache.velocity.VelocityContext;
VelocityContext c = new VelocityContext();
For those that use servlets derived from VelocityServlet, nothing will
change for you as VelocityServlet will be adjusted accordingly (along
with Anakia, Texen, Test, the testbed, everything.) When this commit is
complete, just rebuild.
Details
-------
In order to support Fedor's excellent context chaning idea, as well as
allow for alternative implementations of the Context (there is a
DB-based example for fun...), as well as decouple the internals from the
application-level Context to a more general, protected and flexible
approach, the whole Context scheme has been redone a bit.
1) There is now a distinction between the 'application level Context',
with the get(), put(), remove(), containsKey(), keys() methods we all
have come to know and love, and the 'internal Context' which is for
internal use in Velocity. This really only matters to the internals.
Apps don't see a difference.
2) There is now a package org.apache.velocity.context which has all of
the low-level / internal code, and we use it to prevent apps from
digging into the internals. Again, this doesn't matter to apps as they
will still use org.apache.velocity.VelocityContext. If an app wants to
create a custom Context implementation, it will need to use classes from
the .context package, but only then.
3) There is now a class org.apache.velocity.VelocityContext that
replaces org.apache.velocity.Context as the Context for application
use. It is HashMap rather than Hashtable based (although the base class
handles the nulls, so it doesn't matter... there may be a performance
improvement as there is no synchronization...) It has the same
interface as the current Context, except it supports context chaining
via a new additional constructor :
VelocityContext c1 = new VelocityContext();
c1.put("foo", bar);
VelocityContext c2 = new VelocityContext( c1 );
c2.put("gloog", floog );
template.merge( c2, writer );
and the template will transparently access $foo as it would $gloog.
Yes, this is a stupid example, but very useful, say, in a framework
which supplies a context loaded with data or tools to session-handling
code, etc. See previous list traffic re this.
4) The AST no longer uses the class Context throughout but
InternalContextAdapter, an adapter class that supports all required
context interfaces, both internal as well as app-level. This is solely
an internal change and won't affect applications, nor internals in a
functional way. It 'wraps' the Context passed into Template.merge(),
supporting the Context interface, so for all practical purposes, it's
little more than a class name change. [It does a bit more, but that's
not important here...]
5) There is an abstract class AbstractContext that is the base class for
VelocityContext and intended as the base class for all general purpose
Context implementations beyond VelocityContext. It's trivial to extend
- all you have to do is supply a storage mechanism (like a Hashtable)
and implement the 5 access functions that correspond to get(), put(),
contains(), keys() and remove(). Examples extensions will be provided,
including my goofy DBContext which serializes objects to MySQL. It also
takes care of the chaining, as well as handle null keys and values (
does the logging...). Again, this is only important if the
Velocity-supplied VelocityContext isn't sufficient, and you need
something different (like an LDAP-connected context, the DB-connected
context, a BunnyContext, the dreaded and fearsome
SendACamelToCairoContext...)
While not 100% up-to-date, the code in the /whiteboard under
geir_context_2000128 should give you the gist, as well as the orignal
Fedor code and some of the back-and-forth in jason's code. Note that
that code is not 100% up to date, as I am working on it now, and further
does not include all changed code, as this change required touching
everything (as Context changed to InternalContextAdapter throughout the
AST code and also moved into a package org.apache.velocity.context )
Comments, questions and concerns, as always...
geir
--
Geir Magnusson Jr. [EMAIL PROTECTED]
Velocity : it's not just a good idea. It should be the law.
http://jakarta.apache.org/velocity
