You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/10/05 17:45:07 UTC
svn commit: r582318 - in /myfaces/orchestra/trunk/core/src/site/xdoc:
alternative-configuration.xml bestPractice.xml component-bindings.xml
conversation.xml faqs.xml glossary.xml installation.xml
Author: skitching
Date: Fri Oct 5 08:45:05 2007
New Revision: 582318
URL: http://svn.apache.org/viewvc?rev=582318&view=rev
Log:
Update orchestra core site docs.
Modified:
myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml
myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml
myfaces/orchestra/trunk/core/src/site/xdoc/component-bindings.xml
myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml
myfaces/orchestra/trunk/core/src/site/xdoc/faqs.xml
myfaces/orchestra/trunk/core/src/site/xdoc/glossary.xml
myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml Fri Oct 5 08:45:05 2007
@@ -22,7 +22,7 @@
<document>
<properties>
- <title>Installation</title>
+ <title>Apache MyFaces Orchestra - Alternative Configuration</title>
</properties>
<body>
@@ -68,7 +68,7 @@
<bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
<property name="scopes">
<map>
- <entry key="conversation">
+ <entry key="conversation.flash">
<bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope">
<property name="advices">
<list>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml Fri Oct 5 08:45:05 2007
@@ -21,121 +21,128 @@
-->
<document>
<properties>
- <title>Best Practice</title>
+ <title>Apache MyFaces Orchestra - Best Practice</title>
</properties>
<body>
<section name="Best Practice">
- This page will provide you with guidance to best practices
- in using Apache MyFaces Orchestra - generally, it's better to
- adhere to these principles.
+ This page contains information on how the Orchestra developers believe Orchestra
+ is best used. As always, best practices evolve - see the wiki for the latest
+ information.
- <subsection name="Single Page Conversation">
+ <subsection name="Single Page Conversation With Flash Scope">
<p>
- In many cases, it is the easiest approach to
- provide a single managed bean per view.
- Single Page conversations are easy - put the bean representing your view controller
- into the conversation scope und use it in your value-/methodbinding.
- Additionally, there is a module in Orchestra which will provide convenient functionality
- en plus - for that, you need to set the managed-bean name to the page-name.
- <b>Notice:</b> See the ViewController documentation on how to use other naming strategies and so to adjust the mapping
- from the view-id to your bean names.
+ Write a single managed bean for the view. Configure this bean as belonging
+ to an unnamed "flash" conversation scope and reference it as normal from
+ your presentation pages (jsp, facelets, clay, etc).
</p>
<p>
- The conversation will be started when the bean is first accessed,
- it's your job to end the conversation by calling
- <code>Conversation.getCurrentInstance().invalidate()</code>. You'll do that mostly in save actions
- after you have saved data to the database.
- Eventually, you might want to restart the conversation to provide access to the data again.
- <code>Object yourBackingBean = ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance())</code>
- </p>
-
- <p>
- Often, the user will also be allowed to cancel the current work,
- in which case Orchestra will simply close the conversation
- (without commit to the database). For achieving this, simply call:
- <code>Conversation.getCurrentInstance().invalidate()</code>
- without having called any persistence-layer save-methods before.
+ The conversation will be started when the bean is first accessed, and will
+ automatically be terminated when navigation to some other page occurs
+ (well, technically when a page is rendered that does not reference this
+ managed bean). If you have an action method that wants to "start fresh"
+ while remaining at the same view, then from the action method call
+ ConversationUtils.invalidateAndRestartCurrent() to discard the current
+ conversation.
</p>
+ <p>
+ If this bean is named to match the view that it is backing
+ (eg beanname="edit" for the "/edit" viewid), then it is trivial
+ to get "lifecycle events" from Orchestra's ViewController. See the
+ ViewController documentation for more information on this.
+ </p>
+
</subsection>
- <subsection name="Multi Page Conversation">
+ <subsection name="Multi Page Conversation With Flash Scope">
<p>
- For multi page conversations you have to break through the first suggestion ;-) which means
- that it is not possible to have a conversation bean with the same name as the multitude of pages,
- a bean can of course have a single name only.
- </p>
-
- <p>
- The solution for this is to use a simple request scoped bean per page
- and a single conversation scoped controller.<br />
- If you have three pages, e.g. startPage.jsp, enterPage.jsp, endPage.jsp you'll end up
- with a structure like (note: the bean names are suggestions only):
+ Use one flash-scoped controller for the whole conversation, plus one simple
+ request-scoped bean per view. For example, if you have three pages then structure
+ things as follows:
<ul>
- <li>Page:startPage.jsp</li>
- <li>Page:enterPage.jsp<br/>Bean name: enterPage</li>
- <li>Page:endPage.jsp<br/>Bean name: endPage</li>
- <li>Conversation bean name: pagesController</li>
+ <li>Page:purchaseStep1.jsp</li>
+ <li>Page:purchaseStep2.jsp<br/>Bean name: purchaseStep2</li>
+ <li>Page:purchaseStep3.jsp<br/>Bean name: purchaseStep3</li>
+ <li>Conversation bean name: purchaseController</li>
</ul>
</p>
- <p>
- As you can see, there is no bean required for the startPage. We require the enterPage and endPage beans
- to check if the conversation is really running.
+ <p>
+ The request-scoped beans are used only to check whether the conversation is really running; this avoids
+ problems when users leap into the middle page of a sequence (eg via a bookmark). EL expressions in
+ all of the pages reference the purchaseController object, not the request-scoped beans.
</p>
<p>
- We have to ensure that the user starts with the startPage. Reasons why this might be violated are:
+ We have to ensure that the user starts with the start page. Reasons why this might be violated are:
<ul>
<li>the conversation timed out in the mid of the work</li>
<li>the user tampered with the url</li>
</ul>
- </p>
-
- <p>
- Now that we have a mini backing bean for the enterPage and the endPage we can put in code
- to ensure a running conversation. If the conversation has not been started we issue a redirect
- or execute the JSF navigation system.
- </p>
-
- <p>
To ensure a running conversation, simply add a method called <code>initView()</code>
- to the enterPage and endPage bean which looks like the
- following:
+ to the purchaseStep2 and purchaseStep3 beans which looks like the following:
<pre>
public void initView()
{
ConversationUtils.ensureConversationRedirect("pagesController", "/startPage.faces");
}
- </pre>
-
- <b>Notice:</b> There is also a <code>JsfConversationUtils</code>-class which allows you to invoke a navigation.<br/>
-
+ </pre>
+
+ As noted above, Orchestra's ViewController will invoke "lifecycle events" for a view
+ onto any bean that has a "matching name". Because the request-scoped beans above have
+ names that match the viewid, the initView method on the appropriate bean is called
+ when a request for that view is received, and a check can be made for the existence
+ of the right conversation. Without this check, when a user leaps into the middle
+ of a conversation, EL expressions will trigger the creation of the missing
+ purchaseController (and its associated conversation) but the bean probably does
+ not have the appropriate state to render the page correctly.
+ </p>
+
+ <p>
+ There is no need for a bean to back the first page (purchaseStep1) because it is
+ perfectly valid for the user to enter that page with no existing conversation.
+ </p>
+
+ <p>
+ <b>Notice:</b> There is also a <code>JsfConversationUtils</code>-class which allows
+ you to invoke a navigation rule rather than encoding a url in the call to
+ method ensureConversationRedirect.
</p>
<p>
- TODO - prepare a method to make this more
- developer friendly, implement this in Orchestra and document it here.
- However, for a nice solution it looks like we can't
- avoid the introduction of an annotation based solution
- which will optionally be available if you add the core15 module.
+ An alternative to declaring "dummy beans" just to receive lifecycle callbacks
+ is to customise the way the ViewController maps viewids to beannames. In
+ particular, see the ViewController annotations from the Orchestra core15 module.
</p>
-
</subsection>
+ <subsection name="Multi Page Conversation With Manual Scope">
+
+ <p>
+ In some cases a conversation should not terminate until page N has been visited,
+ but in the middle a user can go off and visit a page that has no references to
+ any managed beans within the main conversation. When using Flash scopes, Orchestra
+ will interpret a visit to such as page as the user "abandoning" the conversation,
+ so the conversation will be discarded. In this case, use a manual scoped conversation,
+ ie one that must be explicitly ended via either a JSF component (ox:endConversation)
+ or a call to the Orchestra API from an action method. Use flash scopes where possible,
+ though - they are less work.
+ </p>
+
+ </subsection>
+
<subsection name="Component bindings">
<p>
- Read something about <a href="component-bindings.html">component binding and the scoping problem</a>.
- </p>
- <p>
- This document is not related to Apache MyFaces Orchestra. It's a good reading for every JSF developer.
+ We recommend you read about <a href="component-bindings.html">component binding and the scoping problem</a>.
+ This document is not specifically about Apache MyFaces Orchestra, but the same issues apply when dealing
+ with component-bindings and conversation-scoped beans.
</p>
</subsection>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/component-bindings.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/component-bindings.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/component-bindings.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/component-bindings.xml Fri Oct 5 08:45:05 2007
@@ -22,7 +22,7 @@
<document>
<properties>
- <title>Apache MyFaces Orchestra - Component Bingings</title>
+ <title>Apache MyFaces Orchestra - Component Bindings</title>
</properties>
<body>
@@ -38,7 +38,7 @@
</subsection>
<subsection name="Problem">
The main problem is that component bindings need to be in a request-scoped backing-bean.
- The cause is that the component tree is regenerated at every request. Longer component bindings
+ The component tree is regenerated at every request. Longer component bindings
are a possible cause for internal id clashes etc...
<p> </p>
Now with what we have advocated so far, we have a single page controller/model object which is associated
@@ -79,7 +79,7 @@
<aop:scoped-proxy />
</bean>
-<bean id="viewcontrollerbean" scope="conversation" ...>
+<bean id="viewcontrollerbean" scope="conversation.flash" ...>
<property name="componentbindingmodel"
ref="componentbindingmodel" />
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml Fri Oct 5 08:45:05 2007
@@ -22,11 +22,11 @@
<document>
<properties>
- <title>The Conversation Scope problem</title>
+ <title>Apache MyFaces Orchestra - The Conversation Scope Problem</title>
</properties>
<body>
- <section name="The Conversation Scope problem">
+ <section name="The Conversation Scope Problem">
<p>
Often a logical operation consists of multiple JSF requests to the server.
For example, purchasing an insurance policy requires completing a number
@@ -85,15 +85,22 @@
This solution works across all JSF implementations (particularly Apache MyFaces and
the Sun Reference Implementation). It works for Java 1.4 or later. If java1.5 is
being used then custom annotations are available to make its use even easier.
- This solution does require that the Spring Framework be used to declare
- conversation-scoped managed beans rather than the standard JSF facility. However
- there are many other good reasons to use Spring...
</p>
<p>
- Various other projects (JBoss Seam, Apache Shale Dialogs) provide
- conversation/dialog support that is similar to Orchestra. See
- the Orchestra wiki pages for up-to-date comparisons of Orchestra with other projects.
+ Orchestra does require conversation-scoped managed beans to be declared via a good
+ dependency-injection (aka IOC) framework with AOP support. The standard JSF
+ managed-beans facility does not provide sufficient flexibility. While it should be
+ possible for Orchestra to be integrated with any appropriate such framework it
+ initially supports only Spring 2.x. This is no great drawback as there are many
+ other good reasons to use Spring! In the remainder of this document we shall
+ assume Spring is the dependency-injection framework being used.
+ </p>
+
+ <p>
+ Various other projects (JBoss Seam, Apache Shale Dialogs, Spring WebFlow) provide
+ conversation/dialog support that is similar to Orchestra. See the Orchestra wiki pages
+ for up-to-date comparisons of Orchestra with other projects.
</p>
</section>
@@ -125,9 +132,9 @@
difficult to achieve with simple session storage. A conversation can be
terminated in a number of ways:
<ul>
+ <li><p>flash conversations end when a request occurs that does not access any bean in that conversation;</p></li>
<li><p>a JSF endConversation component is provided that can be inserted into a page;</p></li>
<li><p>a direct call can be made from a backing bean, eg after performing a "save" or "cancel" operation;</p></li>
- <li><p>flash conversations end when a request occurs that does not access any bean in that conversation;</p></li>
<li><p>a conversation timeout can be configured to automatically expire conversations after a specified time limit.</p></li>
</ul>
And as conversations have names, multiple conversations (bean groupings) can exist concurrently.
@@ -140,7 +147,7 @@
</p>
<p>
- A conversation can have a "policy" of "manual" or "flash".
+ A conversation can have a "policy" of "flash" or "manual".
A "flash" conversation is automatically ended (ie deleted) if a request is executed
which does not reference any bean in that conversation's scope. This is
very convenient when a sequence of pages all have at least one reference
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/faqs.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/faqs.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/faqs.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/faqs.xml Fri Oct 5 08:45:05 2007
@@ -22,7 +22,7 @@
<document>
<properties>
- <title>FAQs</title>
+ <title>Apache MyFaces Orchestra - FAQs</title>
</properties>
<body>
@@ -44,15 +44,12 @@
one environment where this happened, so here the work-around.
</p>
<p>
- To activate the workaround simply put the following code to your spring config and adjust the
+ To activate the workaround simply put the following code in your spring config and adjust the
names as required.
<pre>
<bean id="managedDataSource" class="org.apache.myfaces.orchestra.connectionManager.ConnectionManagerDataSource">
<property name="dataSource" ref="dataSource"/>
- <property name="listeners">
- <bean class="org.apache.myfaces.examples.lib.LoggingConnectionManagerListener"/>
- </property>
</bean>
</pre>
@@ -61,23 +58,10 @@
You have to configure
<ul>
- <li>
- the property <code>dataSource</code> to point to the original datasource and
- </li>
- <li>
- the JPA configuration to use our <code>managedDataSource</code> (adjust the name if required)
- </li>
+ <li><p>the property <code>dataSource</code> to point to the original datasource and</p></li>
+ <li><p>the JPA configuration to use our <code>managedDataSource</code> (adjust the name if required)</p></li>
</ul>
-
- <br />
-
- The property <code>listeners</code> is fully optional. It allows you to configure a listener
- which will be called on each borrow or release of a connection to do some database stuff, e.g.
- login/logout from a legacy database system, or to set the database client info, etc. <br/>
- Provide a class implementing the <code>org.apache.myfaces.orchestra.connectionManager.ConnectionManagerListener</code>
- interface, or even better inherit from <code>org.apache.myfaces.orchestra.connectionManager.AbstractConnectionManagerListener</code>.
</p>
-
</subsection>
<subsection name="PropertyPlaceholderConfigurer STOPS working after the introduction of orchestra into my configuration">
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/glossary.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/glossary.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/glossary.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/glossary.xml Fri Oct 5 08:45:05 2007
@@ -22,7 +22,7 @@
<document>
<properties>
- <title>About Apache MyFaces Orchestra</title>
+ <title>Apache MyFaces Orchestra - Glossary</title>
</properties>
<body>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml?rev=582318&r1=582317&r2=582318&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml Fri Oct 5 08:45:05 2007
@@ -22,11 +22,12 @@
<document>
<properties>
- <title>Installation</title>
+ <title>Apache MyFaces Orchestra - Installation</title>
</properties>
<body>
- <section name="Installation">In the following, we will assume that you know how to setup
+ <section name="Installation">
+ In the following, we will assume that you know how to setup
<ul>
<li>a servlet container (Tomcat, Jetty, etc)</li>
@@ -43,14 +44,15 @@
of kickstarting you in the world of JSF, Spring and JPA and then return back to include Apache
Orchestra.
</p>
- The installation guide will show you how
- to setup a JPA entity manager for Orchestra (so you are working with the new JavaPersistence API standard),
- later a chapter explaining how to access Hibernate directly will be added.
+ The installation guide will show you how to setup a JPA entity manager for Orchestra (so you are
+ working with the new JavaPersistence API standard). Later we hope to add chapters on integrating
+ directly with Hibernate and Toplink.
+
<subsection name="Prerequisites">
<ul>
<li>Apache MyFaces Orchestra core</li>
- <li>Apache MyFaces Orchestra core15</li>
+ <li>Apache MyFaces Orchestra core15 (optional; requires java1.5 or later)</li>
<li>Spring 2.x</li>
@@ -70,18 +72,20 @@
</li>
</ul>
</subsection>
- <subsection name="Spring configuration">Apache MyFaces
- Orchestra uses the powerful Spring framework to provide its conversation
- scope.
- Spring is - just like JSF managed-bean facility which is configured in the faces-config files of
- your application - a dependency injection framework.
- Up and above the features of the managed-bean facility, Spring offers very nice additional features;
- essential for Apache Orchestra is that it allows us to create a new scope-type.
- <p>Lets start with the Spring configuration for the conversation
- scope and the JPA entity-manager factory. This configuration file has to
- be placed into the WEB-INF directory of your web application using the
- name applicationContext.xml. This can be configured with a context-parameter in your web.xml; for
- more information, take a look at the Spring documentation.
+
+ <subsection name="Spring configuration">
+ <p>
+ Apache MyFaces Orchestra uses the powerful Spring framework to provide its conversation scope.
+ Spring is a dependency injection framework - just like the JSF managed-bean facility which
+ is configured in the faces-config files of traditional JSF applications.
+ However Spring offers many very nice additional features, including some that are
+ essential for Apache Orchestra. In particular it allows us to create a new scope-type.
+ </p>
+ <p>
+ Lets start with the Spring configuration for the conversation scope and the JPA entity-manager
+ factory. This configuration file has to be placed into the WEB-INF directory of your web
+ application using the name applicationContext.xml. This can be configured with a
+ context-parameter in your web.xml; for more information, take a look at the Spring documentation.
</p>
<pre>
<?xml version="1.0" encoding="UTF-8"?>
@@ -129,7 +133,7 @@
</property>
</bean>
- <!-- 3. the "entitiy manager" manager -->
+ <!-- 3. the "entity manager" manager -->
<bean id="persistentContextConversationInterceptor"
class="org.apache.myfaces.orchestra.conversation.spring.PersistenceContextConversationInterceptor">
<property name="persistenceContextFactory" ref="persistentContextFactory"/>
@@ -137,7 +141,7 @@
<!-- 4. conversation - persistence adapter -->
<bean id="persistentContextFactory"
- class="org.apache.myfaces.orchestra.conversation.persistenceContexts.JpaPersistenceContextFactory">
+ class="org.apache.myfaces.orchestra.conversation.spring.JpaPersistenceContextFactory">
<property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean>
@@ -182,27 +186,19 @@
<li>2. the conversation scope
<br/>
Here we configure the conversation
- scope as a Spring custom scope. This configuration allows us to use
- scope="conversation" with our beans. This scope implementation also
- allows you to configure a number of advices. Advices intercept each
- method call to your bean. We build on this mechanism to configure the
- entity manager appropriately.
- <br />
- We also configure a "flash" scope which allows us to keep beans as long
- as a page has a reference to it. Once a page has been rendered
- and the bean were not accessed it will be destroyed - the conversation
- automatically ends.
+ scope as a Spring custom scope. This configuration allows us to use scope="conversation.flash"
+ or scope="conversation.manual" with our beans. This scope implementation also allows you to
+ configure a number of advices. Advices intercept each method call to your bean. We build on
+ this mechanism to configure the entity manager appropriately.
<br/>
- If your application does not have to
- deal with persistence, and you would still like to use the conversation
- scope you can delete the advices from this configuration.
+ If your application does not have to deal with persistence, and you would still like to use
+ the conversation scopes you can delete the advices from this configuration.
<br />
Optionally you can configure the timeout used to automatically end a conversation.
- <br />
The <code>timeout</code> property accepts a numeric value which means a timespan
in minutes.
<br />
- Notice: <b>Without this timeout configration the conversation won't die if you do
+ Notice: <b>Without this timeout configuration, a manual conversation won't die if you do
not explicitly end it using the conversation API.</b>
</li>