<!-- $Id$ -->
<!--
   Copyright 2004 The Apache Software Foundation
  
   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

  
  <appendix id="faq">
    <title>Frequently Asked Questions</title>
    <para>
This section contains a few Q's and A's gleemed from the Tapestry developer mailing list. 
</para>
    <qandaset defaultlabel="qanda">
      <qandaentry>
        <question>
          <para>
            <classname>java.lang.NoSuchMethodError</classname> gets thrown
		when I attempt to use Tapestry with Tomcat.  How do I fix this?
		</para>
        </question>
        <answer>
          <para>
            <ulink url="http://jakarta.apache.org/tomcat/index.html">Tomcat</ulink> ships with version 1.0 of the 
	<ulink url="http://java.sun.com/xml/xml_jaxp.html">JAXP (Java API for XML Processing)</ulink> 
	framework.  Tapestry is coded against version 1.1.  You must replace the
	<filename>jaxp.jar</filename> in Tomcat with the
	<filename>javax.xml.jaxp.jar</filename> from Tapestry.  Simply delete the old file
	and copy the new one into the Tomcat distribution.
		</para>
          <para>
		In addition you must replace <filename>parser.jar</filename> (which contains
		an XML parser) with
		<filename>org.apache.crimson.jar</filename>, Sun's default XML parser.
		</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>Can Tapestry be used to create a Portal application?</para>
        </question>
        <answer>
          <para>
		Of course it can!
		</para>
          <para>
		This question came up pretty frequently on the SourceForge forum, so
		I put together a mini-portal application as one of the tutorials.  This sounded
		out some limitations in the framework: the <classname>Porlet</classname> component
		dynamically combines components from multiple pages (using the &Block; and
		&RenderBlock; components).
		</para>
        </answer>
      </qandaentry>
      
      <qandaentry>
      	<question>
      		<para>
      		Is Jetty required to use Tapestry?
      		</para>
      	</question>
      	<answer>
      	<para>
      	For a brief period of time, Tapestry used some Jetty specific code
      	to process file uploads.  This showed up in release 2.0.0 and was fixed (removing all Jetty
      	dependencies) in release 2.0.1.
      	</para>
      	<para>
      	Tapestry still includes Jetty since it so easy to embed Jetty
      	and use it for testing and development, but it is not required.  Many users
      	have had great success using Tomcat or Resin with Tapestry.
      	</para>
      	</answer>
      </qandaentry>
      
      <qandaentry>
      	<question>
      		<para>
      		Why do I get NoClassDefFoundError exceptions in my Tapestry application
      		deployed under WebLogic 6.1?
      		</para>
   		</question>
   		<answer>
   		<para>
WebLogic appears to have a bug when deploying WAR files that contain libraries.  If the library name,
in this case &TapestryFrameworkJar;
contains any periods, then WebLogic fails to expand the JAR file into its temporary deployment
directory.  The end result is that
 the Tapestry classes aren't on the classpath.
 </para>
 
   		<para>
   		The solution is to rename the Tapestry JAR file to not have periods in the name.  Simply renaming it to <filename>tapestry.jar</filename>
   		or <filename>tapestry<replaceable>123</replaceable>.jar</filename>
   		will do.
   		</para>
   		</answer>
   	</qandaentry>
      
      <qandaentry>
        <question>
          <para>
		One more time.  What's this business about rewinding things for forms?
		</para>
        </question>
        <answer>
          <para>
		This is one of the big stumbling blocks for some users of Tapestry.
		The way Tapestry deals with forms is very complex, with a reason: it allows
		for incredibly dynamic pages.
		</para>
          <para>
		In tradional web appllications, the developer is responsible for
		naming each form element, as well as writing a servlet to
		handle the request cycle when the form is submitted.  That turns into
		a lot of code to extract name parameters from the &HttpServletRequest;, 
		convert them from Strings to other datatypes, and push the values
		into appropriate business objects.
		</para>
          <para>
		This works fine as far as it goes ... but the developer has an advantage 
		that the Tapestry framework doesn't have:  the exact name, type and number
		of form elements is known during development.
		</para>
          <para>
		By contrast, Tapestry has to figure this all out on the fly.  In addition,
		Tapestry forms can wrap around &Foreach; components ... that means the same
		&TextField; component may be responsible for updating a property of
		a whole slew of objects.  On top of that, the use
		of &Conditional;, &Block; and &RenderBlock; components
		mean that the exact set of components involved may be determined dynamically.
		</para>
          <note>
            <para>
			An example of this is the 
			<link linkend="inspector.logging">Tapestry Inspector Logging View</link>.  A single
			&PropertySelection; is wrapped by a &ListEdit; which iterates throught
			a list of the possible categories.
			</para>
            <para>
			Categories may be added at any time (in fact, that's another function
			of the page).
			</para>
          </note>
          <para>
		Now, it's natural to envision Tapestry dynamically walking through its components
		and HTML templates to render the form seen in the user's web browser.  The
		mental leap required is that
		the initial renderring process has to be <emphasis>run again</emphasis> in order to figure out
		which components are involved in processing the submission, and how.  That's
		the <emphasis>rewind phase</emphasis>.
		</para>
          <para>
		Just as with the initial render, Tapestry must work through 
		just the right set of components, in just the right order, taking into account
		&Conditional; and &Foreach; components.  You must also factor in that Tapestry is
		assigning the names used for the HTML form elements, which must also be "rediscovered"
		so that the right HTTP parameter can be combined with the correct component and
		assigned to the appropriate business object property.
		</para>
          <para>
		Sure, this is overkill when you have a simple form to enter the user's name.
		But doesn't it give you a warm feeling to know that when you do create
		your killer dynamic form, the <emphasis>very same code</emphasis> you've come to know
		and trust will be waiting to handle it, just as easily?
		</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>
	How do I specify the CSS class used for a Tapestry component?
	</para>
        </question>
        <answer>
          <para>
	Most Tapestry components support
	<link linkend="components.informal-parameters">informal parameters</link>.  
	These are used to specify
	additional HTML attributes for the tag generated by the component.
	</para>
          <para>
	You can set the value for such informal parameters
	is bindings in the &spec.component; element, or
	in the <link linkend="components.html-template">HTML template</link>.
	</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>
	I get the StaleSession page when I submit a form on my home page.  Why?
	</para>
        </question>
        <answer>
          <para>
	Tapestry applications run in a <link linkend="engine.stateless">stateless</link> mode initially.  That is, they
	don't create a &HttpSession;.  This continues until the application has
	some specific server-side state, at which point the &HttpSession; is created.
	</para>
          <para>
	By default, &Form;s (as well as &ActionLink;s) are stateful; they require that
	an active &HttpSession; exists.  If there isn't an active session, they
	throw a <classname>StaleSessionException</classname>.  However, you can bind
	the <varname>stateful</varname> parameter of these components to
	<classname>Boolean.FALSE</classname> to remove this check.
	</para>
          <para>
	This check makes sense once there's server side state; it detects when
	an &HttpSession; has expired from lack of use.  It's better than seeing
	an anomolous <classname>NullPointerException</classname>, which is quite likely
	when all state is lost.
	</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>What happened to the &ILifecycle; interface?</para>
        </question>
        <answer>
          <para>
Prior to release 1.0.5, there was an interface, &ILifecycle;, that could
optionally be implemented by components so that they could be informed about the lifecycle
of the page which contains them, especially knowing when the page was detached from the engine (so that
the components could reset their state accordingly).  
</para>
          <para>
By release 1.0.5, this has become somewhat awkward.  Firstly, several non-component objects needed
similar notification and there wasn't a way to cleanly accomplish this.  Secondly, a finer grained
approach was desired, as different objects had different notification requirements.
</para>
          <para>
For release 1.0.5, the interface was replaced by a more standard approach; well defined JavaBeans events.
These are described in the <link linkend="pages.events">Page Events</link> section of this document.
</para>
          <para>
The &ILifecycle; interface was removed in release 2.0.0.
</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>Why do I need to subclass &ApplicationServlet;?
		</para>
        </question>
        <answer>
          <para>
Several folks have suggested that subclassing &ApplicationServlet; is unneccessary,
and it's primary job, identifying the application specification path, could be accomplished 
using servlet initial parameters.
There are several reasons why a subclass is necessary, outlined in this
<link linkend="engine.servlet.subclass-note">note</link>.  Primarily, it's
a class loader issue.
</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>What happened to <classname>ValidatingTextField</classname>,
		<classname>NumericField</classname>,
		<classname>DateField</classname>
		and <classname>IntegerField</classname>?
		</para>
        </question>
        <answer>
          <para>
		In release 1.0.8, the entire suite of components related to validating
		form input was rewritten.  A single component, &ValidField;, now does the work
		of all the others.  In the earlier version, component subclasses were needed
		to change the behavior:  converting objects to strings, strings to objects and
		validating.  This is now encapsulated in the &IValidator; interface.  In short, it is now
		much easier to create new kinds of validations and just plug them into the
		&ValidField;.
		</para>
        
          <para>This was, regrettably, a completely non-backwards compatible change.  However,
          compatible versions of three of the 1.0.7 components
          (<classname>ValidatingTextField</classname>,
		<classname>NumericField</classname> and
		<classname>DateField</classname>) are now part of the 
		&TapestryContribJar; library.
		</para>
		
          <para>
		In addition, the old components had big disclaimers:  "Don't use these inside
		any kind of loop (such as a &Foreach;)".  By expanding the role of the
		&IValidationDelegate;, this is no longer so, the delegate now does much more,
		including the ability to track errors for fields even inside loops.
		</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question>
          <para>Why don't my &Upload; components work?  I keep getting NullPointerExceptions.
		</para>
        </question>
        <answer>
          <para>
		The &Upload; component creates an <sgmltag class="starttag">input type="file"</sgmltag>
		HTML element.  This requires that the containing <sgmltag class="starttag">form</sgmltag> element
		use the encoding MIME type <literal>multipart/form-data</literal>.  This is accomplished by
		setting the informal parameter <property>enctype</property> of the containing &Form; component to
		 <literal>multipart/form-data</literal>.
		</para>
        </answer>
      </qandaentry>
      
      
      <qandaentry>
      	<question>
      		<para>Why isn't Tapestry a JSP taglib?</para>
      	</question>
      	<answer>
      		<para>
      		Simply put, Tapestry needs to run the whole show, from the point the request is receieved by
      		the servlet all the way through to the end of sending a response page back to the client. 
      		All the benefits of Tapestry come from
      		features that JSPs just don't provide ... knowing the full component heirarchy for the page,
      		and tracking which components are wrapped inside which others, no matter how dynamic the
      		rendering process is.  The way components can work together to generate different
      		portions of the page is both powerful and necessary -- 
      		that's how Tapestry builds the URLs for links and forms.
      		</para>
      		
      		<para>
      		By comparison, something like 
      		<ulink url="http://jakarta.apache.org/">Struts</ulink>
      		still relies on the developer to do most of the work, by defining Actions ... which are
      		little more than a dressed up version of a servlet.  Although it has some rudimentary
      		forms support (that can also be leveraged to process query parameters from ordinary links),
      		it's still an awful lot of coding.
      		</para>
      		
      	</answer>
      </qandaentry>
      
 
<qandaentry>
<question>
<para>
I've fixed all my imports to use <filename>org.apache.tapestry</filename>, but
my &DirectLink; listener methods no longer work.  How do I fix things?
</para>
</question>
<answer>
<para>
With the removal of the <classname>IDirectListener</classname>
interface, the corresponding listener method variation was removed.  The following
method signature <emphasis>used to</emphasis>
be recognized as a listener method:
</para>

<informalexample>
<programlisting>
public void <replaceable>my-method</replaceable>(String[] parameters, &IRequestCycle; cycle)
throws RequestCycleException
{
  ...
}
</programlisting>
</informalexample>

<para>
In the new, simpler, scheme, listener methods take exactly one parameter,
the &IRequestCycle;.
The service parameters are now available from the &IRequestCycle;:
</para>

<informalexample>
<programlisting>
public void <replaceable>my-method</replaceable>(IRequestCycle cycle)
throws RequestCycleException
{
  Object[] parameters = cycle.getServiceParameters();
  ...
}
</programlisting>
</informalexample>

<para>
Starting in release 2.2, the type of each parameter is encoded with its
value in the URL (in release 2.1 and earlier, the parameters were always Strings,
and it was your responsibility to convert them).  
You can cast from &Object;
to a particular type (say, &Integer; or &String;).
</para>

</answer>
</qandaentry>


<qandaentry>
<question>
<para>
How do I duplicate a component several times in the same HTML template?
</para>
</question>

<answer>
<para>
Simply put: you can't.  Component ids must be unique in the template and
must match aganst component specification.  Even when two components
are the same type and have identical bindings, they are still unique
instances and have instance-specific state ... such as the portion of
the HTML template they wrap (for components with bodies).
</para>

<para>
A useful shortcut is to use
the <literal>copy-of</literal>
attribute of the
&spec.component; element.
</para>
</answer>

</qandaentry>
      
    </qandaset>
  </appendix>