tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hls...@apache.org
Subject cvs commit: jakarta-tapestry/doc/src/DevelopersGuide pages.xml
Date Sun, 23 Mar 2003 23:13:25 GMT
hlship      2003/03/23 15:13:24

  Modified:    doc/src/UsersGuide state.xml spec.xml configuration.xml
               doc/src/common TapestryLinks.xml
               doc/src/DevelopersGuide pages.xml
  Removed:     doc/src/DevelopersGuide/images Page-Cleanup-sequence.gif
  Log:
  Update documentation for recent changes (new app extensions and parameter direction 'auto').
  
  Revision  Changes    Path
  1.6       +6 -5      jakarta-tapestry/doc/src/UsersGuide/state.xml
  
  Index: state.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/state.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- state.xml	6 Mar 2003 19:19:33 -0000	1.5
  +++ state.xml	23 Mar 2003 23:13:23 -0000	1.6
  @@ -183,7 +183,8 @@
   </para>
   
   <para>
  -Typically, the Visit class is defined in the application specification.
  +Typically, the Visit class is defined in the application specification, or
  +as a <sgmltag class="starttag">init-parameter</sgmltag> in the web deployment
descriptor (web.xml).
   </para>
   
   <example>
  @@ -243,7 +244,7 @@
   
   <para>
   Care should be taken that the Global object is threadsafe; since many engines (from many
sessions,
  -in many threads) will access it simulatenously.  The default Global object is a synchronized
  +in many threads) will access it simultanenously.  The default Global object is a synchronized
   &HashMap;.  This can be overriden with
   <link linkend="configuration.search-path">configuration property</link>
   <literal>org.apache.tapestry.global-class</literal>.
  @@ -540,8 +541,8 @@
   <para>
   The Java interface &PageDetachListener; is the event listener interface for this purpose.
 
   By simply implementing this interface, Tapestry will register the component as a listener
and ensure that
  -it receives event notifications at the right time (this works for the two other
  -page event interfaces, &PageRenderListener; and &PageCleanupListener; as well;
simply
  +it receives event notifications at the right time (this works for the other
  +page event interface, &PageRenderListener; as well; simply
   implement the interface and leave the rest to the framework).
   </para>
   
  
  
  
  1.6       +29 -46    jakarta-tapestry/doc/src/UsersGuide/spec.xml
  
  Index: spec.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/spec.xml,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- spec.xml	7 Feb 2003 04:28:12 -0000	1.5
  +++ spec.xml	23 Mar 2003 23:13:23 -0000	1.6
  @@ -123,7 +123,7 @@
   <figure>
   	<title><sgmltag class="starttag">application</sgmltag> Elements</title>
   <literallayout>
  -  &spec.description; *, &spec.property; *,
  +  &spec.description; ?, &spec.property; *,
     (&spec.page; | &spec.component-type; | &spec.service; | &spec.library;
| &spec.extension;) *
   </literallayout>
   </figure>
  @@ -250,7 +250,7 @@
   <figure>
   	<title><sgmltag class="starttag">bean</sgmltag> Elements</title>
   <literallayout>
  -  &spec.description; *, &spec.property; *,
  +  &spec.description; ?, &spec.property; *,
     (&spec.set-property; | &spec.set-string-property;) *
   </literallayout>
   </figure>
  @@ -600,7 +600,7 @@
   <figure>
   	<title><sgmltag class="starttag">component-specification</sgmltag> Elements</title>
   <literallayout>
  -  &spec.description; *, &spec.parameter; *, &spec.reserved-parameter; *, &spec.property;
*,
  +  &spec.description; ?, &spec.parameter; *, &spec.reserved-parameter; *, &spec.property;
*,
     (&spec.bean; | &spec.component; | &spec.external-asset; | &spec.context-asset;
| &spec.private-asset; | &spec.property-specification;)*
   </literallayout>
   </figure>
  @@ -675,51 +675,18 @@
   A description may be attached to a many different elements.  Descriptions are used
   by an intelligent IDE to provide help.  The Tapestry Inspector may also display a description.
   </para>
  -
  -<warning>
  -<para>
  -The DTD supports multiple <sgmltag class="starttag">description</sgmltag> elements,
each
  -localized to a different language.  In practice, a single description, in English, is typically
  -used.  This approach to providing a localized description is likely to change in the future,
and
  -it is probably safest to expect just a single <sgmltag class="starttag">description</sgmltag>
tag
  -to be allowed in the next revision of the DTD.
  -</para>
  -</warning>
   	
   <para>
   The descriptive text appears inside the <sgmltag class="starttag">description</sgmltag>
tags.  Leading
   and trailing whitespace is removed and interior whitespace may be altered or removed. 
Descriptions
   should be short; external documentation can provide greater details.
   </para>
  -
  -<figure>
  -	<title><sgmltag class="starttag">description</sgmltag> element</title>
  -<informaltable>
  -<tgroup cols="5">
  -<thead>
  -<row>
  -  <entry>Name</entry>
  -  <entry>Type</entry>
  -  <entry>Required ?</entry>
  -  <entry>Default Value</entry>
  -  <entry>Description</entry>
  -</row>
  -
  -</thead>
  -<tbody>
  -<row>
  -	<entry>xml:lang</entry>
  -	<entry>string</entry>
  -	<entry>no</entry>
  -	<entry/>
  -	<entry>The language the message is localized to as an ISO language string.
  -	</entry>
  -</row>
  -</tbody>
  -</tgroup>
  -</informaltable>
  -</figure>
   	
  +<para>
  +The 	<sgmltag class="starttag">description</sgmltag>
  +element has no attributes.
  +</para>
  +
   </section> <!-- spec.description -->
   
   <section id="spec.extension">
  @@ -980,7 +947,7 @@
   <figure>
   	<title><sgmltag class="starttag">library-specification</sgmltag> Elements</title>
   <literallayout>
  -  &spec.description; *, &spec.property; *,
  +  &spec.description; ?, &spec.property; *,
     (&spec.page; | &spec.component-type; | &spec.service; | &spec.library;
| &spec.extension;) *
   </literallayout>
   </figure>
  @@ -1168,7 +1135,7 @@
   <figure>
   	<title><sgmltag class="starttag">page-specification</sgmltag> Elements</title>
   <literallayout>
  -  &spec.description; *, &spec.property; *,
  +  &spec.description; ?, &spec.property; *,
     (&spec.bean; | &spec.component; | &spec.external-asset; | &spec.context-asset;
| &spec.private-asset; | &spec.property-specification;)*
   </literallayout>
   </figure>
  @@ -1185,7 +1152,7 @@
   
   <para>
   Defines a formal parameter of a component.  Parameters may be connected 
  -(<literal>in</literal> or <literal>form</literal>)
  +(<literal>in</literal>, <literal>form</literal> or <literal>auto</literal>)
   or unconnected (<literal>custom</literal>).  If a parameter is
   connected, but the class does not provide the property (or does, but
   the accessors are abstract), then the framework
  @@ -1193,6 +1160,15 @@
   of the necessary property.
   </para>
   
  +<para>
  +For <literal>auto</literal> parameters, the framework will create a synthetic
property
  +as a wrapper around the binding.  Reading the property will read the value from
  +the binding and updating the property will update the binding value.  <literal>auto</literal>
  +may only be used with required parameters.  <literal>auto</literal> is less
  +efficient than <literal>in</literal>, but can be used even when the component
  +is not rendering.
  +</para>
  +
   <figure>
   	<title><sgmltag class="starttag">parameter</sgmltag> Attributes</title>
   <informaltable>
  @@ -1252,7 +1228,7 @@
   
   <row>
     <entry>direction</entry>
  -  <entry><literal>in|form|custom</literal></entry>
  +  <entry><literal>in|form|auto|custom</literal></entry>
     <entry>no</entry>
     <entry><literal>custom</literal></entry>
     <entry>
  @@ -1274,6 +1250,13 @@
     parameter when the component renders (as with <literal>in</literal>).
     When the form is submitted, the value is read from the property
     and used to set the binding value after the component rewinds.
  +  </para>
  +  
  +  <para>
  +  <literal>auto</literal> creates a synthetic property that works
  +  with the binding to read and update.  <literal>auto</literal>
  +  parameters must be required, but can be used even when the
  +  component is not rendering.
     </para>
     </entry>
   </row>
  
  
  
  1.7       +43 -6     jakarta-tapestry/doc/src/UsersGuide/configuration.xml
  
  Index: configuration.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/configuration.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- configuration.xml	6 Mar 2003 19:19:33 -0000	1.6
  +++ configuration.xml	23 Mar 2003 23:13:23 -0000	1.7
  @@ -19,6 +19,7 @@
   &lt;!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"&gt;
   &lt;web-app&gt;
  +  &lt;distributable/&gt; <co id="configuration.web.distributable"/>
     &lt;display-name&gt;Tapestry Virtual Library Demo&lt;/display-name&gt;
     &lt;servlet&gt;
       &lt;servlet-name&gt;vlib&lt;/servlet-name&gt; <co id="configuration.web.servlet-name"/>
  @@ -49,6 +50,13 @@
   </example>
   
   <calloutlist>
  +<callout arearefs="configuration.web.distributable">
  +<para>
  +This indicates to the application server that the Tapestry application may be clustered.
 Most
  +application servers ignore this element, but future servers may only distribute
  +applications within a cluster if this element is present.	
  +</para>	
  +</callout>
   <callout arearefs="configuration.web.servlet-name">
   	<para>
   	The servlet name may be used when locating the application specification (though
  @@ -429,14 +437,43 @@
   </varlistentry>
   
   <varlistentry>
  -	<term>org.apache.tapestry.value-persister (&IValuePersister;)</term>
  -
  +	<term>org.apache.tapestry.specification-resolver-delegate (&ISpecificationResolverDelegate;)</term>
  +	
   	<listitem>
   	<para>
  -	An object responsible for copying persistent page properties for storage.  If not
  -	provided, an instance of &DefaultValuePersister; is used.
  -	</para>
  +	An object which is used to find page and component specifications that are not located
  +	using the default search rules.  The use of this is open-ended, but is generally
  +	useful in very advanced scenarios where specifications are stored externally
  +	(perhaps in a database), or constructed on the fly.
  +	</para>	
   	</listitem>	
  +</varlistentry>
  +
  +<varlistentry>
  +	<term>org.apache.tapestry.template-source-delegate (&ITemplateSourceDelegate;)</term>
  +	
  +	<listitem>
  +	<para>
  +	An object which is used to find page or component templates that are not located
  +	using the default search rules. The use of this is open-ended, but is generally
  +	useful in very advanced scenarios where templates are stored externally
  +	(perhaps in a database), or constructed on the fly.
  +	</para>	
  +	</listitem>
  +</varlistentry>
  +
  +<varlistentry> 
  +<term>org.apache.tapestry.multipart-decoder (&IMultipartDecoder;)</term>
  +
  +<listitem>
  +<para>
  +Allows an alternate object to be responsible for decoding multipart requests (context
  +type multipart/form-data, used for file uploads).  Generally, this is used to
  +configure an instance of &DefaultMultipartDecoder; with non-default values for
  +the maximum upload size, threshold size (number of bytes before a temporary file is created
  +to store the) and repository directory (where temporary files are stored).	
  +</para>
  +</listitem>	
   </varlistentry>
   
   </variablelist>
  
  
  
  1.27      +8 -8      jakarta-tapestry/doc/src/common/TapestryLinks.xml
  
  Index: TapestryLinks.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tapestry/doc/src/common/TapestryLinks.xml,v
  retrieving revision 1.26
  retrieving revision 1.27
  diff -u -r1.26 -r1.27
  --- TapestryLinks.xml	6 Mar 2003 19:19:33 -0000	1.26
  +++ TapestryLinks.xml	23 Mar 2003 23:13:24 -0000	1.27
  @@ -31,6 +31,7 @@
   <!ENTITY BaseEngine '<ulink url="&ApiRoot;/engine/BaseEngine.html"><classname>BaseEngine</classname></ulink>'>
   <!ENTITY BasePage '<ulink url="&ApiRoot;/html/BasePage.html"><classname>BasePage</classname></ulink>'>
   <!ENTITY Default '<ulink url="&ApiRoot;/bean/Default.html"><classname>Default</classname></ulink>'>
  +<!ENTITY DefaultMultipartDecoder '<ulink url="&ApiRoot;/multipart/DefaultMultipartDecoder.html"><classname>DefaultMultipartDecoder</classname></ulink>'>
   <!ENTITY DefaultValuePersister '<ulink url="&ApiRoot;/record/DefaultValuePersister.html"><classname>DefaultValuePersister</classname></ulink>'>
   <!ENTITY Enum '<ulink url="&ApiRoot;/util/Enum.html"><classname>Enum</classname></ulink>'>
   <!ENTITY EnumPropertySelectionModel '<ulink url="&ApiRoot;/form/EnumPropertySelectionModel.html"><classname>EnumPropertySelectionModel</classname></ulink>'>
  @@ -46,26 +47,25 @@
   <!ENTITY IEngineService '<ulink url="&ApiRoot;/IEngineService.html"><classname>IEngineService</classname></ulink>'>
   <!ENTITY ILifecycle '<classname>ILifecycle</classname>'>
   <!ENTITY IMarkupWriter '<ulink url="&ApiRoot;/IMarkupWriter.html"><classname>IMarkupWriter</classname></ulink>'>
  -<!ENTITY IMonitor '<ulink url="&ApiRoot;/IMonitor.html"><classname>IMonitor</classname></ulink>'>
  +<!ENTITY IMonitor '<ulink url="&ApiRoot;/engine/IMonitor.html"><classname>IMonitor</classname></ulink>'>
  +<!ENTITY IMultipartDecoder '<ulink url="&ApiRoot;/multipart/IMultipartDecoder.html"><classname>IMultipartDecoder</classname></ulink>'>
   <!ENTITY IPage '<ulink url="&ApiRoot;/IPage.html"><classname>IPage</classname></ulink>'>
   <!ENTITY IPageRecorder '<ulink url="&ApiRoot;/IPageRecorder.html"><classname>IPageRecorder</classname></ulink>'>
   <!ENTITY IPropertySelectionModel '<ulink url="&ApiRoot;/form/IPropertySelectionModel.html"><classname>IPropertySelectionModel</classname></ulink>'>
  -<!ENTITY IPropertySource '<ulink url="&ApiRoot;/IPropertySource.html"><classname>IPropertySource</classname></ulink>'>
  +<!ENTITY IPropertySource '<ulink url="&ApiRoot;/engine/IPropertySource.html"><classname>IPropertySource</classname></ulink>'>
   <!ENTITY IPoolable '<ulink url="&ApiRoot;/util/pool/IPoolable.html"><classname>IPoolable</classname></ulink>'>
   <!ENTITY IRender '<ulink url="&ApiRoot;/IRender.html"><classname>IRender</classname></ulink>'>
   <!ENTITY IRequestCycle '<ulink url="&ApiRoot;/IRequestCycle.html"><classname>IRequestCycle</classname></ulink>'>
  -<!ENTITY IRequestDecoder '<ulink url="&ApiRoot;/IRequestDecoder.html"><classname>IRequestDecoder</classname></ulink>'>
  +<!ENTITY IRequestDecoder '<ulink url="&ApiRoot;/request/IRequestDecoder.html"><classname>IRequestDecoder</classname></ulink>'>
  +<!ENTITY ISpecificationResolverDelegate '<ulink url="&ApiRoot;/resolver/ISpecificationResolverDelegate.html"><classname>ISpecificationResolverDelegate</classname></ulink>'>
  +<!ENTITY ITemplateSourceDelegate '<ulink url="&ApiRoot;/engine/ITemplateSourceDelegate.html"><classname>ITemplateSourceDelegate</classname></ulink>'>
   <!ENTITY IValidator '<ulink url="&ApiRoot;/valid/IValidator.html"><classname>IValidator</classname></ulink>'>
   <!ENTITY IValidationDelegate '<ulink url="&ApiRoot;/valid/IValidationDelegate.html"><classname>IValidationDelegate</classname></ulink>'>
  -<!ENTITY IValuePersister '<ulink url="&ApiRoot;/record/IValuePersister.html"><classname>IValuePersister</classname></ulink>'>
  -<!ENTITY IField '<ulink url="&ApiRoot;/valid/IField.html"><classname>IField</classname></ulink>'>
   <!ENTITY IUploadFile '<ulink url="&ApiRoot;/IUploadFile.html"><classname>IUploadFile</classname></ulink>'>
  -<!ENTITY PageCleanupListener '<ulink url="&ApiRoot;/event/PageCleanupListener.html"><classname>PageCleanupListener</classname></ulink>'>
   <!ENTITY PageDetachListener '<ulink url="&ApiRoot;/event/PageDetachListener.html"><classname>PageDetachListener</classname></ulink>'>
   <!ENTITY PageRecorder '<ulink url="&ApiRoot;/record/PageRecorder.html"><classname>PageRecorder</classname></ulink>'>
   <!ENTITY PageRedirectException '<ulink url="&ApiRoot;/PageRedirectException.html"><classname>PageRedirectException</classname></ulink>'>
   <!ENTITY PageRenderListener '<ulink url="&ApiRoot;/event/PageRenderListener.html"><classname>PageRenderListener</classname></ulink>'>
  -<!ENTITY PropertyHelper '<classname>PropertyHelper</classname>'>
   <!ENTITY RequestContext '<ulink url="&ApiRoot;/RequestContext.html"><classname>RequestContext</classname></ulink>'>
   <!ENTITY SimpleEngine '<ulink url="&ApiRoot;/engine/SimpleEngine.html"><classname>SimpleEngine</classname></ulink>'>
   <!ENTITY SpecificationParser '<ulink url="&ApiRoot;/parse/SpecificationParser"><classname>SpecificationParser</classname></ulink>'>
  
  
  
  1.4       +2 -13     jakarta-tapestry/doc/src/DevelopersGuide/pages.xml
  
  Index: pages.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-tapestry/doc/src/DevelopersGuide/pages.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- pages.xml	11 Sep 2002 19:43:36 -0000	1.3
  +++ pages.xml	23 Mar 2003 23:13:24 -0000	1.4
  @@ -725,18 +725,7 @@
         <para>
   This cleanup occurs at the end of the request, after a response has been sent to the client
web browser.
   </para>
  -      <para>
  -Finally,  the &PageCleanupListener; is implemented by objects that need to know when
the
  -&HttpSession; is invalidated.
  -</para>
  -      <figure>
  -        <title>Page Cleanup Sequence</title>
  -        <mediaobject>
  -          <imageobject>
  -            <imagedata fileref="images/Page-Cleanup-sequence.gif" format="GIF"/>
  -          </imageobject>
  -        </mediaobject>
  -      </figure>
  +
         <para>
   The engine knows when the &HttpSession; has been invalidated because the container
will
   invoke <function>valueUnbound()</function>.  It loads and rolls back each page,
then invokes
  
  
  

Mime
View raw message