You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by ge...@apache.org on 2003/10/23 15:49:28 UTC
cvs commit: jakarta-velocity/docs developer-guide.html
geirm 2003/10/23 06:49:28
Modified: xdocs developer-guide.xml
docs developer-guide.html
Log:
update : noted Dan's changes to resource caching, describing the two
parameters, and also noted changes to the log4j logging
Revision Changes Path
1.71 +256 -232 jakarta-velocity/xdocs/developer-guide.xml
Index: developer-guide.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
retrieving revision 1.70
retrieving revision 1.71
diff -u -r1.70 -r1.71
--- developer-guide.xml 22 Oct 2003 03:00:46 -0000 1.70
+++ developer-guide.xml 23 Oct 2003 13:49:28 -0000 1.71
@@ -63,10 +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>
+ <a href="developer-guide.html#Application Attributes">Application Attributes</a>
</li>
<li>
@@ -79,9 +79,9 @@
<li>
<a href="developer-guide.html#Configuring the Log System">Configuring the Log System</a>
- <ul>
- <li>
- <a href="developer-guide.html#Using Log4j With Existing Category">Using Log4j With Existing Category</a>
+ <ul>
+ <li>
+ <a href="developer-guide.html#Using Log4j With Existing Category">Using Log4j With Existing Category</a>
</li>
<li>
<a href="developer-guide.html#Simple Example of a Custom Logger">Simple Example of a Custom Logger</a>
@@ -92,15 +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#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>
+ <li>
+ <a href="developer-guide.html#Resource Manager and Cache">Pluggable Resource Manager and Resource Cache</a>
+ </li>
</ul>
</li>
@@ -1551,57 +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="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">
@@ -1904,6 +1904,21 @@
</p>
<p>
+<code>resource.manager.cache.class</code> Declares the class to be used
+for resource caching. The current default is
+<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
+which uses a LRU Map to prevent data from being held forever. You can
+set the size of the LRU Map using the parameter
+<code>resource.manager.defaultcache.size</code>. The dafault value
+of the default cache size is currently 89.
+</p>
+
+<p>
+<code>resource.manager.defaultcache.size</code> Sets the size of the
+ default implementation of the resource manager resource cache.
+</p>
+
+<p>
<code>resource.loader = <name> (default = File)</code><br/>
<i>Multi-valued key. Will accept CSV for value.</i> Pulic name of a
resource loader to be used. This public name will then be used
@@ -2062,20 +2077,20 @@
exceptional condition. If you see a log message, please
increment this property.
</p>
-
-<p>
-<strong>Pluggable Introspection</strong>
-</p>
-
-<p>
-<code>runtime.introspector.uberspect =
-org.apache.velocity.util.introspection.UberspectImpl</code>
-<br/>
-This property sets the 'Uberspector', the introspection package that
-handles all introspection strategies for Velocity. The default works just
-fine, so only replace if you have something really interesting and special
-to do.
-</p>
+
+<p>
+<strong>Pluggable Introspection</strong>
+</p>
+
+<p>
+<code>runtime.introspector.uberspect =
+org.apache.velocity.util.introspection.UberspectImpl</code>
+<br/>
+This property sets the 'Uberspector', the introspection package that
+handles all introspection strategies for Velocity. The default works just
+fine, so only replace if you have something really interesting and special
+to do.
+</p>
</section>
@@ -2118,29 +2133,38 @@
directory. See the note above regarding automatic detection of
Logkit or Log4j to use as the default logging system.
</li>
-
-<li>
-<b>Existing Log4j Category</b><br/>
-Starting with version 1.3, Velocity will log it's output to an existing
-Log4j Category setup elsewhere in the application. To use this feature
-you must
- <ol>
- <li>
- Make sure that the Log4j jar is in your classpath. (You would do this
- anyway since you are using Log4j in the application using Velocity.)
- </li>
- <li>
- Configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
- </li>
- <li>
- Specify the name of the existing Category to use via the
- 'runtime.log.logsystem.log4j.category' property.
- </li>
- </ol>
-
-This approach replaces and deprecates the older <code>Log4JLogSystem</code>
-class. To see how this is done in code, see the example below.
-</li>
+
+<li>
+<b>Existing Log4j Logger/Category</b><br/>
+Starting with version 1.3, Velocity will log it's output to an existing
+Log4j Category setup elsewhere in the application. With version 1.5, we have
+switched to using the Logger class, as the Categeory class is now deprecated
+in Log4j. To use this feature you must
+ <ol>
+ <li>
+ Make sure that the Log4j jar is in your classpath. (You would do this
+ anyway since you are using Log4j in the application using Velocity.)
+ </li>
+ <li>
+ a) If your system still uses the deprecated Category,
+ configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
+ b) If your environment uses the Logger class,
+ cconfigure Velocity to use the <code>Log4JLogSystem</code> class.
+ </li>
+ <li>
+ a) If using a Category, specify the name of the existing Category to use via the
+ 'runtime.log.logsystem.log4j.category' property.
+ b) If using a Logger, specify the name of the existing Logger to use via the
+ 'runtime.log.logsystem.log4j.logger' property.
+ </li>
+ </ol>
+
+Note that this support for Logger is in version 1.5 of Velocity. Further,
+in version 1.5 we removed the now-ancient and very deprecated origianl
+Log4JLogSystem class and replaced with the current Log4JLogSystem class which
+uses the Logger class. We apologize for the confusion, but we needed to move
+on.
+</li>
<li>
<b>Custom Standalone Logger</b><br/>
@@ -2180,68 +2204,68 @@
</ul>
-<a name="Using Log4j With Existing Category"><strong>Using Log4j With Existing Category</strong></a>
-
-<p>
-Here is an example of how to configure Velocity to log to an existing Log4j
-Category.
-</p>
-
-<source><![CDATA[
-import org.apache.velocity.app.VelocityEngine;
-import org.apache.velocity.runtime.RuntimeConstants;
-
-import org.apache.log4j.Category;
-import org.apache.log4j.BasicConfigurator;
-
-public class Log4jCategoryExample
-{
- public static String CATEGORY_NAME = "velexample";
-
- public static void main( String args[] )
- throws Exception
- {
- /*
- * configure log4j to log to console
- */
-
- BasicConfigurator.configure();
-
- Category log = Category.getInstance( CATEGORY_NAME );
-
- log.info("Hello from Log4jCategoryExample - ready to start velocity");
-
- /*
- * now create a new VelocityEngine instance, and
- * configure it to use the category
- */
-
- VelocityEngine ve = new VelocityEngine();
-
- ve.setProperty( RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
- "org.apache.velocity.runtime.log.SimpleLog4JLogSystem" );
-
- ve.setProperty("runtime.log.logsystem.log4j.category", CATEGORY_NAME);
-
- ve.init();
-
- log.info("this should follow the initialization output from velocity");
- }
-}
-]]></source>
-
-<p>
-Note that the above example can be found in <code>examples/logger_example</code>.
-</p>
-
+<a name="Using Log4j With Existing Category"><strong>Using Log4j With Existing Category</strong></a>
+
+<p>
+Here is an example of how to configure Velocity to log to an existing Log4j
+Category.
+</p>
+
+<source><![CDATA[
+import org.apache.velocity.app.VelocityEngine;
+import org.apache.velocity.runtime.RuntimeConstants;
+
+import org.apache.log4j.Category;
+import org.apache.log4j.BasicConfigurator;
+
+public class Log4jCategoryExample
+{
+ public static String CATEGORY_NAME = "velexample";
+
+ public static void main( String args[] )
+ throws Exception
+ {
+ /*
+ * configure log4j to log to console
+ */
+
+ BasicConfigurator.configure();
+
+ Category log = Category.getInstance( CATEGORY_NAME );
+
+ log.info("Hello from Log4jCategoryExample - ready to start velocity");
+
+ /*
+ * now create a new VelocityEngine instance, and
+ * configure it to use the category
+ */
+
+ VelocityEngine ve = new VelocityEngine();
+
+ ve.setProperty( RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
+ "org.apache.velocity.runtime.log.SimpleLog4JLogSystem" );
+
+ ve.setProperty("runtime.log.logsystem.log4j.category", CATEGORY_NAME);
+
+ ve.init();
+
+ log.info("this should follow the initialization output from velocity");
+ }
+}
+]]></source>
+
+<p>
+Note that the above example can be found in <code>examples/logger_example</code>.
+</p>
+
<a name="Simple Example of a Custom Logger"><strong>Simple Example of a Custom Logger</strong></a>
<p>
-Here is an example of how to use an instantiation of your class that implements
-Velocity's logging system as the logger. Note that we are not passing the name
-of the class to use, but rather a living, existing instantiation of the class
-to be used. All that is required is that it support the
-<code>LogSystem</code> interface.
+Here is an example of how to use an instantiation of your class that implements
+Velocity's logging system as the logger. Note that we are not passing the name
+of the class to use, but rather a living, existing instantiation of the class
+to be used. All that is required is that it support the
+<code>LogSystem</code> interface.
</p>
@@ -2299,8 +2323,8 @@
</section>
<section name="Configuring Resource Loaders">
-
-<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
+
+<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
<p>
One of the fundamental and important parts about Velocity is the resource
@@ -2536,76 +2560,76 @@
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>
-
-<p>
-A resource cache implementation may want to limit the cache size
-(rather than providing an unbounded cache which could consume all
-available memory). To configure Velocity to set the size for your
-cache, use the configuration key:
-</p>
-
-<source><![CDATA[
-resource.manager.cache.size
-]]></source>
-
-<p>
-This key is also defined as a contstant
-<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
-</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>
+
+<p>
+A resource cache implementation may want to limit the cache size
+(rather than providing an unbounded cache which could consume all
+available memory). To configure Velocity to set the size for your
+cache, use the configuration key:
+</p>
+
+<source><![CDATA[
+resource.manager.cache.size
+]]></source>
+
+<p>
+This key is also defined as a contstant
+<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
+</p>
+
</section>
<section name="Template Encoding for Internationalization">
1.104 +29 -7 jakarta-velocity/docs/developer-guide.html
Index: developer-guide.html
===================================================================
RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
retrieving revision 1.103
retrieving revision 1.104
diff -u -r1.103 -r1.104
--- developer-guide.html 22 Oct 2003 03:00:46 -0000 1.103
+++ developer-guide.html 23 Oct 2003 13:49:28 -0000 1.104
@@ -2358,6 +2358,19 @@
runtime log.
</p>
<p>
+<code>resource.manager.cache.class</code> Declares the class to be used
+for resource caching. The current default is
+<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
+which uses a LRU Map to prevent data from being held forever. You can
+set the size of the LRU Map using the parameter
+<code>resource.manager.defaultcache.size</code>. The dafault value
+of the default cache size is currently 89.
+</p>
+ <p>
+<code>resource.manager.defaultcache.size</code> Sets the size of the
+ default implementation of the resource manager resource cache.
+</p>
+ <p>
<code>resource.loader = <name> (default = File)</code><br />
<i>Multi-valued key. Will accept CSV for value.</i> Pulic name of a
resource loader to be used. This public name will then be used
@@ -2576,26 +2589,35 @@
</li>
<li>
-<b>Existing Log4j Category</b><br />
+<b>Existing Log4j Logger/Category</b><br />
Starting with version 1.3, Velocity will log it's output to an existing
-Log4j Category setup elsewhere in the application. To use this feature
-you must
+Log4j Category setup elsewhere in the application. With version 1.5, we have
+switched to using the Logger class, as the Categeory class is now deprecated
+in Log4j. To use this feature you must
<ol>
<li>
Make sure that the Log4j jar is in your classpath. (You would do this
anyway since you are using Log4j in the application using Velocity.)
</li>
<li>
- Configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
+ a) If your system still uses the deprecated Category,
+ configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
+ b) If your environment uses the Logger class,
+ cconfigure Velocity to use the <code>Log4JLogSystem</code> class.
</li>
<li>
- Specify the name of the existing Category to use via the
+ a) If using a Category, specify the name of the existing Category to use via the
'runtime.log.logsystem.log4j.category' property.
+ b) If using a Logger, specify the name of the existing Logger to use via the
+ 'runtime.log.logsystem.log4j.logger' property.
</li>
</ol>
-This approach replaces and deprecates the older <code>Log4JLogSystem</code>
-class. To see how this is done in code, see the example below.
+Note that this support for Logger is in version 1.5 of Velocity. Further,
+in version 1.5 we removed the now-ancient and very deprecated origianl
+Log4JLogSystem class and replaced with the current Log4JLogSystem class which
+uses the Logger class. We apologize for the confusion, but we needed to move
+on.
</li>
<li>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: cvs commit: jakarta-velocity/docs developer-guide.html
Posted by "Geir Magnusson Jr." <ge...@optonline.net>.
Yes, and I think we should chuck 'cache.size', as it doesn't affect the
cache in general, just the default impl, right?
On Thursday, October 23, 2003, at 11:44 AM, Daniel L. Rall wrote:
> I'd already documented the resource.manager.cache.size property. It's
> now in here twice with two different names (cache.size vs.
> defaulcache.size).
>
> geirm@apache.org wrote:
>> geirm 2003/10/23 06:49:28
>> Modified: xdocs developer-guide.xml
>> docs developer-guide.html
>> Log:
>> update : noted Dan's changes to resource caching, describing the two
>> parameters, and also noted changes to the log4j logging
>> Revision Changes Path
>> 1.71 +256 -232 jakarta-velocity/xdocs/developer-guide.xml
>> Index: developer-guide.xml
>> ===================================================================
>> RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
>> retrieving revision 1.70
>> retrieving revision 1.71
>> diff -u -r1.70 -r1.71
>> --- developer-guide.xml 22 Oct 2003 03:00:46 -0000 1.70
>> +++ developer-guide.xml 23 Oct 2003 13:49:28 -0000 1.71
>> @@ -63,10 +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>
>> + <a href="developer-guide.html#Application
>> Attributes">Application Attributes</a>
>> </li>
>> <li>
>> @@ -79,9 +79,9 @@
>> <li>
>> <a href="developer-guide.html#Configuring the Log
>> System">Configuring the Log System</a>
>> - <ul>
>> - <li>
>> - <a href="developer-guide.html#Using Log4j With Existing
>> Category">Using Log4j With Existing Category</a>
>> + <ul>
>> + <li>
>> + <a href="developer-guide.html#Using Log4j With Existing
>> Category">Using Log4j With Existing Category</a>
>> </li>
>> <li>
>> <a href="developer-guide.html#Simple Example of a Custom
>> Logger">Simple Example of a Custom Logger</a>
>> @@ -92,15 +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#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>
>> + <li>
>> + <a href="developer-guide.html#Resource Manager and
>> Cache">Pluggable Resource Manager and Resource Cache</a>
>> + </li>
>> </ul>
>> </li>
>> @@ -1551,57 +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="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">
>> @@ -1904,6 +1904,21 @@
>> </p>
>> <p>
>> +<code>resource.manager.cache.class</code> Declares the class to
>> be used
>> +for resource caching. The current default is
>> +<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
>> +which uses a LRU Map to prevent data from being held forever. You
>> can
>> +set the size of the LRU Map using the parameter
>> +<code>resource.manager.defaultcache.size</code>. The dafault value
>> +of the default cache size is currently 89.
>> +</p>
>> +
>> +<p>
>> +<code>resource.manager.defaultcache.size</code> Sets the size of
>> the
>> + default implementation of the resource manager resource cache.
>> +</p>
>> +
>> +<p>
>> <code>resource.loader = <name> (default = File)</code><br/>
>> <i>Multi-valued key. Will accept CSV for value.</i> Pulic name
>> of a
>> resource loader to be used. This public name will then be used
>> @@ -2062,20 +2077,20 @@
>> exceptional condition. If you see a log message, please
>> increment this property.
>> </p>
>> -
>> -<p>
>> -<strong>Pluggable Introspection</strong>
>> -</p>
>> -
>> -<p>
>> -<code>runtime.introspector.uberspect =
>> -org.apache.velocity.util.introspection.UberspectImpl</code>
>> -<br/>
>> -This property sets the 'Uberspector', the introspection package
>> that
>> -handles all introspection strategies for Velocity. The default
>> works just
>> -fine, so only replace if you have something really interesting and
>> special
>> -to do.
>> -</p>
>> +
>> +<p>
>> +<strong>Pluggable Introspection</strong>
>> +</p>
>> +
>> +<p>
>> +<code>runtime.introspector.uberspect =
>> +org.apache.velocity.util.introspection.UberspectImpl</code>
>> +<br/>
>> +This property sets the 'Uberspector', the introspection package
>> that
>> +handles all introspection strategies for Velocity. The default
>> works just
>> +fine, so only replace if you have something really interesting and
>> special
>> +to do.
>> +</p>
>> </section>
>> @@ -2118,29 +2133,38 @@
>> directory. See the note above regarding automatic detection of
>> Logkit or Log4j to use as the default logging system.
>> </li>
>> -
>> -<li>
>> -<b>Existing Log4j Category</b><br/>
>> -Starting with version 1.3, Velocity will log it's output to an
>> existing
>> -Log4j Category setup elsewhere in the application. To use this
>> feature
>> -you must
>> - <ol>
>> - <li>
>> - Make sure that the Log4j jar is in your classpath. (You would
>> do this
>> - anyway since you are using Log4j in the application using
>> Velocity.)
>> - </li>
>> - <li>
>> - Configure Velocity to use the
>> <code>SimpleLog4JLogSystem</code> class.
>> - </li>
>> - <li>
>> - Specify the name of the existing Category to use via the
>> - 'runtime.log.logsystem.log4j.category' property.
>> - </li>
>> - </ol>
>> -
>> -This approach replaces and deprecates the older
>> <code>Log4JLogSystem</code>
>> -class. To see how this is done in code, see the example below.
>> -</li>
>> +
>> +<li>
>> +<b>Existing Log4j Logger/Category</b><br/>
>> +Starting with version 1.3, Velocity will log it's output to an
>> existing
>> +Log4j Category setup elsewhere in the application. With version
>> 1.5, we have
>> +switched to using the Logger class, as the Categeory class is now
>> deprecated
>> +in Log4j. To use this feature you must
>> + <ol>
>> + <li>
>> + Make sure that the Log4j jar is in your classpath. (You would
>> do this
>> + anyway since you are using Log4j in the application using
>> Velocity.)
>> + </li>
>> + <li>
>> + a) If your system still uses the deprecated Category,
>> + configure Velocity to use the
>> <code>SimpleLog4JLogSystem</code> class.
>> + b) If your environment uses the Logger class,
>> + cconfigure Velocity to use the <code>Log4JLogSystem</code>
>> class.
>> + </li>
>> + <li>
>> + a) If using a Category, specify the name of the existing
>> Category to use via the
>> + 'runtime.log.logsystem.log4j.category' property.
>> + b) If using a Logger, specify the name of the existing Logger
>> to use via the
>> + 'runtime.log.logsystem.log4j.logger' property.
>> + </li>
>> + </ol>
>> +
>> +Note that this support for Logger is in version 1.5 of Velocity.
>> Further,
>> +in version 1.5 we removed the now-ancient and very deprecated
>> origianl
>> +Log4JLogSystem class and replaced with the current Log4JLogSystem
>> class which
>> +uses the Logger class. We apologize for the confusion, but we
>> needed to move
>> +on.
>> +</li>
>> <li>
>> <b>Custom Standalone Logger</b><br/>
>> @@ -2180,68 +2204,68 @@
>> </ul>
>> -<a name="Using Log4j With Existing Category"><strong>Using
>> Log4j With Existing Category</strong></a>
>> -
>> -<p>
>> -Here is an example of how to configure Velocity to log to an
>> existing Log4j
>> -Category.
>> -</p>
>> -
>> -<source><![CDATA[
>> -import org.apache.velocity.app.VelocityEngine;
>> -import org.apache.velocity.runtime.RuntimeConstants;
>> -
>> -import org.apache.log4j.Category;
>> -import org.apache.log4j.BasicConfigurator;
>> -
>> -public class Log4jCategoryExample
>> -{
>> - public static String CATEGORY_NAME = "velexample";
>> -
>> - public static void main( String args[] )
>> - throws Exception
>> - {
>> - /*
>> - * configure log4j to log to console
>> - */
>> -
>> - BasicConfigurator.configure();
>> -
>> - Category log = Category.getInstance( CATEGORY_NAME );
>> -
>> - log.info("Hello from Log4jCategoryExample - ready to start
>> velocity");
>> -
>> - /*
>> - * now create a new VelocityEngine instance, and
>> - * configure it to use the category
>> - */
>> -
>> - VelocityEngine ve = new VelocityEngine();
>> -
>> - ve.setProperty(
>> RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
>> - "org.apache.velocity.runtime.log.SimpleLog4JLogSystem"
>> );
>> -
>> - ve.setProperty("runtime.log.logsystem.log4j.category",
>> CATEGORY_NAME);
>> -
>> - ve.init();
>> -
>> - log.info("this should follow the initialization output
>> from velocity");
>> - }
>> -}
>> -]]></source>
>> -
>> -<p>
>> -Note that the above example can be found in
>> <code>examples/logger_example</code>.
>> -</p>
>> -
>> +<a name="Using Log4j With Existing Category"><strong>Using Log4j
>> With Existing Category</strong></a>
>> +
>> +<p>
>> +Here is an example of how to configure Velocity to log to an
>> existing Log4j
>> +Category.
>> +</p>
>> +
>> +<source><![CDATA[
>> +import org.apache.velocity.app.VelocityEngine;
>> +import org.apache.velocity.runtime.RuntimeConstants;
>> +
>> +import org.apache.log4j.Category;
>> +import org.apache.log4j.BasicConfigurator;
>> +
>> +public class Log4jCategoryExample
>> +{
>> + public static String CATEGORY_NAME = "velexample";
>> +
>> + public static void main( String args[] )
>> + throws Exception
>> + {
>> + /*
>> + * configure log4j to log to console
>> + */
>> +
>> + BasicConfigurator.configure();
>> +
>> + Category log = Category.getInstance( CATEGORY_NAME );
>> +
>> + log.info("Hello from Log4jCategoryExample - ready to start
>> velocity");
>> +
>> + /*
>> + * now create a new VelocityEngine instance, and
>> + * configure it to use the category
>> + */
>> +
>> + VelocityEngine ve = new VelocityEngine();
>> +
>> + ve.setProperty(
>> RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
>> + "org.apache.velocity.runtime.log.SimpleLog4JLogSystem"
>> );
>> +
>> + ve.setProperty("runtime.log.logsystem.log4j.category",
>> CATEGORY_NAME);
>> +
>> + ve.init();
>> +
>> + log.info("this should follow the initialization output
>> from velocity");
>> + }
>> +}
>> +]]></source>
>> +
>> +<p>
>> +Note that the above example can be found in
>> <code>examples/logger_example</code>.
>> +</p>
>> +
>> <a name="Simple Example of a Custom Logger"><strong>Simple Example
>> of a Custom Logger</strong></a>
>> <p>
>> -Here is an example of how to use an instantiation of your class
>> that implements
>> -Velocity's logging system as the logger. Note that we are not
>> passing the name
>> -of the class to use, but rather a living, existing instantiation
>> of the class
>> -to be used. All that is required is that it support the
>> -<code>LogSystem</code> interface.
>> +Here is an example of how to use an instantiation of your class
>> that implements
>> +Velocity's logging system as the logger. Note that we are not
>> passing the name
>> +of the class to use, but rather a living, existing instantiation
>> of the class
>> +to be used. All that is required is that it support the
>> +<code>LogSystem</code> interface.
>> </p>
>> @@ -2299,8 +2323,8 @@
>> </section>
>> <section name="Configuring Resource Loaders">
>> -
>> -<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
>> +
>> +<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
>> <p>
>> One of the fundamental and important parts about Velocity is the
>> resource
>> @@ -2536,76 +2560,76 @@
>> 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>
>> -
>> -<p>
>> -A resource cache implementation may want to limit the cache size
>> -(rather than providing an unbounded cache which could consume all
>> -available memory). To configure Velocity to set the size for your
>> -cache, use the configuration key:
>> -</p>
>> -
>> -<source><![CDATA[
>> -resource.manager.cache.size
>> -]]></source>
>> -
>> -<p>
>> -This key is also defined as a contstant
>> -<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
>> -</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>
>> +
>> +<p>
>> +A resource cache implementation may want to limit the cache size
>> +(rather than providing an unbounded cache which could consume all
>> +available memory). To configure Velocity to set the size for your
>> +cache, use the configuration key:
>> +</p>
>> +
>> +<source><![CDATA[
>> +resource.manager.cache.size
>> +]]></source>
>> +
>> +<p>
>> +This key is also defined as a contstant
>> +<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
>> +</p>
>> +
>> </section>
>> <section name="Template Encoding for Internationalization">
>> 1.104 +29 -7
>> jakarta-velocity/docs/developer-guide.html
>> Index: developer-guide.html
>> ===================================================================
>> RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
>> retrieving revision 1.103
>> retrieving revision 1.104
>> diff -u -r1.103 -r1.104
>> --- developer-guide.html 22 Oct 2003 03:00:46 -0000 1.103
>> +++ developer-guide.html 23 Oct 2003 13:49:28 -0000 1.104
>> @@ -2358,6 +2358,19 @@
>> runtime log.
>> </p>
>> <p>
>> +<code>resource.manager.cache.class</code> Declares the class to
>> be used
>> +for resource caching. The current default is
>> +<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
>> +which uses a LRU Map to prevent data from being held forever. You
>> can
>> +set the size of the LRU Map using the parameter
>> +<code>resource.manager.defaultcache.size</code>. The dafault value
>> +of the default cache size is currently 89.
>> +</p>
>> + <p>
>> +<code>resource.manager.defaultcache.size</code> Sets the size of
>> the
>> + default implementation of the resource manager resource cache.
>> +</p>
>> + <p>
>> <code>resource.loader = <name> (default = File)</code><br />
>> <i>Multi-valued key. Will accept CSV for value.</i> Pulic name
>> of a
>> resource loader to be used. This public name will then be used
>> @@ -2576,26 +2589,35 @@
>> </li>
>> <li>
>> -<b>Existing Log4j Category</b><br />
>> +<b>Existing Log4j Logger/Category</b><br />
>> Starting with version 1.3, Velocity will log it's output to an
>> existing
>> -Log4j Category setup elsewhere in the application. To use this
>> feature
>> -you must
>> +Log4j Category setup elsewhere in the application. With version
>> 1.5, we have
>> +switched to using the Logger class, as the Categeory class is now
>> deprecated
>> +in Log4j. To use this feature you must
>> <ol>
>> <li>
>> Make sure that the Log4j jar is in your classpath. (You would
>> do this
>> anyway since you are using Log4j in the application using
>> Velocity.)
>> </li>
>> <li>
>> - Configure Velocity to use the
>> <code>SimpleLog4JLogSystem</code> class.
>> + a) If your system still uses the deprecated Category,
>> + configure Velocity to use the
>> <code>SimpleLog4JLogSystem</code> class.
>> + b) If your environment uses the Logger class,
>> + cconfigure Velocity to use the <code>Log4JLogSystem</code>
>> class.
>> </li>
>> <li>
>> - Specify the name of the existing Category to use via the
>> + a) If using a Category, specify the name of the existing
>> Category to use via the
>> 'runtime.log.logsystem.log4j.category' property.
>> + b) If using a Logger, specify the name of the existing Logger
>> to use via the
>> + 'runtime.log.logsystem.log4j.logger' property.
>> </li>
>> </ol>
>> -This approach replaces and deprecates the older
>> <code>Log4JLogSystem</code>
>> -class. To see how this is done in code, see the example below.
>> +Note that this support for Logger is in version 1.5 of Velocity.
>> Further,
>> +in version 1.5 we removed the now-ancient and very deprecated
>> origianl
>> +Log4JLogSystem class and replaced with the current Log4JLogSystem
>> class which
>> +uses the Logger class. We apologize for the confusion, but we
>> needed to move
>> +on.
>> </li>
>> <li>
>
>
>
--
Geir Magnusson Jr 203-247-1713(m)
geirm@optonline.net
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: cvs commit: jakarta-velocity/docs developer-guide.html
Posted by "Daniel L. Rall" <dl...@finemaltcoding.com>.
I'd already documented the resource.manager.cache.size property. It's now in
here twice with two different names (cache.size vs. defaulcache.size).
geirm@apache.org wrote:
> geirm 2003/10/23 06:49:28
>
> Modified: xdocs developer-guide.xml
> docs developer-guide.html
> Log:
> update : noted Dan's changes to resource caching, describing the two
> parameters, and also noted changes to the log4j logging
>
> Revision Changes Path
> 1.71 +256 -232 jakarta-velocity/xdocs/developer-guide.xml
>
> Index: developer-guide.xml
> ===================================================================
> RCS file: /home/cvs/jakarta-velocity/xdocs/developer-guide.xml,v
> retrieving revision 1.70
> retrieving revision 1.71
> diff -u -r1.70 -r1.71
> --- developer-guide.xml 22 Oct 2003 03:00:46 -0000 1.70
> +++ developer-guide.xml 23 Oct 2003 13:49:28 -0000 1.71
> @@ -63,10 +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>
> + <a href="developer-guide.html#Application Attributes">Application Attributes</a>
> </li>
>
> <li>
> @@ -79,9 +79,9 @@
>
> <li>
> <a href="developer-guide.html#Configuring the Log System">Configuring the Log System</a>
> - <ul>
> - <li>
> - <a href="developer-guide.html#Using Log4j With Existing Category">Using Log4j With Existing Category</a>
> + <ul>
> + <li>
> + <a href="developer-guide.html#Using Log4j With Existing Category">Using Log4j With Existing Category</a>
> </li>
> <li>
> <a href="developer-guide.html#Simple Example of a Custom Logger">Simple Example of a Custom Logger</a>
> @@ -92,15 +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#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>
> + <li>
> + <a href="developer-guide.html#Resource Manager and Cache">Pluggable Resource Manager and Resource Cache</a>
> + </li>
> </ul>
> </li>
>
> @@ -1551,57 +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="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">
>
> @@ -1904,6 +1904,21 @@
> </p>
>
> <p>
> +<code>resource.manager.cache.class</code> Declares the class to be used
> +for resource caching. The current default is
> +<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
> +which uses a LRU Map to prevent data from being held forever. You can
> +set the size of the LRU Map using the parameter
> +<code>resource.manager.defaultcache.size</code>. The dafault value
> +of the default cache size is currently 89.
> +</p>
> +
> +<p>
> +<code>resource.manager.defaultcache.size</code> Sets the size of the
> + default implementation of the resource manager resource cache.
> +</p>
> +
> +<p>
> <code>resource.loader = <name> (default = File)</code><br/>
> <i>Multi-valued key. Will accept CSV for value.</i> Pulic name of a
> resource loader to be used. This public name will then be used
> @@ -2062,20 +2077,20 @@
> exceptional condition. If you see a log message, please
> increment this property.
> </p>
> -
> -<p>
> -<strong>Pluggable Introspection</strong>
> -</p>
> -
> -<p>
> -<code>runtime.introspector.uberspect =
> -org.apache.velocity.util.introspection.UberspectImpl</code>
> -<br/>
> -This property sets the 'Uberspector', the introspection package that
> -handles all introspection strategies for Velocity. The default works just
> -fine, so only replace if you have something really interesting and special
> -to do.
> -</p>
> +
> +<p>
> +<strong>Pluggable Introspection</strong>
> +</p>
> +
> +<p>
> +<code>runtime.introspector.uberspect =
> +org.apache.velocity.util.introspection.UberspectImpl</code>
> +<br/>
> +This property sets the 'Uberspector', the introspection package that
> +handles all introspection strategies for Velocity. The default works just
> +fine, so only replace if you have something really interesting and special
> +to do.
> +</p>
>
> </section>
>
> @@ -2118,29 +2133,38 @@
> directory. See the note above regarding automatic detection of
> Logkit or Log4j to use as the default logging system.
> </li>
> -
> -<li>
> -<b>Existing Log4j Category</b><br/>
> -Starting with version 1.3, Velocity will log it's output to an existing
> -Log4j Category setup elsewhere in the application. To use this feature
> -you must
> - <ol>
> - <li>
> - Make sure that the Log4j jar is in your classpath. (You would do this
> - anyway since you are using Log4j in the application using Velocity.)
> - </li>
> - <li>
> - Configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
> - </li>
> - <li>
> - Specify the name of the existing Category to use via the
> - 'runtime.log.logsystem.log4j.category' property.
> - </li>
> - </ol>
> -
> -This approach replaces and deprecates the older <code>Log4JLogSystem</code>
> -class. To see how this is done in code, see the example below.
> -</li>
> +
> +<li>
> +<b>Existing Log4j Logger/Category</b><br/>
> +Starting with version 1.3, Velocity will log it's output to an existing
> +Log4j Category setup elsewhere in the application. With version 1.5, we have
> +switched to using the Logger class, as the Categeory class is now deprecated
> +in Log4j. To use this feature you must
> + <ol>
> + <li>
> + Make sure that the Log4j jar is in your classpath. (You would do this
> + anyway since you are using Log4j in the application using Velocity.)
> + </li>
> + <li>
> + a) If your system still uses the deprecated Category,
> + configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
> + b) If your environment uses the Logger class,
> + cconfigure Velocity to use the <code>Log4JLogSystem</code> class.
> + </li>
> + <li>
> + a) If using a Category, specify the name of the existing Category to use via the
> + 'runtime.log.logsystem.log4j.category' property.
> + b) If using a Logger, specify the name of the existing Logger to use via the
> + 'runtime.log.logsystem.log4j.logger' property.
> + </li>
> + </ol>
> +
> +Note that this support for Logger is in version 1.5 of Velocity. Further,
> +in version 1.5 we removed the now-ancient and very deprecated origianl
> +Log4JLogSystem class and replaced with the current Log4JLogSystem class which
> +uses the Logger class. We apologize for the confusion, but we needed to move
> +on.
> +</li>
>
> <li>
> <b>Custom Standalone Logger</b><br/>
> @@ -2180,68 +2204,68 @@
>
> </ul>
>
> -<a name="Using Log4j With Existing Category"><strong>Using Log4j With Existing Category</strong></a>
> -
> -<p>
> -Here is an example of how to configure Velocity to log to an existing Log4j
> -Category.
> -</p>
> -
> -<source><![CDATA[
> -import org.apache.velocity.app.VelocityEngine;
> -import org.apache.velocity.runtime.RuntimeConstants;
> -
> -import org.apache.log4j.Category;
> -import org.apache.log4j.BasicConfigurator;
> -
> -public class Log4jCategoryExample
> -{
> - public static String CATEGORY_NAME = "velexample";
> -
> - public static void main( String args[] )
> - throws Exception
> - {
> - /*
> - * configure log4j to log to console
> - */
> -
> - BasicConfigurator.configure();
> -
> - Category log = Category.getInstance( CATEGORY_NAME );
> -
> - log.info("Hello from Log4jCategoryExample - ready to start velocity");
> -
> - /*
> - * now create a new VelocityEngine instance, and
> - * configure it to use the category
> - */
> -
> - VelocityEngine ve = new VelocityEngine();
> -
> - ve.setProperty( RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
> - "org.apache.velocity.runtime.log.SimpleLog4JLogSystem" );
> -
> - ve.setProperty("runtime.log.logsystem.log4j.category", CATEGORY_NAME);
> -
> - ve.init();
> -
> - log.info("this should follow the initialization output from velocity");
> - }
> -}
> -]]></source>
> -
> -<p>
> -Note that the above example can be found in <code>examples/logger_example</code>.
> -</p>
> -
> +<a name="Using Log4j With Existing Category"><strong>Using Log4j With Existing Category</strong></a>
> +
> +<p>
> +Here is an example of how to configure Velocity to log to an existing Log4j
> +Category.
> +</p>
> +
> +<source><![CDATA[
> +import org.apache.velocity.app.VelocityEngine;
> +import org.apache.velocity.runtime.RuntimeConstants;
> +
> +import org.apache.log4j.Category;
> +import org.apache.log4j.BasicConfigurator;
> +
> +public class Log4jCategoryExample
> +{
> + public static String CATEGORY_NAME = "velexample";
> +
> + public static void main( String args[] )
> + throws Exception
> + {
> + /*
> + * configure log4j to log to console
> + */
> +
> + BasicConfigurator.configure();
> +
> + Category log = Category.getInstance( CATEGORY_NAME );
> +
> + log.info("Hello from Log4jCategoryExample - ready to start velocity");
> +
> + /*
> + * now create a new VelocityEngine instance, and
> + * configure it to use the category
> + */
> +
> + VelocityEngine ve = new VelocityEngine();
> +
> + ve.setProperty( RuntimeConstants.RUNTIME_LOG_LOGSYSTEM_CLASS,
> + "org.apache.velocity.runtime.log.SimpleLog4JLogSystem" );
> +
> + ve.setProperty("runtime.log.logsystem.log4j.category", CATEGORY_NAME);
> +
> + ve.init();
> +
> + log.info("this should follow the initialization output from velocity");
> + }
> +}
> +]]></source>
> +
> +<p>
> +Note that the above example can be found in <code>examples/logger_example</code>.
> +</p>
> +
> <a name="Simple Example of a Custom Logger"><strong>Simple Example of a Custom Logger</strong></a>
>
> <p>
> -Here is an example of how to use an instantiation of your class that implements
> -Velocity's logging system as the logger. Note that we are not passing the name
> -of the class to use, but rather a living, existing instantiation of the class
> -to be used. All that is required is that it support the
> -<code>LogSystem</code> interface.
> +Here is an example of how to use an instantiation of your class that implements
> +Velocity's logging system as the logger. Note that we are not passing the name
> +of the class to use, but rather a living, existing instantiation of the class
> +to be used. All that is required is that it support the
> +<code>LogSystem</code> interface.
>
> </p>
>
> @@ -2299,8 +2323,8 @@
> </section>
>
> <section name="Configuring Resource Loaders">
> -
> -<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
> +
> +<a name="Resource Loaders"><strong>Resource Loaders</strong></a>
>
> <p>
> One of the fundamental and important parts about Velocity is the resource
> @@ -2536,76 +2560,76 @@
> 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>
> -
> -<p>
> -A resource cache implementation may want to limit the cache size
> -(rather than providing an unbounded cache which could consume all
> -available memory). To configure Velocity to set the size for your
> -cache, use the configuration key:
> -</p>
> -
> -<source><![CDATA[
> -resource.manager.cache.size
> -]]></source>
> -
> -<p>
> -This key is also defined as a contstant
> -<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
> -</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>
> +
> +<p>
> +A resource cache implementation may want to limit the cache size
> +(rather than providing an unbounded cache which could consume all
> +available memory). To configure Velocity to set the size for your
> +cache, use the configuration key:
> +</p>
> +
> +<source><![CDATA[
> +resource.manager.cache.size
> +]]></source>
> +
> +<p>
> +This key is also defined as a contstant
> +<code>RuntimeConstants.RESOURCE_MANAGER_CACHE_SIZE</code>
> +</p>
> +
> </section>
>
> <section name="Template Encoding for Internationalization">
>
>
>
> 1.104 +29 -7 jakarta-velocity/docs/developer-guide.html
>
> Index: developer-guide.html
> ===================================================================
> RCS file: /home/cvs/jakarta-velocity/docs/developer-guide.html,v
> retrieving revision 1.103
> retrieving revision 1.104
> diff -u -r1.103 -r1.104
> --- developer-guide.html 22 Oct 2003 03:00:46 -0000 1.103
> +++ developer-guide.html 23 Oct 2003 13:49:28 -0000 1.104
> @@ -2358,6 +2358,19 @@
> runtime log.
> </p>
> <p>
> +<code>resource.manager.cache.class</code> Declares the class to be used
> +for resource caching. The current default is
> +<code>org.apache.velocity.runtime.resource.ResourceCacheImpl</code>
> +which uses a LRU Map to prevent data from being held forever. You can
> +set the size of the LRU Map using the parameter
> +<code>resource.manager.defaultcache.size</code>. The dafault value
> +of the default cache size is currently 89.
> +</p>
> + <p>
> +<code>resource.manager.defaultcache.size</code> Sets the size of the
> + default implementation of the resource manager resource cache.
> +</p>
> + <p>
> <code>resource.loader = <name> (default = File)</code><br />
> <i>Multi-valued key. Will accept CSV for value.</i> Pulic name of a
> resource loader to be used. This public name will then be used
> @@ -2576,26 +2589,35 @@
> </li>
>
> <li>
> -<b>Existing Log4j Category</b><br />
> +<b>Existing Log4j Logger/Category</b><br />
> Starting with version 1.3, Velocity will log it's output to an existing
> -Log4j Category setup elsewhere in the application. To use this feature
> -you must
> +Log4j Category setup elsewhere in the application. With version 1.5, we have
> +switched to using the Logger class, as the Categeory class is now deprecated
> +in Log4j. To use this feature you must
> <ol>
> <li>
> Make sure that the Log4j jar is in your classpath. (You would do this
> anyway since you are using Log4j in the application using Velocity.)
> </li>
> <li>
> - Configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
> + a) If your system still uses the deprecated Category,
> + configure Velocity to use the <code>SimpleLog4JLogSystem</code> class.
> + b) If your environment uses the Logger class,
> + cconfigure Velocity to use the <code>Log4JLogSystem</code> class.
> </li>
> <li>
> - Specify the name of the existing Category to use via the
> + a) If using a Category, specify the name of the existing Category to use via the
> 'runtime.log.logsystem.log4j.category' property.
> + b) If using a Logger, specify the name of the existing Logger to use via the
> + 'runtime.log.logsystem.log4j.logger' property.
> </li>
> </ol>
>
> -This approach replaces and deprecates the older <code>Log4JLogSystem</code>
> -class. To see how this is done in code, see the example below.
> +Note that this support for Logger is in version 1.5 of Velocity. Further,
> +in version 1.5 we removed the now-ancient and very deprecated origianl
> +Log4JLogSystem class and replaced with the current Log4JLogSystem class which
> +uses the Logger class. We apologize for the confusion, but we needed to move
> +on.
> </li>
>
> <li>
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org