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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
