You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lenya.apache.org by an...@apache.org on 2005/04/13 14:36:15 UTC
svn commit: r161177 - in lenya/docu/src/documentation/content/xdocs:
1_4/reference/usecase-framework/abstractusecase.xml
1_4/reference/usecase-framework/index.xml site.xml
Author: andreas
Date: Wed Apr 13 05:36:14 2005
New Revision: 161177
URL: http://svn.apache.org/viewcvs?view=rev&rev=161177
Log:
added more docs on usecase framework
Added:
lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/abstractusecase.xml
Modified:
lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/index.xml
lenya/docu/src/documentation/content/xdocs/site.xml
Added: lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/abstractusecase.xml
URL: http://svn.apache.org/viewcvs/lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/abstractusecase.xml?view=auto&rev=161177
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/abstractusecase.xml (added)
+++ lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/abstractusecase.xml Wed Apr 13 05:36:14 2005
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2002-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.
+-->
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://forrest.apache.org/dtd/document-v12.dtd">
+<document>
+ <header>
+ <title>The AbstractUsecase Class</title>
+ </header>
+ <body>
+
+ <section>
+ <title>Introduction</title>
+ <p>
+ When you implement a custom usecase, you're very likely to extend
+ <code>org.apache.lenya.cms.usecase.AbstractUsecase</code>. This class provides a set of
+ functionality to simplify the implementation of usecases.
+ </p>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <p>
+ The usecase is configured in <code>cocoon.xconf</code>.
+ A typical configuration looks like this:
+ </p>
+
+<source xml:space="preserve"><![CDATA[
+<component-instance name="edit.forms" logger="lenya.publication"
+ class="org.apache.lenya.cms.editors.forms.FormsEditor">
+ <transaction policy="pessimistic"/>
+ <view template="edit/forms/forms" menu="false"/>
+</component-instance>
+]]></source>
+
+ <p>
+ The following configuration options are available:
+ </p>
+
+ <ul>
+ <li>Element <code><transaction></code> (optional)
+ <ul>
+ <li>Attribute <code>policy = (optimistic | pessimistic)</code></li>
+ </ul>
+ <br/>
+ <p>
+ This element is used to determine the transaction policy of the usecase
+ (<em>optimistic</em> or <em>pessimistic offline lock</em>). It can be omitted,
+ the default is optimistic behaviour.
+ You should only use pessimistic behaviour for complex usecases when the user
+ can't afford to lose all changes.
+ </p>
+ <br/>
+ </li>
+
+ <li>Element <code><view></code> (optional)
+ <ul>
+ <li>Attribute <code>template</code> (required)</li>
+ <li>Attribute <code>menu = (true | false)</code> (optional)</li>
+ </ul>
+ <br/>
+ <p>
+ This element declares the view of the usecase. The <code>template</code> attribute
+ points to the JX template to use, relatively to the <code>lenya/usecases</code>
+ directory. The suffix <code>.jx</code> is added automatically. The attribute <code>menu</code>
+ determines if the menu should be visible. It can be omitted and defaults to <code>false</code>.
+ </p>
+ <br/>
+ </li>
+ </ul>
+
+ </section>
+
+ <section>
+ <title>Extending AbstractUsecase</title>
+
+ <p>
+ The following methods of the <code>AbstractUsecase</code> class are meant to be overridden:
+ </p>
+
+ <ul>
+ <li>
+ <code>protected void initParameters()</code>
+ <p>
+ This method is called to initialize the parameters of the usecase. For instance, if
+ your usecase shall display meta data on the view screen, <code>initParameters()</code>
+ reads the meta data from the document and puts them into the parameter map using
+ <code>setParameter(String, Object)</code> to make them available to the JX template.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckPreconditions()</code>
+ <p>
+ The method <code>checkPreconditions()</code> is a template method which calls this
+ method. For details on <code>checkPreconditions()</code>, see section
+ <link href="index.html">Overview</link>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckExecutionConditions()</code>
+ <p>
+ The method <code>checkExecutionConditions()</code> is a template method which calls this
+ method. For details on <code>checkExecutionConditions()</code>, see section
+ <link href="index.html">Overview</link>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doCheckPostconditions()</code>
+ <p>
+ The method <code>checkPostonditions()</code> is a template method which calls this
+ method. For details on <code>checkPostonditions()</code>, see section
+ <link href="index.html">Overview</link>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected void doExecute()</code>
+ <p>
+ The method <code>execute()</code> is a template method which calls this
+ method. For details on <code>execute()</code>, see section
+ <link href="index.html">Overview</link>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>public void advance()</code>
+ <p>
+ For details on <code>advance()</code>, see section
+ <link href="index.html">Overview</link>.
+ </p>
+ <br/>
+ </li>
+
+ <li>
+ <code>protected Transactionable[] getObjectsToLock()</code>
+ <p>
+ This method is supposed to return all objects which should be locked before
+ the usecase is started. If the transaction policy is <em>pessimistic offline lock</em>,
+ these objects are checked out immediately.
+ </p>
+ <br/>
+ </li>
+
+ </ul>
+
+ </section>
+
+ </body>
+</document>
Modified: lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/index.xml
URL: http://svn.apache.org/viewcvs/lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/index.xml?view=diff&r1=161176&r2=161177
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/index.xml (original)
+++ lenya/docu/src/documentation/content/xdocs/1_4/reference/usecase-framework/index.xml Wed Apr 13 05:36:14 2005
@@ -114,10 +114,92 @@
The methods of this interface are called in a certain order when the usecase is invoked:
</p>
<ol>
- <li><code>setup(String sourceUrl, Situation situation);</code> Initializes the handler.</li>
- <li><code>isInteractive()</code> Asks is the usecase is interactive, i.e. if a confirmation screen should be presented to the user.</li>
- <li><code>checkPreconditions()</code> This allows the handler to check if the usecase may be invoked in this situation.</li>
+ <li><code>setSourceURL(String sourceUrl)</code>
+ <br/>
+ <code>setName(String)</code>
+ <p>Initialize the handler.</p>
+ <br/>
+ </li>
+ <li><code>checkPreconditions()</code>
+ <p>
+ This method is called to check the pre-conditions of the usecase. The pre-conditions
+ are checked before the usecase is started, i.e., before the first screen is presented
+ to the user. To denote that a condition does not comply, add an appropriate error message
+ using <code>addErrorMessage(String)</code>. If an error message was added, the usecase
+ is not started. Alternatively, you can provide information to the user using
+ <code>addInfoMessage(String)</code>. This doesn't prevent the usecase from being executed.
+ </p>
+ <br/>
+ </li>
+ <li><code>lockInvolvedObjects()</code>
+ <p>
+ This method is called to lock all objects which could be changed during the usecase.
+ </p>
+ <br/>
+ </li>
</ol>
+
+ <p>
+ The following methods are called in a loop while the user interacts with the usecase,
+ until a request parameter with the name <code>submit</code> was sent.
+ </p>
+
+ <ol>
+ <li><code>getView()</code>
+ <p>
+ Requests the next view to be displayed. The view may be <code>null</code> if no
+ screen should be presented to the user.
+ </p>
+ <br/>
+ </li>
+ <li><code>advance()</code>
+ <p>
+ This method is called to advance the usecase after the a user interaction.
+ In contrast to <code>execute()</code>, this method is not called when the
+ <code><input type="submit" name="submit"></code> was pressed, but for every
+ other submitting of the form. A typical usecase is the <em>multiple forms editor</em> where
+ <code>advance()</code> is used to update the document when the user switched to
+ another element.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ <p>
+ When the form is submitted using the <code><input type="submit" name="submit"></code>
+ button, the usecase is finished:
+ </p>
+
+ <ol>
+ <li><code>checkExecutionConditions()</code>
+ <p>
+ This method is called before the usecase is actually executed. A typical example
+ is the validation of form data.
+ </p>
+ <br/>
+ </li>
+ <li><code>execute()</code>
+ <p>
+ This method actually executes the final step of the usecase.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
+ <p>
+ When the form is submitted using the <code><input type="submit" name="cancel"></code>
+ button, the usecase is cancelled:
+ </p>
+
+ <ol>
+ <li><code>cancel()</code>
+ <p>
+ This method cancels the usecase. The transaction is rolled back.
+ </p>
+ <br/>
+ </li>
+ </ol>
+
</section>
<section>
Modified: lenya/docu/src/documentation/content/xdocs/site.xml
URL: http://svn.apache.org/viewcvs/lenya/docu/src/documentation/content/xdocs/site.xml?view=diff&r1=161176&r2=161177
==============================================================================
--- lenya/docu/src/documentation/content/xdocs/site.xml (original)
+++ lenya/docu/src/documentation/content/xdocs/site.xml Wed Apr 13 05:36:14 2005
@@ -57,7 +57,10 @@
<reference href="reference/" label="Technical Reference">
<sitemaps14 href="lenya-sitemaps.html" label="Overview of Lenya Sitemaps" />
- <usecase-framework-index href="usecase-framework/index.html" label="Usecase Framework"/>
+ <usecase-framework href="usecase-framework/" label="Usecase Framework">
+ <usecase-framework-overview href="index.html" label="Overview"/>
+ <abstractusecase href="abstractusecase.html" label="AbstractUsecase"/>
+ </usecase-framework>
<publication-templating href="publication-templating/index.html" label="Publication Templating"/>
</reference>
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@lenya.apache.org
For additional commands, e-mail: commits-help@lenya.apache.org