geirm 02/03/14 20:26:39
Modified: xdocs developer-guide.xml
docs developer-guide.html
Log:
Update : added docs on the application attributes and the pluggable
resource cache and manager
Revision Changes Path
1.67 +117 -1 jakarta-velocity/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
retrieving revision 1.66
retrieving revision 1.67
diff -u -r1.66 -r1.67
--- developer-guide.xml 14 Mar 2002 13:36:37 -0000 1.66
+++ developer-guide.xml 15 Mar 2002 04:26:38 -0000 1.67
@@ -63,6 +63,10 @@
<li><a href="developer-guide.html#Exceptions">Exceptions</a></li>
<li><a href="developer-guide.html#Miscellaneous Details">Miscellaneous
Details</a></li>
</ul>
+</li>
+
+<li>
+ <a href="developer-guide.html#Application Attributes">Application Attributes</a>
</li>
<li>
@@ -88,9 +92,15 @@
<li>
<a href="developer-guide.html#Configuring Resource Loaders">Configuring the
Resource Loaders (template loaders)</a>
<ul>
+ <li>
+ <a href="developer-guide.html#Resource Loaders">Resource Loaders</a>
+ </li>
<li>
<a href="developer-guide.html#Configuration Examples">Configuration
Examples</a>
</li>
+ <li>
+ <a href="developer-guide.html#Resource Manager and Cache">Pluggable Resource
Manager and Resource Cache</a>
+ </li>
</ul>
</li>
@@ -1541,6 +1551,57 @@
information - the error messages are pretty good for figuring out what is wrong.
</p>
</section>
+
+<section name="Application Attributes">
+<p>
+<i>Application Attributes</i> are name-value pairs that can be associated with
+a RuntimeInstance (either via the <code>VelocityEngine</code> or
+the <code>Velocity</code> singleton) and accessed from any part of the Velocity
+engine that has access to the RuntimeInstance.
+</p>
+
+<p>
+This feature was designed for applications that need to communicate between
+the application layer and custom parts of the Velocity engine, such as
+loggers, resource loaders, resource managers, etc.
+</p>
+
+<p>
+The Application Attribute API is very simple. From the application layer, there
+is a method of the <code>VelocityEngine</code> and the <code>Velocity</code>
+classes :
+</p>
+
+<source>
+<![CDATA[
+ public void setApplicationAttribute( Object key, Object value );
+]]>
+</source>
+
+<p>
+through which an application can store on Object under an application (or
+internal component) specified key. There are no restrictions on the key
+or the value. The value for a key may be set at any time - it is not required
+that this be set before init() is called.
+</p>
+
+<p>
+Internal components can access the key-value pairs if they have access to the
+object via the <code>RuntimeServices</code> interface, using the method
+</p>
+
+<source>
+<![CDATA[
+ public Object getApplicationAttribute( Object key );
+]]>
+</source>
+
+<p>
+Note that internal components cannot set the value of the key, just get it.
+if the internal component must communicate information to the application layer,
+it must do so via the Object passed as the value.
+</p>
+</section>
<section name="EventCartridge and Event Handlers">
@@ -2224,6 +2285,8 @@
</section>
<section name="Configuring Resource Loaders">
+
+<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
<p>
One of the fundamental and important parts about Velocity is the resource
@@ -2459,7 +2522,60 @@
Note that while all three require very little configuration information
for proper operation, the ClasspathResourceLoader is the simplest.
</p>
-
+
+
+<a name="Resource Manager and Cache"></a>
+<strong>Pluggable Resource Manager and Resource Cache</strong>
+
+<p>
+The Resource Manager is the main part of the resource (template and static content)
+management system, and is responsible for taking application requests for
+templates, finding them in the available resource loaders, and then optionally
+caching the parsed template. The Resource Cache is the mechanism that the
+Resource Manager uses to cache templates for quick reuse. While the default
+versions of these two facilities are suitable for most
+applications, for advanced users it now is possible
+to replace the default resource manager
+and resource cache with custom implementations.
+</p>
+
+<p>
+A resource manager implementation must implement the
+<code>org.apache.velocity.runtime.resource.ResourceManager</code> interface.
+A description of the requirements of a resource manager is out of scope for
+this document. Implementors are encouraged to review the default implementation.
+To configure Velocity to load the replacement implementation, use the
+configuration key :
+</p>
+
+<source><![CDATA[
+resource.manager.class
+]]></source>
+
+<p>
+This key is also defined as a contstant
+<code>RuntimeConstants.RESOURCE_MANAGER_CLASS</code>
+</p>
+
+<p>
+A resource cache implementation must implement the
+<code>org.apache.velocity.runtime.resource.ResourceCache</code> interface
+As with the resource manager, a description of the requirements of a
+resource manager is out of scope for
+this document. Implementors are encouraged to review the default implementation.
+To configure Velocity to load the replacement implementation, use the
+configuration key :
+</p>
+
+<source><![CDATA[
+resource.manager.cache.class
+]]></source>
+
+<p>
+This key is also defined as a contstant
+<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_CLASS</code>
+</p>
+
</section>
<section name="Template Encoding for Internationalization">
1.93 +182 -1 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.92
retrieving revision 1.93
diff -u -r1.92 -r1.93
--- developer-guide.html 14 Mar 2002 13:36:37 -0000 1.92
+++ developer-guide.html 15 Mar 2002 04:26:38 -0000 1.93
@@ -190,6 +190,10 @@
</li>
<li>
+ <a href="developer-guide.html#Application Attributes">Application Attributes</a>
+</li>
+
+<li>
<a href="developer-guide.html#EventCartridge and Event Handlers">EventCartridge and
Event Handlers</a>
</li>
@@ -213,8 +217,14 @@
<a href="developer-guide.html#Configuring Resource Loaders">Configuring the
Resource Loaders (template loaders)</a>
<ul>
<li>
+ <a href="developer-guide.html#Resource Loaders">Resource Loaders</a>
+ </li>
+ <li>
<a href="developer-guide.html#Configuration Examples">Configuration Examples</a>
</li>
+ <li>
+ <a href="developer-guide.html#Resource Manager and Cache">Pluggable Resource
Manager and Resource Cache</a>
+ </li>
</ul>
</li>
@@ -1945,6 +1955,96 @@
<table border="0" cellspacing="0"
cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
+ <a name="Application Attributes"><strong>Application
Attributes</strong></a>
+ </font>
+ </td></tr>
+ <tr><td>
+ <blockquote>
+ <p>
+<i>Application Attributes</i> are name-value pairs that can be associated with
+a RuntimeInstance (either via the <code>VelocityEngine</code> or
+the <code>Velocity</code> singleton) and accessed from any part of the Velocity
+engine that has access to the RuntimeInstance.
+</p>
+ <p>
+This feature was designed for applications that need to communicate between
+the application layer and custom parts of the Velocity engine, such as
+loggers, resource loaders, resource managers, etc.
+</p>
+ <p>
+The Application Attribute API is very simple. From the application layer, there
+is a method of the <code>VelocityEngine</code> and the <code>Velocity</code>
+classes :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+ public void setApplicationAttribute( Object key, Object value );
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+through which an application can store on Object under an application (or
+internal component) specified key. There are no restrictions on the key
+or the value. The value for a key may be set at any time - it is not required
+that this be set before init() is called.
+</p>
+ <p>
+Internal components can access the key-value pairs if they have access to the
+object via the <code>RuntimeServices</code> interface, using the method
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+
+ public Object getApplicationAttribute( Object key );
+
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+Note that internal components cannot set the value of the key, just get it.
+if the internal component must communicate information to the application layer,
+it must do so via the Object passed as the value.
+</p>
+ </blockquote>
+ </p>
+ </td></tr>
+ <tr><td><br/></td></tr>
+ </table>
+ <table border="0" cellspacing="0"
cellpadding="2" width="100%">
+ <tr><td bgcolor="#525D76">
+ <font color="#ffffff" face="arial,helvetica,sanserif">
<a name="EventCartridge and Event Handlers"><strong>EventCartridge and
Event Handlers</strong></a>
</font>
</td></tr>
@@ -2670,7 +2770,8 @@
</td></tr>
<tr><td>
<blockquote>
- <p>
+ <a name="Resource Loaders"><strong>Resource
Loaders</strong></a>
+ <p>
One of the fundamental and important parts about Velocity is the resource
management system and the resource loaders. They are referred to as 'resources'
here rather than 'templates' because the resource management system will also
@@ -2990,6 +3091,86 @@
<p>
Note that while all three require very little configuration information
for proper operation, the ClasspathResourceLoader is the simplest.
+</p>
+ <a name="Resource Manager and
Cache" />
+ <strong>Pluggable Resource Manager
and Resource Cache</strong>
+ <p>
+The Resource Manager is the main part of the resource (template and static content)
+management system, and is responsible for taking application requests for
+templates, finding them in the available resource loaders, and then optionally
+caching the parsed template. The Resource Cache is the mechanism that the
+Resource Manager uses to cache templates for quick reuse. While the default
+versions of these two facilities are suitable for most
+applications, for advanced users it now is possible
+to replace the default resource manager
+and resource cache with custom implementations.
+</p>
+ <p>
+A resource manager implementation must implement the
+<code>org.apache.velocity.runtime.resource.ResourceManager</code> interface.
+A description of the requirements of a resource manager is out of scope for
+this document. Implementors are encouraged to review the default implementation.
+To configure Velocity to load the replacement implementation, use the
+configuration key :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+resource.manager.class
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+This key is also defined as a contstant
+<code>RuntimeConstants.RESOURCE_MANAGER_CLASS</code>
+</p>
+ <p>
+A resource cache implementation must implement the
+<code>org.apache.velocity.runtime.resource.ResourceCache</code> interface
+As with the resource manager, a description of the requirements of a
+resource manager is out of scope for
+this document. Implementors are encouraged to review the default implementation.
+To configure Velocity to load the replacement implementation, use the
+configuration key :
+</p>
+ <div align="left">
+ <table cellspacing="4" cellpadding="0" border="0">
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#ffffff"><pre>
+resource.manager.cache.class
+</pre></td>
+ <td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ <tr>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1"
height="1" vspace="0" hspace="0" border="0"/></td>
+ <td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif"
width="1" height="1" vspace="0" hspace="0" border="0"/></td>
+ </tr>
+ </table>
+ </div>
+ <p>
+This key is also defined as a contstant
+<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_CLASS</code>
</p>
</blockquote>
</p>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
