Author: buildbot
Date: Mon May 4 11:19:53 2020
New Revision: 1060137
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/class-reloading.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/class-reloading.html
==============================================================================
--- websites/production/tapestry/content/class-reloading.html (original)
+++ websites/production/tapestry/content/class-reloading.html Mon May 4
11:19:53 2020
@@ -178,17 +178,17 @@
<p>One of the best features of Tapestry is automatic reloading of changed
classes and templates. <em>Page and component</em> classes will automatically
reload when changed. Likewise, changes to component templates and other related
resources will also be picked up immediately. In addition, starting in version
5.2, your service classes will also be reloaded automatically after changes (if
you're using <a href="ioc.html">Tapestry IoC</a>).</p><h2
id="ClassReloading-Contents">Contents</h2><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1588512138959 {padding: 0px;}
-div.rbtoc1588512138959 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1588512138959 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1588591168705 {padding: 0px;}
+div.rbtoc1588591168705 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1588591168705 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1588512138959">
+/*]]>*/</style></p><div class="toc-macro rbtoc1588591168705">
<ul class="toc-indentation"><li><a
href="#ClassReloading-TemplateReloading">Template Reloading</a></li><li><a
href="#ClassReloading-ClassReloading">Class Reloading</a></li><li><a
href="#ClassReloading-PackagesScanned">Packages Scanned</a></li><li><a
href="#ClassReloading-FileSystemOnly">File System Only</a></li><li><a
href="#ClassReloading-ClassLoaderIssues">Class Loader Issues</a></li><li><a
href="#ClassReloading-ClassCastExceptions">ClassCastExceptions</a></li><li><a
href="#ClassReloading-HandlingReloadsinyourCode">Handling Reloads in your
Code</a></li><li><a href="#ClassReloading-CheckingForUpdates">Checking For
Updates</a></li><li><a
href="#ClassReloading-TroubleshootingLiveClassReloading">Troubleshooting Live
Class Reloading</a>
<ul class="toc-indentation"><li><a href="#ClassReloading-QuickChecklist">Quick
Checklist</a></li><li><a
href="#ClassReloading-IfLiveClassReloadingdoesn'twork">If Live Class Reloading
doesn't work</a>
<ul class="toc-indentation"><li><a
href="#ClassReloading-ProductionMode">Production Mode</a></li><li><a
href="#ClassReloading-BuildPathIssues">Build Path Issues</a></li><li><a
href="#ClassReloading-BuildingAutomatically">Building
Automatically</a></li><li><a
href="#ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</a></li></ul>
</li><li><a href="#ClassReloading-TomcatSpecifics">Tomcat
Specifics</a></li><li><a
href="#ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class
Reloading works but is slow</a></li></ul>
</li></ul>
-</div><h2 id="ClassReloading-TemplateReloading">Template Reloading</h2><p>When
a template changes, all page instances (as well as the hierarchy of components
below them) are discarded and reconstructed with the new template. However,
classes are not reloaded in this case.</p><h2
id="ClassReloading-ClassReloading">Class Reloading</h2><p>On a change to
<em>any</em> loaded class from inside a controlled package (or any sub-package
of a controlled package), Tapestry will discard all page instances, and discard
the class loader.</p><p><a href="class-reloading.html">Persistent field
data</a> on the pages will usually not be affected (as it is stored separately,
usually in the session). This allows you to make fairly significant changes to
a component class even while the application continues to run.</p><h2
id="ClassReloading-PackagesScanned">Packages Scanned</h2><p>Only certain
classes are subject to reload. Reloading is based on package name; the packages
that are reloaded are derived f
rom the <a href="configuration.html">application configuration</a>.</p><p>If
your root package is <code>org.example.myapp</code>, then only classes in the
following packages (and their sub-packages) will be scanned for automatic
reloads:</p><ul><li>org.example.myapp.pages</li><li>org.example.myapp.components</li><li>org.example.myapp.mixins</li><li>org.example.myapp.base</li><li>org.example.myapp.services
(Tapestry 5.2 and later, with restrictions)</li></ul><p>Starting in Tapestry
5.2, live class reloading includes service implementation classes. There are
some limitations to this. See <a
href="service-implementation-reloading.html">Service Implementation
Reloading</a> for more details.</p><h2 id="ClassReloading-FileSystemOnly">File
System Only</h2><p>Reloading of classes and other files applies only to files
that are actually on the file system, and not files obtained from JAR files.
This is perfect during development, where the files in question are in your
local workspace. I
n a deployed application, you are somewhat subject to the implementation of
your servlet container or application server.</p><h2
id="ClassReloading-ClassLoaderIssues">Class Loader Issues</h2><p>Tapestry uses
an extra class loader to load page and component classes.</p><p>When a change
to an underlying Java class file is detected, Tapestry discards the class
loader and any pooled page instances.</p><p>You should be careful to not hold
any references to Tapestry pages or components in other code, such as Tapestry
IoC services. Holding such references can cause significant memory leaks, as
they can prevent the class loader from being reclaimed by the garbage
collector.</p><h2
id="ClassReloading-ClassCastExceptions">ClassCastExceptions</h2><p>Tapestry's
class loader architecture can cause minor headaches when you make use of a
services layer, or any time that you pass component instances to objects that
are not themselves components.</p><p>In such cases you may see
ClassCastException er
rors. This is because the same class name, say org.example.myapp.pages.Start,
exists as two different class instances. One class instance is loaded by the
web application's default class loader. A second class instance has been loaded
<em>and transformed</em> by Tapestry's reloading class loader.</p><p>Ordinary
classes, such as Tapestry IoC Services, will be loaded by the default class
loader and expect instances to be loaded by the same class loader (or a
parent).</p><p>The solution to this problem is to introduce an interface; the
component class should implement the interface, and the service should expect
an instance of the interface, rather than a specific type.</p><p>It is
important that the interface be loaded by the default class loader. It should
not be in the pages or components package, but instead be in another package,
such as services.</p><h2 id="ClassReloading-HandlingReloadsinyourCode">Handling
Reloads in your Code</h2><p>On occasion, you may need to know when invali
dations occur, to clear your own cache. For example, if you have a binding
that creates new classes, the way <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PropertyConduitSource.html";>PropertyConduitSource</a>
does, you need to discard any cached classes or instances when a change is
detected in component classes.</p><p>You do this by registering a listener with
the correct <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tpaestry5/services/InvalidationEventHub.html";>InvalidationEventHub</a>
service.</p><p>For example, your service may be in the business of creating
new classes based on component classes, and keep a cache of those
classes:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div><h2 id="ClassReloading-TemplateReloading">Template Reloading</h2><p>When
a template changes, all page instances (as well as the hierarchy of components
below them) are discarded and reconstructed with the new template. However,
classes are not reloaded in this case.</p><h2
id="ClassReloading-ClassReloading">Class Reloading</h2><p>On a change to
<em>any</em> loaded class from inside a controlled package (or any sub-package
of a controlled package), Tapestry will discard all page instances, and discard
the class loader.</p><p><a
href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=84804223";>Persistent
field data</a> on the pages will usually not be affected (as it is stored
separately, usually in the session). This allows you to make fairly significant
changes to a component class even while the application continues to
run.</p><h2 id="ClassReloading-PackagesScanned">Packages Scanned</h2><p>Only
certain classes are subject to reload. Reloading is based on packa
ge name; the packages that are reloaded are derived from the <a
href="configuration.html">application configuration</a>.</p><p>If your root
package is <code>org.example.myapp</code>, then only classes in the following
packages (and their sub-packages) will be scanned for automatic
reloads:</p><ul><li>org.example.myapp.pages</li><li>org.example.myapp.components</li><li>org.example.myapp.mixins</li><li>org.example.myapp.base</li><li>org.example.myapp.services
(Tapestry 5.2 and later, with restrictions)</li></ul><p>Starting in Tapestry
5.2, live class reloading includes service implementation classes. There are
some limitations to this. See <a
href="service-implementation-reloading.html">Service Implementation
Reloading</a> for more details.</p><h2 id="ClassReloading-FileSystemOnly">File
System Only</h2><p>Reloading of classes and other files applies only to files
that are actually on the file system, and not files obtained from JAR files.
This is perfect during development, where
the files in question are in your local workspace. In a deployed application,
you are somewhat subject to the implementation of your servlet container or
application server.</p><h2 id="ClassReloading-ClassLoaderIssues">Class Loader
Issues</h2><p>Tapestry uses an extra class loader to load page and component
classes.</p><p>When a change to an underlying Java class file is detected,
Tapestry discards the class loader.</p><p>You should be careful to not hold any
references to Tapestry pages or components in other code, such as Tapestry IoC
services. Holding such references can cause significant memory leaks, as they
can prevent the class loader from being reclaimed by the garbage
collector.</p><h2
id="ClassReloading-ClassCastExceptions">ClassCastExceptions</h2><p>Tapestry's
class loader architecture can sometimes cause a minor problem when you make use
of a services layer without interfaces, or if that you pass component instances
to objects that are not themselves components.</p><p>I
n such cases you may see ClassCastException errors. This is because the same
class name, say org.example.myapp.pages.Start, exists as two different class
instances. One class instance is loaded by the web application's default class
loader. A second class instance has been loaded <em>and transformed</em> by
Tapestry's reloading class loader.</p><p>Ordinary classes, such as Tapestry IoC
Services, will be loaded by the default class loader and expect instances to be
loaded by the same class loader (or a parent).</p><p>The solution to this
problem is to introduce an interface; the component class should implement the
interface, and the service should expect an instance of the interface, rather
than a specific type.</p><p>It is important that the interface be loaded by the
default class loader. It should not be in the pages or components package, but
instead be in another package, such as services.</p><h2
id="ClassReloading-HandlingReloadsinyourCode">Handling Reloads in your
Code</h2><p
>On occasion, you may need to know when invalidations occur, to clear your own
>cache. For example, if you have a binding that creates new classes, the way
><a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PropertyConduitSource.html";>PropertyConduitSource</a>
> does, you need to discard any cached classes or instances when a change is
>detected in component classes.</p><p>You do this by registering a listener
>with the correct <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tpaestry5/services/InvalidationEventHub.html";>InvalidationEventHub</a>
> service.</p><p>For example, your service may be in the business of creating
>new classes based on component classes, and keep a cache of those
>classes:</p><div class="code panel pdl" style="border-width: 1px;"><div
>class="codeContent panelContent pdl">
<pre><code class="language-java">public class MyServiceImpl implements
MyService, InvalidationEventListener
{
public final Map<String,Class> cache = new
ConcurrentHashMap<String,Class>();
@@ -209,7 +209,7 @@ div.rbtoc1588512138959 li {margin-left:
</div></div><p>This is the intent of service builder methods; to do more than
just injecting dependencies.</p><h2
id="ClassReloading-CheckingForUpdates">Checking For Updates</h2><p>The built in
InvalidationEventHub services provide notifications of changes to component
classes, to component templates, and to component message catalogs. If you wish
to check some other resources (for example, files in a directory of the file
system or rows in a database table), you should register as an <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/UpdateListener.html";>UpdateListener</a>
with the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/UpdateListenerHub.html";>UpdateListenerHub</a>
service.</p><p>Periodically (the frequency is configurable), UpdateListeners
are notified that they should check for updates. Typically, UpdateListeners are
also InvalidationEventHubs (or provide Invalida
tionEventHubs), so that other interested parties can be alerted when
underlying data changes.</p><h2
id="ClassReloading-TroubleshootingLiveClassReloading">Troubleshooting Live
Class Reloading</h2><h3 id="ClassReloading-QuickChecklist">Quick
Checklist</h3><ul><li>"Production Mode" must be false (in Tapestry 5.3 and
later)</li><li>The class must be one that Tapestry instantiates (a page,
component, or mixin class, or a Tapestry IOC service implementation that
implements an interface)</li><li>Turn on "Build Automatically" in your IDE, or
remember to build manually.</li><li>Turn <em>off</em> JVM hot code swapping, if
your servlet container supports it.</li><li>Eclipse: Uncheck the "derived"
checkbox for the Target dir (in the Project Explorer view, right click on
"target", select properties, uncheck "derived" on the Resource
tab)</li></ul><p>Some of these issues are described in more detail
below.</p><h3 id="ClassReloading-IfLiveClassReloadingdoesn'twork">If Live Class
Reloading doesn't
work</h3><h4 id="ClassReloading-ProductionMode">Production
Mode</h4><p>Starting with Tapestry 5.3, Live Class Reloading only works when
not in "Production Mode". Check your application module (usually
AppModule.java) to be sure you have:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre><code
class="language-java">configuration.add(SymbolConstants.PRODUCTION_MODE,
"false");
</code></pre>
-</div></div><p>and that this isn't being overridden to "true" on your
application's startup command line.</p><h4
id="ClassReloading-BuildPathIssues">Build Path Issues</h4><p>Live Class
Reloading can fail if your build path isn't set correctly, and the exact
configuration may differ between Maven plugin versions and Eclipse versions.
The build process must be set to create classes in a folder which is in the
servlet container's classpath.</p><p>Live Class Reloading won't work correctly
with vanilla Tomcat without some tweaks (see below).</p><p>Non-Tapestry filters
can interfere with LCR. Try disabling other filters in your web.xml file to see
if that helps.</p><h4 id="ClassReloading-BuildingAutomatically">Building
Automatically</h4><p>Although LCR allows you to see changes without restarting
your app, you still need to "build" your project (to compile the Java source
into byte code). Your IDE can be set to do this automatically every time you
save a file. (In Eclipse, this is done us
ing <code>Project > Build Automatically</code>.) Alternatively, you can
manually trigger a build after you save a file. (In Eclipse, this is done using
<code>Project > Build</code>, or by pressing <code>Control-B</code>.)</p><h4
id="ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</h4><p>Many servlet containers,
including Tomcat and Jetty, support various forms of hot code swapping and/or
automatic restarts when file changes are detected. These are generally
<strong>much slower</strong> than LCR and usually should be turned off with
Tapestry applications. If you're using RunJettyRun plugin for Eclipse, for
example, edit your Run Configuration, and on the Jetty tab, click Show Advanced
Options and uncheck the Enable Scanner checkbox.</p><h3
id="ClassReloading-TomcatSpecifics">Tomcat Specifics</h3><p>See <a
class="external-link"
href="http://www.tynamo.org/Developing+with+Tomcat+and+Eclipse/";
rel="nofollow">t
hese Tomcat-specific hints</a></p><h3
id="ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class Reloading
works but is slow</h3><p>If LCR works for you but is slow (more than a second
or two), consider the following.</p><ul><li>Be sure your project source files
(your workspace in Eclipse, for example), are on a local drive, NOT a network
location. Network drives are always slower, and the file system scanning needed
for LCR can add a noticable lag if I/O is slow. If you use Maven, be sure to
put your local repository (e.g. ~/.m2/repository) on a local drive for similar
reasons.</li><li><p>Java 7 and below: Since LCR adds classes to your PermGen
space, you may be running low on PermGen memory (and may eventually get a
"java.lang.OutOfMemoryError: PermGen space" error). Try increasing PermGen size
with a JVM argument of something like -XX:MaxPermSize=400m. (PermGen
settings are not relevant for Java 8 and above.)</p></li></ul></div>
+</div></div><p>and that this isn't being overridden to "true" on your
application's startup command line.</p><h4
id="ClassReloading-BuildPathIssues">Build Path Issues</h4><p>Live Class
Reloading can fail if your build path isn't set correctly, and the exact
configuration may differ between Maven plugin versions and Eclipse versions.
The build process must be set to create classes in a folder which is in the
servlet container's classpath.</p><p>Live Class Reloading won't work correctly
with vanilla Tomcat without some tweaks (see below).</p><p>Non-Tapestry filters
can interfere with LCR. Try disabling other filters in your web.xml file to see
if that helps.</p><h4 id="ClassReloading-BuildingAutomatically">Building
Automatically</h4><p>Although LCR allows you to see changes without restarting
your app, you still need to "build" your project (to compile the Java source
into byte code). Your IDE can be set to do this automatically every time you
save a file. (In Eclipse, this is done us
ing <code>Project > Build Automatically</code>.) Alternatively, you can
manually trigger a build after you save a file. (In Eclipse, this is done using
<code>Project > Build</code>, or by pressing <code>Control-B</code>.)</p><h4
id="ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</h4><p>Many servlet containers,
including Tomcat and Jetty, support various forms of hot code swapping and/or
automatic restarts when file changes are detected. These are generally
<strong>much slower</strong> than LCR and usually should be turned off with
Tapestry applications. If you're using RunJettyRun plugin for Eclipse, for
example, edit your Run Configuration, and on the Jetty tab, click Show Advanced
Options and uncheck the Enable Scanner checkbox.</p><h3
id="ClassReloading-TomcatSpecifics">Tomcat Specifics</h3><p>See <a
class="external-link"
href="http://www.tynamo.org/Developing+with+Tomcat+and+Eclipse/";
rel="nofollow">t
hese Tomcat-specific hints</a></p><h3
id="ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class Reloading
works but is slow</h3><p>If LCR works for you but is slow (more than a second
or two), consider the following.</p><ul><li>Be sure your project source files
(your workspace in Eclipse, for example), are on a local drive, NOT a network
location. Network drives are always slower, and the file system scanning needed
for LCR can add a noticable lag if I/O is slow. If you use Maven, be sure to
put your local repository (e.g. ~/.m2/repository) on a local drive for similar
reasons.</li><li><p>Java 7 and below: Since LCR adds classes to your PermGen
space, you may be running low on PermGen memory (and may eventually get a
"java.lang.OutOfMemoryError: PermGen space" error). Try increasing PermGen size
with a JVM argument of something like -XX:MaxPermSize=400m. (PermGen
settings are not relevant for Java 8 and
above.)</p></li></ul><p></p><p></p></div>
</div>
<!-- /// Content End -->
</div>
