[seam-commits] Seam SVN: r9535 - trunk/doc/Seam_Reference_Guide/en-US.

[seam-commits at lists.jboss.org]

Author: shane.bryzak at jboss.com
Date: 2008-11-10 01:24:00 -0500 (Mon, 10 Nov 2008)
New Revision: 9535

Added:
   trunk/doc/Seam_Reference_Guide/en-US/Performance.xml
Modified:
   trunk/doc/Seam_Reference_Guide/en-US/master.xml
Log:
JBSEAM-2704

Added: trunk/doc/Seam_Reference_Guide/en-US/Performance.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Performance.xml	                        (rev 0)
+++ trunk/doc/Seam_Reference_Guide/en-US/Performance.xml	2008-11-10 06:24:00 UTC (rev 9535)
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<chapter id="performance">
+  <title>Performance Tuning</title>
+  
+  <para>
+    This chapter is an attempt to document in one place all the tips for getting the best performance from
+    your Seam application.
+  </para>
+    
+  <section>
+    <title>Bypassing Interceptors</title>
+    
+    <para>
+      For repetitive value bindings such as those found in a JSF dataTable or other iterative control 
+      (like <literal>ui:repeat</literal>), the full interceptor stack will be invoked for every invocation of 
+      the referenced Seam component.  The effect of this can result in a substantial performance hit, especially 
+      if the component is accessed many times.  A significant performance gain can be achieved by disabling the 
+      interceptor stack for the Seam component being invoked.  To disable interceptors for the component, add the 
+      <literal>@BypassInterceptors</literal> annotation to the component class.       
+    </para>
+    
+    <warning>
+      <para>
+        It is very important to be aware of the implications of disabling interceptors for a Seam component.
+        Features such as bijection, annotated security restrictions, synchronization and others are 
+        unavailable for a component marked with <literal>@BypassInterceptors</literal>.  While in most cases
+        it is possible to compensate for the loss of these features (e.g. instead of injecting a component
+        using <literal>@In</literal>, you can use <literal>Component.getInstance()</literal> instead) it is
+        important to be aware of the consequences.
+      </para>      
+    </warning>
+    
+    <para>
+      The following code listing demonstrates a Seam component with its interceptors disabled:
+    </para>
+    
+    <programlisting><![CDATA[@Name("foo")
+ at Scope(EVENT)
+ at BypassInterceptors
+public class Foo
+{
+   public String getRowActions()
+   {
+     // Role-based security check performed inline instead of using @Restrict or other security annotation
+     Identity.instance().checkRole("user");
+     
+     // Inline code to lookup component instead of using @In
+     Bar bar = (Bar) Component.getInstance("bar");
+   
+     String actions;   
+     // some code here that does something     
+     return actions;
+   }
+}]]></programlisting>
+    
+    
+    
+  </section>
+    
+    
+</chapter>
\ No newline at end of file

Modified: trunk/doc/Seam_Reference_Guide/en-US/master.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/master.xml	2008-11-09 23:21:43 UTC (rev 9534)
+++ trunk/doc/Seam_Reference_Guide/en-US/master.xml	2008-11-10 06:24:00 UTC (rev 9535)
@@ -37,6 +37,7 @@
     <xi:include href= "Components.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Controls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Elenhancements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+    <xi:include href= "Performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />    
     <xi:include href= "Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
     <xi:include href= "Oc4j.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />