FAQ
Author: lu4242
Date: Tue Apr 17 01:29:52 2012
New Revision: 1326868

URL: http://svn.apache.org/viewvc?rev=1326868&view=rev
Log:
reorganize orchestra documentation

Added:
myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml (with props)
myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml (with props)
Removed:
myfaces/orchestra/trunk/core/src/site/site.xml
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/implementation.xml
myfaces/orchestra/trunk/core/src/site/xdoc/installation.xml
myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
myfaces/orchestra/trunk/core/src/site/xdoc/multiwindow.xml
myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml
myfaces/orchestra/trunk/core/src/site/xdoc/todo.xml
myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml
myfaces/orchestra/trunk/core/src/site/xdoc/viewController.xml
Modified:
myfaces/orchestra/trunk/maven/src/site/site.xml

Modified: myfaces/orchestra/trunk/maven/src/site/site.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/site.xml?rev=1326868&r1=1326867&r2=1326868&view=diff
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/site.xml (original)
+++ myfaces/orchestra/trunk/maven/src/site/site.xml Tue Apr 17 01:29:52 2012
@@ -89,6 +89,27 @@

<menu name="Documentation" inherit="top">
<item name="Wiki" href="http://wiki.apache.org/myfaces/Orchestra" />
+ <item name="Introduction" href="./introduction.html"/>
+ <item name="Conversations" href="./conversation.html"/>
+ <item name="Persistence" href="./persistence.html"/>
+ <item name="Implementation" href="./implementation.html"/>
+ <item name="Multiple Windows" href="./multiwindow.html"/>
+ <item name="Installation" href="./installation.html"/>
+ <item name="Conversation API Usage" href="./usage.html"/>
+ <item name="ViewController" href="./viewController.html"/>
+ <item name="Best Practice" href="./bestPractice.html"/>
+ <item name="JSF Component Bindings" href="./component-bindings.html"/>
+ <item name="TODO" href="./todo.html"/>
+ <item name="FAQs" href="./faqs.html"/>
+ <item name="Glossary" href="./glossary.html"/>
+ </menu>
+
+ <menu name="Release Notes">
+ <item name="Core 1.1" href="http://svn.apache.org/repos/asf/myfaces/orchestra/tags/core-1_1/RELEASE-NOTES.txt"/>
+ <item name="Core 1.2" href="http://svn.apache.org/repos/asf/myfaces/orchestra/tags/core-1_2/RELEASE-NOTES.txt"/>
+ <item name="Core 1.3" href="http://svn.apache.org/repos/asf/myfaces/orchestra/tags/core-1_3/RELEASE-NOTES.txt"/>
+ <item name="Core 1.3.1" href="http://svn.apache.org/repos/asf/myfaces/orchestra/tags/core-1_3_1/RELEASE-NOTES.txt"/>
+ <item name="Core 1.4" href="http://svn.apache.org/repos/asf/myfaces/orchestra/tags/core-1_4/RELEASE-NOTES.txt"/>
</menu>

<menu ref="reports" inherit="top"/>

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - Alternative Configuration</title>
+ </properties>
+
+ <body>
+ <section name="Installation">
+ The following configuration provides a blueprint for
+ a single Tomcat installation using Spring 2.0, jpa ri
+ and runtime weaving.
+
+ <subsection name="Prerequisites">
+
+ <ul>
+ <li>Prerequisites - Knowledge: Basic Spring 2.0 configuration knowledge, knowledge about
+ the jpa ri, to the level that knowing what runtime weaving is can be assumed.
+ </li>
+ <li>Prerequisites - JDK Versions: JDK 5+ (on non Sun JDKs a working runtime weaving on 5
+ or a 6+ non Sun JDK)</li>
+ <li>Tomcat: 5.5+</li>
+ <li>Spring 2.x+</li>
+ </ul>
+ </subsection>
+ <subsection name="Spring configuration">
+ The following configuration uses runtime weaving, and
+ a connection pool. It should work on most Tomcat configurations.
+
+
+ <pre>
+ &lt;?xml version="1.0" encoding="UTF-8"?&gt;
+ &lt;beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:tx="http://www.springframework.org/schema/tx"
+ xmlns:aop="http://www.springframework.org/schema/aop"
+ xmlns:sa="https://spring-annotation.dev.java.net/context"
+
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
+ http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.0.xsd
+ http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.0.xsd"
+ &gt;
+
+ &lt;tx:annotation-driven transaction-manager="transactionManager" /&gt;
+ &lt;bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/&gt;
+
+ &lt;bean class="org.springframework.beans.factory.config.CustomScopeConfigurer"&gt;
+ &lt;property name="scopes"&gt;
+ &lt;map&gt;
+ &lt;entry key="conversation.access"&gt;
+ &lt;bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope"&gt;
+ &lt;property name="advices"&gt;
+ &lt;list&gt;
+ &lt;ref bean="persistentContextConversationInterceptor" /&gt;
+ &lt;/list&gt;
+ &lt;/property&gt;
+ &lt;/bean&gt;
+ &lt;/entry&gt;
+ &lt;/map&gt;
+ &lt;/property&gt;
+ &lt;/bean&gt;
+
+ &lt;bean id="thedataSource" class="org.apache.commons.dbcp.BasicDataSource"&gt;
+ &lt;property name="driverClassName" value="org.h2.Driver" /&gt;
+ &lt;property name="url"
+ value="jdbc:h2:/DATA/dummydatabase;MODE=MYSQL" /&gt;
+
+ &lt;property name="username" value="theusername" /&gt;
+ &lt;property name="password" value="thepassword" /&gt;
+
+ &lt;property name="initialSize"&gt;
+ &lt;value&gt;2&lt;/value&gt;
+ &lt;/property&gt;
+ &lt;property name="maxActive"&gt;
+ &lt;value&gt;100&lt;/value&gt;
+ &lt;/property&gt;
+ &lt;property name="maxIdle"&gt;
+ &lt;value&gt;2&lt;/value&gt;
+ &lt;/property&gt;
+ &lt;/bean&gt;
+
+ &lt;bean id="entityManagerFactory"
+ class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
+
+ &lt;property name="dataSource" ref="thedataSource" /&gt;
+ &lt;property name="jpaDialect"&gt;
+ &lt;bean class="org.springframework.orm.jpa.vendor.TopLinkJpaDialect" /&gt;
+ &lt;/property&gt;
+ &lt;property name="jpaVendorAdapter"&gt;
+ &lt;bean
+ class="org.springframework.orm.jpa.vendor.TopLinkJpaVendorAdapter"&gt;
+ &lt;property name="showSql" value="false" /&gt;
+ &lt;property name="generateDdl" value="true" /&gt;
+ &lt;property name="databasePlatform" value="oracle.toplink.essentials.platform.database.MySQL4Platform" /&gt;
+ &lt;/bean&gt;
+ &lt;/property&gt;
+
+ &lt;property name="jpaProperties"&gt;
+
+ &lt;props&gt;
+ &lt;prop key="toplink.logging.level"&gt;INFO&lt;/prop&gt;
+ &lt;prop key="toplink.target-database"&gt;oracle.toplink.essentials.platform.database.MySQL4Platform&lt;/prop&gt;
+ &lt;prop key="toplink.ddl-generation"&gt;create-tables&lt;/prop&gt;
+ &lt;prop key="toplink.cache.type.default"&gt;HardWeak&lt;/prop&gt;
+ &lt;prop key="toplink.cache.size.default"&gt;5000&lt;/prop&gt;
+ &lt;/props&gt;
+ &lt;/property&gt;
+ &lt;property name="loadTimeWeaver"&gt;
+ &lt;bean
+ class="org.springframework.instrument.classloading.InstrumentationLoadTimeWeaver" /&gt;
+ &lt;/property&gt;
+ &lt;/bean&gt;
+
+ &lt;bean id="transactionManager"
+ class="org.springframework.orm.jpa.JpaTransactionManager"&gt;
+ &lt;property name="entityManagerFactory"
+ ref="entityManagerFactory" /&gt;
+
+ &lt;/bean&gt;
+
+ &lt;bean id="jpaPersistentContextFactory" class="org.apache.myfaces.orchestra.conversation.persistenceContexts.JpaPersistenceContextFactory"&gt;
+ &lt;property name="entityManagerFactory" ref="entityManagerFactory" /&gt;
+ &lt;/bean&gt;
+ &lt;bean id="persistentContextConversationInterceptor" class="org.apache.myfaces.orchestra.conversation.spring.PersistenceContextConversationInterceptor"&gt;
+ &lt;property name="persistenceContextFactory" ref="jpaPersistentContextFactory" /&gt;
+ &lt;/bean&gt;
+
+ &lt;/beans&gt;
+ </pre>
+
+ This configuration enables load time weaving of the orm classes and thus allows
+ lazy instantiation of classes. The main issue with this configuration is, that
+ Tomcat still needs a javaagent passed down as parameter. If this is not done
+ the loadtime weaving ultimately will fail.
+ the required javaagent is:
+ <pre>
+-javaagent:&lt;path to the spring weavers&gt;/weavers/spring-agent.jar
+ </pre>
+ There are weaverless configurations as well, in spring 2.0.2 it was not yet possible to enable
+ them for jpa and Tomcat. This situation might change soon, please refer to the Spring documentation
+ for additional information on how to enable the loadtime weaving of jpa classes.
+
+ </subsection>
+ <subsection name="Key differences to the original configuration">
+ Following key differences can be found:
+ <ul>
+ <li> Load time weaving enabled via: &lt;property name="loadTimeWeaver"&gt; </li>
+ <li> A connection pool was used instead of a plain jdbc connection </li>
+ <li> Tomcat has to be started with an appropriate javaagent statement </li>
+ </ul>
+ </subsection>
+
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/alternative-configuration.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,227 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+ <document>
+ <properties>
+ <title>Apache MyFaces Orchestra - Best Practice</title>
+ </properties>
+
+ <body>
+ <section name="Best Practice">
+
+ 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 With Access Scope">
+
+ <p>
+ This applies when you have a single page that the user may submit multiple times
+ (eg select an item from a list and click a button, then select a different item
+ and click another button). The state of the page changes after each submit, but
+ this state must be held in memory.
+ </p>
+
+ <p>
+ Write a single managed bean for the view. Configure this bean as belonging
+ to an unnamed access-scoped conversation 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, and will
+ automatically be terminated (ie the bean will be deleted) 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. Even if
+ the bean-name does not match the view, there are ways of configuring
+ things so it still receives the appropriate callbacks. See the
+ ViewController documentation for more information on this.
+ </p>
+
+ </subsection>
+
+ <subsection name="Multi Page Conversation With Access Scope">
+ <p>
+ This applies when you have a set of pages that cooperate together to interact
+ with the user, but where the state used by these pages must be held in memory.
+ Commonly, sequences of pages like this eventually lead to a "save" or "execute"
+ button which then performs an action using the state that was set up by the user
+ via the preceding pages. Such sequences are sometimes called a "wizard".
+ </p>
+
+ <p>
+ Use one access-scoped controller for the whole conversation, plus one simple
+ request-scoped or access-scoped bean per view. For example, if you have three
+ pages then structure things as follows:
+
+ <ul>
+ <li>Page:purchaseStep1.jsp<br/>Bean name: purchaseStep1</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>
+ Generally, there is no need to specify a conversationName attribute for these beans,
+ ie the name of the conversation they are in is the same as the name of the bean.
+ </p>
+ <p>
+ The per-view beans handle logic and state that is specific to that page. If there is state needed
+ for the page, then use "access" scope, otherwise use "request" scope. Inject the controller bean
+ into each per-view bean so that state and logic which is shared between views can be accessed.
+ </p>
+ <p>
+ If there is common logic that each page shares, then that can be defined in an abstract base bean
+ which the per-view beans extend.
+ </p>
+ <p>
+ EL expressions in the pages can reference either the per-view bean or the common controller bean,
+ whichever is appropriate.
+ </p>
+ <p>
+ There are two problems with workflows:
+ <ul>
+ <li>
+ <p>
+ A conversation may timeout in the middle of a conversation
+ (eg the user goes to lunch, then tries to continue on return), and
+ </p>
+ </li>
+ <li>
+ <p>
+ A user may try to leap into the middle of a conversation (eg via a bookmark)
+ </p>
+ </li>
+ </ul>
+ With the above recommended structure, each per-view bean except the first one can then
+ check whether the conversation exists and is in an appropriate state for that view.
+ If not, then a navigation to the proper "entry page" for the conversation can be done.
+ </p>
+ <p>
+ The basic check for the existence of the conversation is fairly simple to do in java code:
+ <pre>
+public void initView()
+{
+ ConversationUtils.ensureConversationRedirect("purchaseController", "/purchaseStep1.jsf");
+}
+ </pre>
+ If a set of per-view beans share a common base class then this initView method can be
+ added to the base class, then overridden only in the page that is redirected to
+ ("purchaseStep1.jsp" in this example) to prevent circular redirects. This then protects
+ all of the pages from access without a correctly initialised conversation.
+ </p>
+
+ <p>
+ There is one issue: after redirect it would sometimes be nice to display an error
+ message indicating *why* the redirect happened, eg "Invalid Conversation State". This
+ is not easy on a redirect. A forward would be easier to handle, as that data could
+ be placed in request scope.
+ </p>
+ <p>
+ 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>
+ The orchestra core15 module provides the @ConversationRequire annotation to make this even easier.
+ </p>
+
+ <p>
+ Note that this works even when the purchaseController bean (which is in the purchaseController
+ conversation, unless otherwise configured) is injected into the per-view bean. The object
+ injected is actually a proxy, so the conversation is not created until the bean is really
+ referenced.
+ </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>
+ If the views in a workflow are so simple that there is no logic or state needed, then
+ rather than declaring "dummy beans" just to receive lifecycle callbacks the way the
+ ViewController maps viewids to beannames can be configured. In particular, see the
+ ViewController annotations from the Orchestra core15 module. Having a separate bean
+ for the "entry page" of a workflow is always a good idea however.
+ </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 Access 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 access scopes where possible,
+ though - they are less work.
+ </p>
+
+ </subsection>
+
+ <subsection name="Avoid Session Scope">
+ <p>
+ In almost all cases, using Session scope is a bad idea. All sorts of data goes into
+ sessions, including data from UI frameworks, and sometimes from the servlet engine
+ itself. Instead of using session-scope, put all such beans into a single conversation
+ scope called "session". The most significant benefit from this is that Orchestra's
+ "conversation context" feature now allows a user to open multiple windows to your
+ app without problems; each window has a different "conversation context", and each
+ "conversation context" has a completely independent set of conversations - including
+ all the beans in the "session" conversation. It's almost like the user connecting
+ from two different machines - except that any application login (authentication)
+ data is shared.
+ </p>
+ <p>
+ There are a few places where real session-scoped data might be appropriate, but not
+ many. Think whether two separate browser windows for a user really should share that
+ data. And if they should, then make sure that the shared objects are thread-safe, as
+ two concurrent requests from two different windows will be using the same instance.
+ </p>
+ </subsection>
+
+ <subsection name="Component bindings">
+ <p>
+ 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>
+
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/bestPractice.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - Component Bindings</title>
+ </properties>
+
+ <body>
+ <section name="Component Bindings">
+ <subsection name="Introduction">
+ <subsubsection name="Basic discrepancy">
+ <p>
+ JSF components interact with backing beans. However the lifecycles of these two types of
+ objects are very different; beans may last just a request, or longer (eg a session bean).
+ A component logically may last a number of page views, but physically new instances are
+ created for each request, when the view is "restored".
+ </p>
+ <p>
+ JSF is designed so that in normal cases views "pull" data from backing beans, "push" data entered by the
+ user into backing beans, and "invoke" event-handler methods on backing beans. In all cases, the dependency
+ is unidirectional: views know about beans, but beans do not know about views. And the coupling is done
+ only via EL strings, not hard references. This means that the lifecycles of the view components and
+ the backing beans they reference are decoupled, and the lifecycle mismatch is not an issue.
+ </p>
+ <p>
+ However JSF does provide a mechanism for backing beans to access view components in the rare cases where
+ this is necessary: "bindings". Unfortunately the coupling here is done via direct object references, not
+ EL strings. And if a bean then holds on to these references then very bad things can happen if the
+ lifetime of the bean is longer than a request. Just one of the possible problems is the ugly
+ "duplicate component id" error.
+ </p>
+ <p>
+ Note that "bindings" are not generally a good idea, and should be avoided where possible. In the
+ remainder of this page we assume that you have some very good reason for wanting bindings, and
+ show you how they can be used with non-request-scoped beans.
+ </p>
+ </subsubsection>
+
+ </subsection>
+ <subsection name="Problem">
+ <p>
+ In order to avoid the lifecycle mismatch between components and beans, any bean that stores a component
+ binding must be request-scoped.
+ </p>
+ <p>
+ However what has been recommended in the "Orchestra best practices" is an access-scoped backing bean for
+ a view and an additional (access or manual) conversation-scoped controller for multi-page conversations.
+ The page controller/model now is stateful, which is exactly what we wanted, however when component bindings
+ are needed then they should not be stored on these beans because they are not request-scoped.
+ </p>
+ <p>
+ Therefore the following construct is bound to fail:
+ <pre>
+&lt;component binding="#{viewcontrollerbean.bindingattribute}" /&gt;
+ </pre>
+ due to the difference in scopes.
+ </p>
+ <p>
+ There are two possible solutions to this problem.
+ </p>
+ </subsection>
+
+ <subsection name="Solution 1: Spring aop-proxy">
+ <p>
+ Spring in 2.0 has introduced a construct called aop-proxy. This is a special tag which can be embedded
+ into beans which basically does nothing more than to weave a proxy object around an existing object which inherits
+ the scope of the referencing bean.
+ The inner part of the proxy or own bean then can have a scope of its own which can be smaller than the scope
+ of the referencing object.
+ </p>
+ <p>
+ So how does this help? Lets look again at our example
+ <pre>
+&lt;component binding="#{viewcontrollerbean.componentbindingmodel.bindingattribute}" /&gt;
+ </pre>
+ </p>
+ <p>
+ The accessor path has slightly changed, we have introduced a second bean; a model
+ bean which specifically holds our component bindings.
+ </p>
+ <p>
+ What happens on the spring configuration side is simply the following:
+ <pre>
+&lt;bean id="componentbindingmodel" scope="request" class="path.to.our.model.class"/&gt;
+&lt;bean id="viewcontrollerbean" scope="conversation.access" ...&gt;
+ &lt;property name="componentbindingmodel"
+ ref="componentbindingmodel" /&gt;
+&lt;/bean&gt;
+ </pre>
+ </p>
+ <p>
+ The associated component binding model class is a class which only holds the components as attributes and
+ provides associated setter and getter methods. The viewcontrollerbean class can then invoke its
+ methods to get access to the bound component instances.
+ </p>
+ <p>
+ When the viewcontrollerbean object is instantiated, Spring sees that it must inject the bean named
+ "componentbindingmodel" into it. However that bean is marked as an aop:proxy, so what spring injects
+ is just a "proxy" object, not a real componentbindingmodel bean. Whenever the viewcontrollerbean
+ then invokes a method on that proxy object, the proxy looks up bean "componentbindingmodel" in
+ the specified scope (request), then invokes that method on the object it found. This does have a
+ significant performance impact; each method call on the proxy performs the bean lookup again.
+ However it always acts on the "latest" version of that bean, which would not happen if a real
+ reference had been held. At the end of the request, the request-scoped componentbindingmodel object
+ is discarded as normal, and only the proxy "shell" remains. At the next request, a new componentbindingmodel
+ instance is created and added into the request scope, and methods invoked on the proxy will then
+ automatically work against this new object.
+ </p>
+ </subsection>
+ <subsection name="Solution 2: A request-scoped facade">
+ <p>
+ Only a few of the methods on the non-request-scoped backing bean will need access to the bound
+ components. Therefore, these methods can be moved into a request-scoped bean. Add the component
+ binding methods to this request-scoped bean too, and inject a reference to the "real" backing
+ bean into it. Alter the view so that EL expressions that need those component bindings to
+ be evaluated point to the request-scoped bean.
+ </p>
+ <p>
+ Another way of thinking about this is that the "real" backing bean for the page is implemented as
+ request-scoped, and any state it needs to retain is pushed into a "helper" object that is of
+ conversation scope. The request-scoped bean has access to the components without problems.
+ </p>
+ <p>
+ While either of these solutions means yet another backing-bean class for the view, there is no
+ "spring magic" required.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/component-bindings.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - The Conversation Scope Problem</title>
+ </properties>
+
+ <body>
+ <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
+ of related forms (often referred to as a "conversation", "workflow" or
+ "dialog"), during which the same java objects need to be kept in memory.
+ </p>
+
+ <p>
+ However JSF provides only three scopes for data to be stored in:
+ <ul>
+ <li><p>Application scope</p></li>
+ <li><p>Session scope</p></li>
+ <li><p>Request scope</p></li>
+ </ul>
+ </p>
+
+ <p>
+ Application scope is only rarely of use; such data is shared across all users of that JSF application.
+ Request scope is not useful for the above scenario; all data stored in request scope is discarded at
+ the end of each "command".
+ </p>
+
+ <p>
+ Session scope can be used to hold data across multiple requests (a conversation),
+ but suffers from a number of other issues:
+ <ul>
+ <li><p>When the conversation is complete, it is best to discard all the related objects in order
+ to save memory. However this is quite difficult to do when using session scope.</p></li>
+ <li><p>When a user performs some task for a second time (eg purchasing a second insurance policy),
+ it is usually better for the backing beans to be new instances rather than having whatever
+ state they had at the end of the previous pass. This is difficult to achieve when the beans
+ are in session scope; every relevant bean needs to be explicitly deleted or reset. However
+ when these objects are stored in a conversation this happens automatically as the conversation
+ (with all its beans) has been discarded.</p></li>
+ <li><p>The user cannot have multiple windows open on the same site. Sessions are typically
+ tracked using cookies, and all windows associated with the same browser instance
+ share cookies and therefore are within the same "session". If two windows are created
+ for the same session then very strange effects can be caused due to the same "backing beans"
+ being used by the two windows. Note that JSF implementations generally provide support for
+ multiple concurrent windows (eg MyFaces and Sun RI) but this only means that the JSF
+ *components* are safe for use with multiple windows; any application that uses only
+ request-scope beans will therefore work correctly but apps with session-scoped beans
+ will still suffer confusion.</p></li>
+ </ul>
+ </p>
+
+ <p>
+ The Tomahawk library provides a partial solution to this conversation problem with
+ the t:saveState tag, which allows data to be bound to a JSF View; it is then
+ available across multiple consecutive requests to the same view. It can also be
+ "passed" to a following view when navigation occurs. However this can be difficult
+ to use, as every bean that needs to be part of the conversation needs to be explicitly
+ tracked.
+ </p>
+
+ <p>
+ The draft JSF 2.0 specification currently defines a new "view" scope which also
+ provides a partial solution to this issue that is similar to the Tomahawk
+ t:saveState tag.
+ </p>
+
+ <p>
+ The Orchestra library provides another alternative.
+ 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.
+ </p>
+
+ <p>
+ 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>
+
+ <section name="Orchestra Conversation Scope Features">
+ <p>
+ The normal behaviour for JSF is that when an EL expression references a
+ bean that cannot be found anywhere in the current scopes, the managed bean
+ declarations are searched for the specified name. If a match is found then
+ the bean declaration is used to create an appropriate object instance and
+ insert it into the appropriate scope. The JSF standard provides a way for
+ variable lookup to be extended, and Spring provides an adapter that makes Spring
+ bean declarations accessable to JSF just like managed beans declared in the standard manner.
+ </p>
+
+ <p>
+ While "managed beans" declared using the standard JSF syntax can only be declared with
+ app, session or request scope it is possible with Spring 2.0 to declare custom scopes.
+ Orchestra makes "conversation scopes" available for use. When a bean is instantiated
+ which is declared to be part of "conversation Foo" then the conversation with that name
+ is looked up and the bean inserted into it. This scope is user-specific (ie is a child
+ of the session scope) and is created if it doesn't yet exist.
+ </p>
+
+ <p>
+ So far, the effect is just the same as using <i>session</i> scope for these beans.
+ However a conversation acts as a <i>container</i> for all the beans configured
+ with a particular conversation name. When a conversation ends, all beans
+ associated with that conversation can then be discarded together which is
+ difficult to achieve with simple session storage. A conversation can be
+ terminated in a number of ways:
+ <ul>
+ <li><p>access-scoped 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>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.
+ </p>
+
+ <p>
+ Conversation names are declared simply by specifying attribute orchestra:conversationName on
+ the Spring bean definition. If no name is provided, then the bean is placed in its own
+ private conversation (which happens to have a name equal to the bean name).
+ </p>
+
+ <p>
+ A conversation can have a <i>lifetime</i> of "access" or "manual".
+ An access-scoped 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
+ to a bean of that conversation scope. If the user navigates to any other
+ page (via direct url entry, or clicking a link, etc) then after that new page is
+ rendered the old (obsolete) conversation scope is automatically discarded. Only
+ when a user's path through the application can reference pages that do not reference
+ conversation-scoped beans is the "manual" conversation necessary - and in that case, an
+ explicit endConversation component (or direct API call) must be used to discard beans
+ when no longer needed.
+ </p>
+
+ <p>
+ Orchestra also provides the concept of a "conversation context", which holds
+ a set of named conversations. A "separateConversationContext" JSF component
+ creates a new context. When this is a parent of any command component
+ (eg a commandLink) then a new conversation context is automatically
+ created when that command is executed. This allows multiple windows
+ to access the same site while having completely independent sets of
+ objects that are of "conversation scope". A hidden "id" emitted into
+ pages specifies what the current conversation context is, ensuring the
+ new windows "sticks" with its associated conversation context.
+ </p>
+ </section>
+ <section name="Orchestra Conversation Scope Limitations">
+ <p>
+ Conversation-scoped beans are always stored (indirectly) in the user's http session.
+ This means that Orchestra requires server-side storage.
+ </p>
+ </section>
+ <section name="Notes for Seam Users">
+ <p>
+ The JBoss Seam library also provides a conversation scope. The purpose of this
+ scope is the same in Orchestra and Seam, but the details are a little different.
+ We aren't Seam experts, so this section is just our best attempt at describing
+ the fundamental differences; please contact the mailing list if you are a Seam
+ expert and have corrections for this section...
+ </p>
+ <p>
+ Seam's conversations are "request-centric", ie a request always has an associated
+ conversation (which may be "transient", ie of request scope!). Beans can be bound
+ to the current conversation via "out-jection" annotations. Therefore it makes sense
+ to ask "what is the current conversation for this request" from anywhere, even when
+ the object making the call is not "in" a conversation.
+ </p>
+ <p>
+ Orchestra instead is "bean-centric", ie a bean instance may have an associated
+ conversation, but a request does not. A request can access multiple beans, and each
+ of those beans can potentially be in a different conversation. A method can ask
+ "what conversation am I being invoked in", ie what conversation-scoped bean has
+ invoked the current method (and the answer may be "none"). Note that having
+ multiple conversations is really useful for pages where different parts of the page
+ (different "panels") have different lifetimes.
+ </p>
+ <p>
+ Seam's concept of "nested" conversations isn't generally needed in Orchestra, as
+ Orchestra supports multiple concurrent conversations (each with a separate "name").
+ In the case where a page calls itself, Orchestra <i>does</i> then need to "nest" data,
+ as the beans will try to use the same conversation. In this case, a nested
+ conversation-context must be used.
+ </p>
+ <p>
+ Seam uses an @Begin annotation on a method (or a non-standard "begin-conversation"
+ JSF navigation rule) to create a long-lived conversation. Orchestra does it automatically;
+ whenever an instance of a bean is created which is marked as being in a conversation "foo"
+ then conversation "foo" starts. Seam uses out-jection annotations to indicate which beans
+ belong in the conversation; instead with Orchestra the bean declarations themselves indicate
+ which conversation the bean instance is in.
+ </p>
+ <p>
+ Both Seam and Orchestra need a mechanism to end a conversation. For Orchestra's
+ "manual-lifetime" conversations, the o:endConversation tag or a call to method
+ Conversation.getCurrentInstance().invalidate() are pretty much equivalent to the
+ Seam @End annotation. For Orchestra's "access-lifetime" conversations, the conversation
+ is terminated automatically; we are not aware of any Seam equivalent for this.
+ </p>
+ <p>
+ Seam's conversation-context is almost identical to Orchestra's conversation-context.
+ However with Seam, pages need to explicitly include the context id into urls, by
+ using EL expression #{conversation.id} or the s:conversationPropagation tag where
+ appropriate. Orchestra automatically does this; instead, only links that should <i>not</i>
+ propagate the conversation context need to be marked (using the o:separateConversationContext
+ tag). This works for all JSF components as long as they call ExternalContext.encodeURL(),
+ which all code that generates URLs should do.
+ </p>
+ <p>
+ Seam's "conversation switcher" functionality is equivalent to switching between different
+ Orchestra "conversation contexts".
+ </p>
+ </section>
+ <section name="Notes for Spring WebFlow Users">
+ <p>
+ The Spring WebFlow library also provides a conversation scope. The purpose of this
+ scope is the same in Orchestra and Seam, but the details are a little different.
+ </p>
+ <p>
+ WebFlow appears to have a similar approach to Seam (request-centric rather than
+ Orchestra's bean-centric approach). See the first couple of paragraphs above
+ describing the Seam/Orchestra differences for the implications of this.
+ </p>
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/conversation.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - FAQs</title>
+ </properties>
+
+ <body>
+ <section name="FAQ">
+
+ <subsection name="Database connection not passed back to the connection pool after the HTTP request">
+
+ <p>
+ Depending on your environment and used JPA-implementation you might experience the problem
+ that there are database connections which have not been passed back to the connection pool.<br />
+ This can happen if you use entities with e.g. OneToMany mappings and lazy init AND accessing the
+ OneToMany collection from your JSF view the first time.<br />
+ The EntityManager has to re-establish a connection to your database, but now that this happens
+ outside of your conversation scoped bean, no one ends the transaction and so no one puts the
+ connection back to the pool.<br />
+ The problem is that with a growing number of users and a growing number of conversations
+ (especially not ended conversations - waiting for their timeout) your pool might exhaust.<br />
+ As said before, this might not be the case with all JPA-implementations. But we had at least
+ one environment where this happened, so here the work-around.
+ </p>
+ <p>
+ To activate the workaround simply put the following code in your spring config and adjust the
+ names as required.
+
+ <pre>
+&lt;bean id="managedDataSource" class="org.apache.myfaces.orchestra.connectionManager.ConnectionManagerDataSource"&gt;
+ &lt;property name="dataSource" ref="dataSource"/&gt;
+&lt;/bean>
+ </pre>
+
+ The basic principle is to put a virtual DataSource between the JPA-implementation and
+ the read DataSource (which should be a connection pool for performance reasons).<br />
+
+ You have to configure
+ <ul>
+ <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>
+ </p>
+ </subsection>
+
+ <subsection name="PropertyPlaceholderConfigurer STOPS working after the introduction of orchestra into my configuration">
+ <p>
+ Use the <code>&lt;aop:scoped-proxy&gt;</code> configuratino with in the
+ <code>persistentContextConversationInterceptor</code> definition.
+ You'll end up with something like:
+ <pre>
+&lt;bean id="persistentContextConversationInterceptor" class="org.apache.myfaces.orchestra.conversation.spring.PersistenceContextConversationInterceptor"&gt;
+ &lt;aop:scoped-proxy/&gt;
+ &lt;property name="persistenceContextFactory" ref="persistentContextFactory"/&gt;
+&lt;/bean>
+ </pre>
+ </p>
+ <p>
+ The reason is, that, during startup of the spring system when the custom scope will
+ be initialized, the system might already require a datasource, but at this time
+ the <code>PropertyPlaceholderConfigurer</code> didn't run already.<br />
+ Using the <code>&lt;aop:scoped-proxy&gt;</code> configuration allows the initialization
+ process to end cleanly.
+ </p>
+ </subsection>
+
+ <subsection name="The ViewController events are called twice">
+ <p>
+ If your ViewController event methods are called twice you probably configured the
+ ViewControllerPhaseListener in your faces-config.xml which is not required.<br />
+ Orchestra already does this for you.
+ </p>
+ </subsection>
+
+ <subsection name="Is it possible to pass a persistent entity between beans in different conversations?">
+ <p><br>No!</br></p>
+ <p>
+ Each conversation has its own persistence context, but an entity can only be managed
+ by the context it was loaded by.
+ <br/>
+ Reading an entity may trigger lazy loads. This will always be performed using the
+ persistence context that loaded the entity, ie this works regardless of who calls
+ the method on the entity.
+ <br/>
+ However performing operations like merge, delete, etc. require the object to be
+ passed to a persistence context; if it is passed to the wrong one then unexpected
+ behaviour will occur. Things like using the object in a query being executed in
+ a persistence context that is not the one associated with that entity may also
+ fail.
+ <br/>
+ Rather than passing entity references between conversations, just pass the key of the
+ object and reload it if access is required from a different conversation.
+ <br/>
+ This is not an Orchestra limitation, but more a technical limitation of how ORMs work today.
+ </p>
+ </subsection>
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/faqs.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - Glossary</title>
+ </properties>
+
+ <body>
+ <section
+ name="Glossary">
+ <ul>
+ <li>POJO
+ <br/>
+ A plain-old-Java-object, according to the Java bean standard.
+ This is a class with (mostly) private members and a get- and set-method
+ (also called getter and setter) for each of them. The original aim
+ of object-relational mapping tools was to persist such pojos into the database with the
+ help of e.g. an external xml configuration per pojo. When Java 5 came
+ up this changed a bit, now it is common to use annotations in the Java
+ source itself. With that, strictly spoken, beans are not pojos anymore.
+ </li>
+
+ <li>Entity
+ <br/>
+ A pojo with an extended description. The description allows the entitiy
+ manger to persist the entity into the database. Common
+ descriptions are XML files or annotations in the Java source. This
+ data is called metadata.
+ </li>
+
+ <li>Property
+ <br/>
+ A property is a member variable of your pojo with a defined
+ set and get method. You have to follow the Java Bean
+ specification. The following examples show this syntax -
+ the first column, named property, shows how you would access
+ this property from the outside (e.g. via reflection or from a JSF-JSP-page).
+ The second column shows the syntax of defining the member, the next columns
+ the name of getter and setter.
+ <table width="40%">
+ <tr>
+ <th>property</th>
+
+ <th>member</th>
+
+ <th>getter</th>
+
+ <th>setter</th>
+ </tr>
+
+ <tr>
+ <td>userId</td>
+
+ <td>private String userId</td>
+
+ <td>getUserId</td>
+
+ <td>setUserId</td>
+ </tr>
+
+ <tr>
+ <td>userName</td>
+
+ <td>private String _userName</td>
+
+ <td>getUserName</td>
+
+ <td>setUserName</td>
+ </tr>
+
+ <tr>
+ <td>displayed</td>
+
+ <td>private boolean displayed</td>
+
+ <td>isDisplayed</td>
+
+ <td>setDisplayed</td>
+ </tr>
+
+ </table>
+ </li>
+
+ <li>Entity Manager
+ <br/>
+ The "entity manager" manages all your entities,
+ keeps track of property updates and issues the database statements
+ required to synchronize the entity state with the database. If you
+ close an entity manager you will loose the coupling between its
+ internal state and your entities, they are so called "detached objects"
+ afterwards.
+ </li>
+
+ <li>Entity Manager Factory
+ <br/>
+ The "entity manager factory" is
+ responsible for processing all the entity metadata and to create an
+ entity manager based on it.
+ </li>
+
+ <li>DAO - Data Access Object
+ <br/>
+ Usage of data access objects is based on the pattern with the same name. Data access
+ objects are singletons which contain
+ all of the database requests your application will issue - generally, one data access object
+ encapsulates all database requests for one entity.
+ Thus, the DAO is injected with an entity
+ manager.
+ </li>
+
+ <li>Conversation
+ <br/>
+ A conversation is the time-span encapsulating all the
+ operations in your business logic required to finish a process
+ (in the end, this will almost always include the need for executing database transactions).
+ Other names of this principle are: application transaction, unit-of-work
+ </li>
+
+ <li>Session Scope
+ <br/>
+ The session scope of your servlet container.
+ Beans put into this scope live until the configured inactivity timout
+ for the session has been reached or the session is closed explicitly
+ </li>
+
+ <li>Request Scope
+ <br/>
+ The request scope of your servlet container.
+ The lifetime of request-scoped-beans is as long as the duration of a
+ single HTTP request. Once the servlet container finishes sending
+ the page data, the request will die and with it all the beans put into
+ this scope.
+ </li>
+
+ <li>JPA - Java Persistence API
+ <br/>
+ The JPA standardizes the way how
+ you annotate your entities with regards to persistence. That way you can change the
+ ORM tool as long as the ORM tool follows the JPA
+ specification.
+ </li>
+
+ <li>backing bean
+ <br/>
+ A backing bean is the bean behind a JSF view
+ (jsp, facelet, etc page). While JSF does not require such a bean, it is
+ good practice to provide one backing-bean per page as a rule of thumb.
+ </li>
+ </ul>
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/glossary.xml
------------------------------------------------------------------------------
svn:eol-style = native

Added: myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml?rev=1326868&view=auto
==============================================================================
--- myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml (added)
+++ myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml Tue Apr 17 01:29:52 2012
@@ -0,0 +1,227 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+ "http://www.apache.org/dtd/xdoc.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+ -->
+
+<document>
+ <properties>
+ <title>Apache MyFaces Orchestra - Implementation Details</title>
+ </properties>
+
+ <body>
+ <section name="Overview">
+ <p>
+ To understand what features Orchestra can provide, and what its limitations are,
+ it can be helpful to understand how it works. This is entirely optional, and
+ you can skip this section if you wish.
+ </p>
+ <p>
+ Please note that the information in this section describes how the current
+ implementation works. This is subject to change in future releases.
+ </p>
+ </section>
+ <section name="Proxies">
+ <p>
+ Orchestra uses object "proxies" that intercept calls to real beans in order to
+ track data flows and to redirect them as appropriate.
+ </p>
+ <p>
+ When a bean is configured to live in an Orchestra scope, any time an instance
+ of that bean is created then what is returned is not a reference to the actual
+ type, but instead a proxy object. The proxy object is of the same type (ie
+ "x instanceof TheExpectedType" will return true). If you use getClass() on the
+ proxy object, it may show that the proxy is a subclass of the expected type
+ (depending on how the proxying is implemented). However in most cases this doesn't
+ matter; the proxy can be treated exactly as if it was of the expected type, and of
+ course provides all the same methods that the expected type supports.
+ </p>
+ <p>
+ Of course this relies upon instances being created in a way that Orchestra can
+ intercept in order to create the proxy object. The most common usage is expected
+ to be JSF with Spring; in this setup a custom JSF VariableResolver is automatically
+ registered so that EL expressions such as "#{myBean}" cause Spring to handle the
+ lookup, and Orchestra's Spring scope-handler will then automatically proxy the bean.
+ However other presentation-tier approaches (eg plain jsp or servlets) and other
+ bean-management implementations (such as Google Guice) should be usable with
+ Orchestra as long as there is a mechanism for the appropriate proxies to be
+ created when needed.
+ </p>
+ <p>
+ The proxy has two distinct functions: to direct calls to an appropriate "real"
+ underlying bean (similar to Spring's aop:scoped-proxy), and to run an arbitrary
+ set of "advices" around each method call on the proxy. In particular, an advice is
+ used to implement Orchestra's persistence support (see later).
+ </p>
+ </section>
+ <section name="Indirection">
+ <p>
+ The proxy object returned by orchestra during a bean lookup does not directly hold
+ a reference to the underlying bean. Instead it just keeps:
+ <ul>
+ <li>a reference to a Scope object</li>
+ <li>a conversation-name string</li>
+ <li>a bean-name string</li>
+ </ul>
+ </p>
+ <p>
+ Invoking any method on the proxy object causes it to:
+ <ul>
+ <li>fetch the ConversationManager object for the current user</li>
+ <li>fetch the current ConversationContext for the user's current window</li>
+ <li>fetch the correct Conversation instance (using the conversation-name)</li>
+ <li>
+ fetch the correct target object from the Conversation (using bean-name),
+ or (if the instance does not yet exist) create an instance and store it in the
+ conversation.
+ </li>
+ </ul>
+ Then the originally invoked method is forwarded to the target object that was found.
+ </p>
+ <p>
+ Any call on a method of the proxy will therefore be forwarded to an instance that is
+ stored in a specific Conversation object. If the Conversation object is deleted, then
+ invoking a method on the proxy will just create a new Conversation instance and a
+ new instance of the target bean. Because of this, proxy objects can be retained
+ for any length of time; they never point to "stale" objects. This in turn allows
+ Orchestra to discard conversation objects at appropriate times without breaking
+ code holding references to those objects.
+ </p>
+ <p>
+ There is of course a performance penalty for this; invoking a method on a
+ conversation-scoped object (via its proxy) require a couple of hashmap lookups to
+ locate the target object, plus whatever internal overhead the proxying library
+ (currently CGLIB) adds.
+ </p>
+ <p>
+ Note that in Orchestra Core 1.0 a spring aop:scoped-proxy tag was needed on bean
+ definitions in order to enable the above functionality. Orchestra does function
+ without the indirection feature, but code must then be careful not to store any such
+ references for later use; instead beans can only be referenced via EL expressions.
+ It was strongly recommended in Orchestra 1.0 that aop:scoped-proxy be added to
+ each conversation-scoped bean definition and it is now automatic in Orchestra
+ Core 1.1.
+ </p>
+ </section>
+ <section name="Storing Conversations">
+ <p>
+ Conversations are stored within a ConversationContext which is stored within a
+ ConversationManager which is in turn stored within an HttpSession.
+ </p>
+ <p>
+ A conversation and its associated data therefore lasts as long as the user's
+ session object, unless explicitly deleted by Orchestra.
+ </p>
+ </section>
+ <section name="Access Scope">
+ <p>
+ When a proxy is invoked, and retrieves a target bean from a specific conversation
+ it also marks the conversation as "accessed". This allows Orchestra to determine
+ whether a conversation is currently "in use", or whether the user has navigated off
+ to some other part of the webapp. When the conversation is marked as "access" scope,
+ and is not in use then it is simple to detect this and discard the conversation
+ (together with all the bean instances that are stored in it).
+ </p>
+ <p>
+ Because proxies simply trigger the creation of new instances (and a conversation to
+ hold it) when needed, a user returning to an "access scope" page simply causes a
+ "fresh" version of the page state to be created.
+ </p>
+ <p>
+ This approach is quite different from some other libraries that provide conversation
+ scope. In particular, it does not require any elaborate flow-control state charts
+ to control navigation. With Orchestra the detection of beans that are no longer in
+ use is completely automatic.
+ </p>
+ </section>
+ <section name="Manual Scope">
+ <p>
+ With manual scope, Conversation instances are only deleted when application code
+ makes an explicit call to the Orchestra API, or when a JSF tag in a page makes
+ that call. The application therefore itself determines when a set of beans
+ (ie a conversation) is no longer needed. The implementation of this is obvious:
+ a ConversationContext object holds a map of conversations by name, and this
+ just removes the appropriate (name, Conversation) entry from that map. All the
+ beans in the conversation then become elegible for garbage-collection. Note
+ that Orchestra provides an option for beans in a conversation to be notified
+ when the conversation is terminated, which provides a kind of "destructor"
+ opportunity.
+ </p>
+ </section>
+ <section name="Multiple beans in a single Scope">
+ <p>
+ Each conversation has a name. By default, a conversation-scoped bean will be
+ placed in a conversation whose name is the bean-name used to retrieve that bean
+ from the dependency-injection system (Spring or other). Therefore by default
+ each conversation has only one bean in it.
+ </p>
+ <p>
+ Configuring a group of beans to belong to the same conversation is quite
+ useful with both Access and Manual scopes. To do this, simply ensure that the
+ configuration on the bean declaration specifies a conversation name. The
+ Conversation object has a Map of the objects in it, and so therefore can
+ hold any number of different beans, keyed by their bean-name.
+ </p>
+ </section>
+ <section name="Multiple Window Support">
+ <p>
+ An http session is typically maintained via a "cookie" that identifies the session
+ to be used for each request. A web-browser can open multiple windows or tabs which
+ share the same cookies; in this situation requests from different windows will all
+ use the same http-session on the server, and therefore access exactly the same
+ instances of session-scoped objects.
+ </p>
+ <p>
+ Unfortunately reusing session-scoped objects for completely unrelated requests
+ coming from different windows or tabs of a user's browser can cause nasty problems.
+ </p>
+ <p>
+ The Java Servlet standard does not support more than one session per user. However
+ Orchestra effectively provides this by keeping conversation objects as children of
+ a ConversationContext object. All that is needed is for each window to specify a
+ different ConversationContext object to use. Further documentation on this feature
+ can be found elsewhere on the Orchestra site.
+ </p>
+ </section>
+ <section name="Persistence">
+ <p>
+ Each conversation can optionally have a PersistenceContext associated with it. When
+ this is configured, then after a proxy has been invoked and has determined which
+ conversation the target bean is in, it configures the PersistenceContext associated
+ with that conversation as "the global persistence context". Any persistence operations
+ performed by the target bean (or the ordinary instances it calls) therefore run in
+ the context of the persistence context for that conversation. When the method on the
+ target bean returns, the proxy restores the previous persistence context.
+ </p>
+ <p>
+ Conversation instances are stored (indirectly) in the user session, so the persistence
+ context objects last across multiple requests, and are only discarded when the associated
+ conversation object is discarded. This allows "long running" persistence operations.
+ </p>
+ <p>
+ As noted elsewhere, this is useful only in applications where the database access and
+ the web presentation logic exist in the same physical tier. This is common for
+ small to medium applications, but the largest and most security-sensitive applications
+ typically keep database access logic in a separate tier and therefore this Orchestra
+ feature cannot be applied. However there are many single-tier applications where this
+ functionality can save a lot of developer time and effort.
+ </p>
+ </section>
+ </body>
+</document>

Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/implementation.xml
------------------------------------------------------------------------------
svn:eol-style = native

Search Discussions

  • Lu4242 at Apr 17, 2012 at 1:30 am
    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,314 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>Apache MyFaces Orchestra - Installation</title>
    + </properties>
    +
    + <body>
    + <section name="Installation">
    + In the following, we will assume that you know how to setup
    + <ul>
    + <li><p>a servlet container (Tomcat, Jetty, etc)</p></li>
    + <li><p>your ORM tool (OpenJPA, Toplink.essentials, Hibernate, etc)</p></li>
    + <li><p>your JSF implementation (MyFaces, JSF-RI, etc)</p></li>
    + </ul>
    + <p>
    + For a beginner these are big assumptions; none of these technologies are simple.
    + However we simply cannot conver these topics in a brief guide. In addition, these
    + subjects are covered well elsewhere.
    + </p>
    + <p>
    + For an absolute beginner in using these technologies, we recommend taking a look at the
    + <a href="http://code.google.com/p/facesgoodies/">Faces-Goodies</a> project - a perfect way
    + of kickstarting you in the world of JSF, Spring and JPA and then return back to include Apache
    + Orchestra.
    + </p>
    + <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 we hope to add chapters on integrating
    + directly with Hibernate and Toplink.
    + </p>
    +
    + <subsection name="Prerequisites">
    + <ul>
    + <li><p>Apache MyFaces Orchestra core</p></li>
    + <li><p>Apache MyFaces Orchestra core15 (optional; requires java1.5 or later)</p></li>
    + <li><p>Spring 2.x</p></li>
    + <li><p>a JSF implementation (e.g. JSF-RI, MyFaces)</p></li>
    + <li><p>a JPA implementation (e.g. OpenJPA, toplink.essentials (formerly
    + Oracle Toplink)</p></li>
    + <li><p>and all their dependencies
    + <br/>
    + This might sound somehow vague; however, the exact names of the necessary libraries
    + depends on the JSF and JPA implementation. If you have to setup
    + an application architecture like this from scratch it might be best to take a look at our
    + examples package, and there in the file "pom.xml" which includes a section on the
    + necessary dependencies.</p>
    + </li>
    + </ul>
    + </subsection>
    +
    + <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>
    +<![CDATA[
    + <?xml version="1.0" encoding="UTF-8"?>
    +
    + <beans xmlns="http://www.springframework.org/schema/beans"
    + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    + xmlns:tx="http://www.springframework.org/schema/tx"
    + xmlns:aop="http://www.springframework.org/schema/aop"
    + xsi:schemaLocation="
    + http://www.springframework.org/schema/beans
    + http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
    + http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.0.xsd
    + http://www.springframework.org/schema/aop
    + " rel="nofollow">http://www.springframework.org/schema/aop/spring-aop-2.0.xsd">
    +
    + <!-- 1. initialization of all orchestra modules (required for core15 module) -->
    + <import resource="classpath*:/META-INF/spring-orchestra-init.xml" />
    +
    + <!-- 2. the conversation scopes -->
    + <bean class="org.springframework.beans.factory.config.CustomScopeConfigurer">
    + <property name="scopes">
    + <map>
    + <entry key="conversation.manual">
    + <bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope">
    + <property name="timeout" value="30" />
    + <property name="advices">
    + <list>
    + <ref bean="persistentContextConversationInterceptor"/>
    + </list>
    + </property>
    + </bean>
    + </entry>
    +
    + <entry key="conversation.access">
    + <bean class="org.apache.myfaces.orchestra.conversation.spring.SpringConversationScope">
    + <property name="timeout" value="30" />
    + <property name="advices">
    + <list>
    + <ref bean="persistentContextConversationInterceptor"/>
    + </list>
    + </property>
    + <property name="lifetime" value="access"/>
    + </bean>
    + </entry>
    + </map>
    + </property>
    + </bean>
    +
    + <!-- 3. the "entity manager" manager -->
    + <bean id="persistentContextConversationInterceptor"
    + class="org.apache.myfaces.orchestra.conversation.spring.PersistenceContextConversationInterceptor">
    + <property name="persistenceContextFactory" ref="persistentContextFactory"/>
    + </bean>
    +
    + <!-- 4. conversation - persistence adapter -->
    + <bean id="persistentContextFactory"
    + class="org.apache.myfaces.orchestra.conversation.spring.JpaPersistenceContextFactory">
    + <property name="entityManagerFactory" ref="entityManagerFactory"/>
    + </bean>
    +
    + <!-- 5. persistence -->
    + <bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>
    +
    + <tx:annotation-driven />
    +
    + <bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager">
    + <property name="entityManagerFactory" ref="entityManagerFactory"/>
    + </bean>
    +
    + <bean id="entityManagerFactory"
    + class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
    + <property name="jpaProperties">
    + <props>
    + <prop key="toplink.logging.level">FINE</prop>
    + <prop key="toplink.jdbc.driver">org.apache.derby.jdbc.EmbeddedDriver</prop>
    + <prop key="toplink.jdbc.url">jdbc:derby:myfacesOrchestraDB;create=true</prop>
    + <prop key="toplink.jdbc.user">sa</prop>
    + <prop key="toplink.jdbc.password">foobar</prop>
    + <prop key="toplink.target-database">oracle.toplink.essentials.platform.database.DerbyPlatform</prop>
    + <prop key="toplink.ddl-generation">create-tables</prop>
    + </props>
    + </property>
    + <property name="persistenceUnitName" value="default"/>
    + </bean>
    + </beans>
    + ]]>
    +</pre>
    + <p>
    + Basically, all you need to do is copy this configuration segment and paste it
    + into your Spring configuration file. Then you'll need to adapt the settings in the element
    + entityManagerFactory - namely the jpaProperties. For a more detailed explanation, we have
    + included the following instructions - it is not necessary to read through them.
    + </p>
    + <ul>
    + <li>1. initialization of orchestra modules
    + <br />
    + The Spring import statement will ensure that all <code>spring-orchestra-init.xml</code>
    + files are processed. Orchestra sets up some defaults in these init files that are
    + necessary for the correct functioning of Orchestra.
    + </li>
    + <li>2. the conversation scopes
    + <br/>
    + Here we configure both "conversation.access" and "conversation.manual" as new Spring
    + custom scopes. This configuration allows us to use scope="conversation.access"
    + or scope="conversation.manual" within our bean declarations. The scope definition
    + also allows a number of advices (interceptors) to be configured; advices intercept
    + each method call to a bean in that scope. We add an interceptor here to ensure that
    + on any call to a bean in that scope the entity manager (aka persistence context) is
    + set to be the appropriate one for that conversation.
    + <br/>
    + 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.
    + The <code>timeout</code> property accepts a numeric value which means a timespan
    + in minutes.
    + <br />
    + 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>
    +
    + <li>3. the "persistence context conversation interceptor"
    + <br/>
    + This tells spring what class to use for the interceptor specified in the scope
    + definitions. This orchestra class does the hard work of keeping the right
    + persistence context set up at all times.
    + </li>
    +
    + <li>4. conversation - persistence adapter
    + <br/>
    + Depending on the ORM tool you want to use you will have to configure an appropriate
    + persistenceContextFactory. Apache MyFaces Orchestra provides a JPA implementation
    + in its current release; other adapters may be added in the future.
    + </li>
    +
    + <li>5.persistence
    + <br/>
    + This enables the standard Spring support for persistence annotations such as
    + @PersistenceContext; any bean instantiated by spring will be scanned for
    + annotations and the appropriate dependencies injected.
    + <br/>
    + This section also sets up database transaction support.
    + <br/>
    + As this is all standard Spring functionality, have a look at the Spring
    + documentation for further details and options. For our example, we use
    + <code><tx:annotation-driven/></code>.
    + <br/>
    + If you are using Java 1.4 you can choose a non-annotation-based approach.
    + </li>
    + </ul>
    + <p>
    + <b>Notice</b>
    + : You will be able to configure multiple conversation
    + scopes (each one of them will need to have a distinct name)
    + using different persistence strategies or without persistence at all.
    + </p>
    + <p>That's all for Spring now -
    + according to the JPA specification and your JPA implementation, you will also
    + have to provide a META-INF/persistence.xml too. Please check your JPA provider
    + documentation on how to do this.
    + </p>
    + </subsection>
    + <subsection name="JSF configuration">
    + <p>
    + Next you have to add some listeners to your web.xml configuration.
    + </p>
    + <pre>
    +<![CDATA[
    +<listener>
    + <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    +</listener>
    +<listener>
    + <listener-class>org.springframework.web.context.request.RequestContextListener</listener-class>
    +</listener>
    +<listener>
    + <listener-class>org.apache.myfaces.orchestra.conversation.servlet.ConversationManagerSessionListener</listener-class>
    +</listener>
    +]]>
    + </pre>
    + </subsection>
    +
    + <subsection name="Mixed environment installation">
    + <p>
    + If your application has only JSF pages then no further configuration is required.
    + </p>
    + <p>
    + However if your application includes jsp, plain servlets, or anything else that
    + does not pass through the FacesServlet then two filters must be defined:
    + </p>
    +<pre>
    +<![CDATA[
    + <filter>
    + <filter-name>frameworkAdapterFilter</filter-name>
    + <filter-class>org.apache.myfaces.orchestra.frameworkAdapter.basic.BasicFrameworkAdapterFilter</filter-class>
    + </filter>
    +
    + <filter>
    + <filter-name>requestParameterFilter</filter-name>
    + <filter-class>org.apache.myfaces.orchestra.requestParameterProvider.RequestParameterServletFilter</filter-class>
    + </filter>
    +
    + <filter-mapping>
    + <filter-name>frameworkAdapterFilter</filter-name>
    + <url-pattern>*.jsp</url-pattern>
    + </filter-mapping>
    +
    + <filter-mapping>
    + <filter-name>requestParameterFilter</filter-name>
    + <url-pattern>*.jsp</url-pattern>
    + </filter-mapping>
    +]]></pre>
    + </subsection>
    +
    + <subsection name="Conclusion">
    + That's all for the basic configuration of Apache MyFaces Orchestra; now you should have
    + working conversation scopes and correctly configured persistence. In fact there is nothing
    + special in creating the database access objects (DAO) or your business objects (BO). Your
    + JSF page backing beans will also look the same - however, you configure them in Spring and
    + put them into the conversation scope now, rather than session scope.
    + </subsection>
    +
    + </section>
    + <section name="User provided configurations">
    + <ul>
    + <li><p><a href="alternative-configuration.html">A spring configuration using toplink and load time weaving with tomcat</a></p></li>
    + </ul>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/installation.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,69 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>The Apache MyFaces Orchestra Core Module</title>
    + </properties>
    +
    + <body>
    + <section name="Apache MyFaces Orchestra Core">
    + <p>The Orchestra Core library provides the following features as described in the
    + documentation for the Orchestra project:
    + <ul>
    + <li><p><a href="conversation.html">Conversation scope</a> (aka dialog scope) for beans.</p></li>
    + <li><p><a href="persistence.html">Conversation-scope persistence</a> contexts. This fixes the
    + dreaded LazyInitializationException or NonUniqueObjectException problems when working with
    + persistent objects.</p></li>
    + </ul>
    + </p>
    + <p>Orchestra Core requires only Java 1.4 and JSF 1.1.</p>
    + </section>
    + <section name="Important Information">
    + <p>
    + Orchestra assumes the presence of a server-side http session into which state is stored.
    + If you are designing a highly scalable distributed system then this may not be the right
    + approach for you.
    + </p>
    + <p>
    + Orchestra persistence features presume the presentation tier has access to the database,
    + ie that the presentation and database-access tiers are combined. This is often the case
    + in small-to-medium web applications. Large or security-sensitive applications which separate
    + database access out into an isolated tier (eg use a "full EJB stack") cannot use the Orchestra
    + persistence facilities, although they can still make use of the regular conversational support
    + for beans in the presentation layer.
    + </p>
    + <p>
    + Orchestra conversations with persistence support will never be transparently "distributable"; JPA
    + sessions are not serializable. However it should be possible for conversations that do not have an
    + associated persistence context to be distributed; this work has not yet been done as the current
    + Orchestra developers and users do not need this feature. If you need this feature, please contact
    + the development list.
    + </p>
    + <p>
    + Orchestra currently does not support Portlets. It should not be particularly difficult
    + to implement this, but the current Orchestra development team do not use Portlets so
    + support will only be available when someone volunteers to do the necessary work.
    + </p>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/introduction.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,220 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>Dealing with Multiple Browser Windows</title>
    + </properties>
    +
    + <body>
    + <section name="The General Problem">
    + <p>When the web was originally designed, sites were stateless. In addition, users would usually
    + only use a single web-browser window. Unfortunately neither of these are now true; the sites
    + that JSF and similar technologies are most useful for are highly stateful applications that
    + resemble desktop applications. And users are used to having multiple browser windows or tabs
    + open concurrently; it is simply natural for them to try to browse data with one window while
    + editing it with another. In any application this requires some programming care to handle
    + correctly, although for "desktop" applications this is not too difficult. For web applications
    + handling this is trickier, but possible as long as the server can keep track of which window
    + is performing which operations and allocate separate "state" data to each window.</p>
    + <p>When all state is embedded within a page (as form fields), or within the url (as query
    + parameters); the window identity does not need to be tracked at all as each request includes
    + all the necessary state. However there are a couple of significant problems with embedding
    + state into a page, including:
    + <ul>
    + <li>limited size of urls</li>
    + <li>the long lifetime of urls (they can be bookmarked and later reused)</li>
    + <li>state encoded into forms gets lost on GET requests (ie link anchors)</li>
    + <li>network bandwidth needed to stream state from server to client</li>
    + <li>not all state may be easily serializable (eg persistence contexts).</li>
    + </ul>
    + </p>
    + <p>Unfortunately, the http protocol has not kept up with these new changes in web usage. The
    + use of a "sessionId" embedded in either the url or a "cookie" was invented many years ago to
    + support stateful behaviour <i>per-browser</i>. However this simply does not allow a server to
    + properly provide per-window state.</p>
    + <p>There are various hacks available to handle per-window state on the server which work at
    + least partially, but none of them are completely satisfactory.</p>
    + <p>The user actions which are particularly problematic are:</p>
    + <ul>
    + <li>Right-clicking a link and selecting "open in new window" or "open in new tab"</li>
    + <li>Bookmarking a page, then later opening a new page and activating the bookmark.</li>
    + <li>Copying the URL from the browser toolbar and pasting it into a new window</li>
    + </ul>
    + <p>Note that this section is not discussing the issue of modal popup windows. Those occur
    + only where the program explicitly chooses, and so which "window state" is associated with that
    + window is under the control of the programmer and is not a major problem. It is those windows
    + that the user may open without the knowledge of the server that this page addresses.</p>
    + </section>
    +
    + <section name="Orchestra and the Multiple Window Problem">
    + <p>Orchestra is explicitly intended to support stateful applications using server-side state.
    + Therefore people who are interested in using Orchestra are almost certainly also interested in dealing with
    + the general problem of multiple concurrent windows onto the stateful application.</p>
    + <p>Orchestra is also intended to provide a framework on which sophisticated "state management"
    + for applications can be built. An example is the ability to click a link in a page header to
    + save the current state, effectively providing a bookmark-with-state that the user can then
    + restore at some later time. This would allow users to "interrupt" their current task to deal with an
    + urgent call, then return to it when the interruption is dealt with. Therefore the concept of
    + state management is core; the "ConversationContext" class holds the entire set of active conversations
    + and a user can have multiple ConversationContext objects (although only one is used for any
    + particular http request). Providing per-window state management is just a matter of associating
    + a window with a particular ConversationContext.</p>
    + <p>There is also one Orchestra-specific issue related to multiple windows: the "access-scope conversation"
    + feature fails when multiple windows are sharing the same state. Access scope monitors requests and
    + automatically cleans up conversations that are no longer being used. However when two windows are
    + accessing the same orchestra-enabled webapp concurrently and use the same per-window-state, then a
    + request in one window would cause conversations to be discarded which the other window later wants
    + to use.</p>
    + <p>Orchestra therefore provides built-in support for multiple windows. Unfortunately due to the
    + limitations of http this is not a bullet-proof solution and correct handling of multiple windows
    + requires some work by the programmer and some cooperation by the end users.</p>
    + <p>See the section below titled "Orchestra Multiple Window Support" for details of the current
    + implementation provided by Orchestra.</p>
    + </section>
    +
    + <section name="Embedding a window-id in a hidden field">
    + <p>The most reliable way of tracking window identity is to embed a window-id within a hidden
    + field in each form, and mark forms as using POST (which is the default). Browsers do not support
    + an operation to do "submit form and show result in other window", and bookmarking does not store
    + form data. In addition, when a POST is performed the url of the post is displayed in the browser
    + navigation bar, but not the form field values so it is not stored by a later "bookmark" operation.
    + Therefore a window identifier from one form cannot end up in another window (except by malicious
    + behaviour on the part of the user, which doesn't matter here as the user can only confuse the state
    + of their own windows, not anybody else's).</p>
    + <p>Unfortunately, the window identity will be lost as soon as the user does an operation
    + that is not a POST. And this is a critical flaw in most cases; applications that care about window
    + state generally want to allow navigation via links (GET) as well as form posts.</p>
    + <p>Even when state is only needed for POST sequences, that state does need to be cleaned up when
    + the user does a GET. Therefore losing the window identity value when a GET is done makes it
    + impossible to correctly clean up memory on the server.</p>
    + </section>
    +
    + <section name="Embedding a window-id in a cookie">
    + <p>Cookies are (name,value) pairs that a server can send to a browser, and which the browser will
    + then echo back in each request that it sends to a server. These are not bookmarkable and are provided
    + on all request types (GET, POST, etc). Therefore they are ideal to track window identity - except
    + that all modern browsers treat cookies as shared across all windows in a browser. Setting it in one
    + window affects all other windows too.</p>
    + <p>There is <i>possibly</i> a way to use cookies to track window identity when javascript is enabled.
    + Below is the outline of a possible approach using cookies. However it has not been implemented at the
    + current time because it has a number of significant flaws. Together these make this approach less
    + appealing than the url-based approach that Orchestra currently implements. The limitations are:</p>
    + <ul>
    + <li>It requires javascript (though it is possible to "fall back" to other approaches).</li>
    + <li>It requires session-scoped cookies</li>
    + <li>It requires the server to detect whether the browser supports cookies or not.</li>
    + <li>It requires javascript to be rendered into the head of each page.</li>
    + </ul>
    + <p>Javascript can be used to update a cookie's value. Therefore it is possible for links to use an
    + "onclick" handler to set a cookie to contain a window-id, then perform the requested GET operation
    + and immediately reset the cookie. This causes the request to contain the needed window-id while
    + preventing the id from appearing in the page URL (where it can be bookmarked or simply copy-and-pasted).
    + In addition, the "open in new window" operation will not run the javascript so requests fetched into
    + a new window will not send a window-id and the server can detect this.</p>
    + <p>Some example code that would be rendered into the head of each page:</p>
    + <pre>
    +window.document.cookie="windowId=-1";
    +function docookie(link) {
    + window.document.cookie="windowId=3";
    + window.location.replace(link.href)
    + window.document.cookie="windowId=-1";
    + return false;
    +}
    + </pre>
    + <p>Javascript links then look like <![CDATA[<a href="someurl" onclick="docookie(this)">..</a>]]></p>
    + </section>
    +
    + <section name="Embedding a window-id in the URL">
    + <p>The window identity can be embedded within the url as a query parameter. This means that each form's
    + action url must contain the magic parameter, and so must the href of every link that is intended to be
    + clicked to perform navigation in the same frame. A request that does not contain the magic query
    + parameter is regarded as a "new window", and is allocated a new id.</p>
    + <p>Users must then be prevented from using "open in new window" on links containing the id, as that would
    + copy the magic window-id parameter and both windows would appear to the server to be the same window. This
    + can be done by setting the "href" parameter of these links to "javascript:0", and adding an onclick
    + attribute that actually does the navigation by assigning the desired url to property "window.location".
    + The FireFox browser simply does not render the "open in new window" option when the href is a javascript
    + link; Internet Explorer does render the menu option but the newly opened window is always blank.</p>
    + <p>Users will want to open new windows, however. Therefore the webapp developer can arrange for some
    + of the links to explicitly use javascript to open a new window and assign it a URL that does not have
    + the magic window-id parameter, therefore causing the request from that window to be assigned a new id.</p>
    + <p>Unfortunately this approach does have some limitations:</p>
    + <ul>
    + <li>The window-id value appears in the navigation bar, which is slightly ugly.</li>
    + <li>The window-id is saved when a bookmark is made; if two windows are opened and the same bookmark
    + activated in each then the two windows then have the same window-id. A simple copy-and-paste of the url
    + also duplicates the window-id parameter.</li>
    + <li>Javascript is required; when javascript is not enabled then the whole application becomes unusable
    + as the links are unusable (do nothing).</li>
    + </ul>
    + <p>Because of the above limitations this approach does <i>allow</i> the user to have multiple windows on
    + the same app, each with independent state, but does require them to avoid the problematic behvaiours.</p>
    + </section>
    +
    + <section name="Post-render detection of Window Properties">
    + <p>When a new window is opened, a new javascript Window object is created for it. Javascript can
    + therefore check for a property on the window and if it is not set then it can assume this is a
    + new window.</p>
    + <p>This approach is reasonably simple to implement. Its major limitations are:</p>
    + <ul>
    + <li>Javascript is required</li>
    + <li>Testing can only be done <i>after</i> a page has been rendered. When the test fails (ie this
    + is a new window) then the javascript can discard the current page and request a new one from the
    + server, this time telling the server to allocate a new window-id. However if rendering of the
    + page causes side-effects on the server then these cannot be undone. In most cases this is not an
    + issue as new pages are always populated using GET requests and these should not have side-effects.
    + </li>
    + </ul>
    + <p>The server of course also needs to be told about the id, so this would need to be combined
    + with something like the "Embedding a window-id in the URL" approach. However it does work around
    + some of the limitations of that approach by detecting when a "forbidden" user operation has occurred.</p>
    + <p>This approach was (AFAIK) invented by the Apache Wicket project.</p>
    + <p>The fact that new-window-detection occurs after rendering makes this unsuitable for handling
    + multiple windows with respect to Orchestra access-scope. Access-scoped beans within the per-window-state
    + (conversation context) associated with the current window are purged following rendering of a new view;
    + unforunately if it is later discovered on the browser that this request was rendered into a new window
    + (ie should have run in a new conversation context) then it is too late to "unpurge" the conversation
    + context.</p>
    + </section>
    +
    + <section name="Orchestra Multiple Window Support">
    + <p>Orchestra currently implements the "Embedding a window-id in the URL" approach. It overrides method
    + ServletResponse.encodeURL to automatically insert a query-parameter named "conversationContext" into every url
    + rendered in the page. This can be disabled for specific links using the JSF ox:separateConversationContext
    + tag around the link; the link url will not have the magic parameter in it and therefore the request will cause
    + a new context to be allocated on the server.</p>
    + </section>
    +
    + <section name="Other Web Frameworks">
    + <p>In the documentation for various webapp frameworks and conversation-management libraries a claim
    + to handle multiple windows correctly is often found. However these appear to all be false. Spring
    + WebFlow, JBoss Seam and Apache Wicket all fail to handle multiple windows correctly despite statements
    + to the contrary in their documentation. This is not a flaw in their code; solving this correctly
    + appears to be impossible without a change to the http protocol. However it is a flaw in the
    + documentation. Claims by any other webapp framework to handle this issue 100% correctly should be
    + carefully analysed. If one is found that does appear to implement a perfect solution for this
    + approach, please contact the Orchestra mailing list!</p>
    + </section>
    +
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/multiwindow.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,240 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>Conversation Scoped Persistence</title>
    + </properties>
    +
    + <body>
    + <section name="Introduction To Conversation Scoped Persistence">
    + <p>Orchestra's persistence support aims to simplify developers life when it comes
    + to build web based applications that extensively use ORM persistence including
    + JPA (Java Persistence API), Toplink or Hibernate.</p>
    + <p>Persistent objects often participate in a conversation (ie a sequence of requests).
    + For example, an address-management module may need to read a person from a database
    + on the first request of a conversation, then later requests may modify attributes
    + and add child records for address, telephone, email, etc. Only at the end of the
    + conversation is the data saved back to the database.</p>
    + </section>
    +
    + <section name="The Problem">
    + <p>Whoever has web-application development experience with an ORM layer
    + has run into exceptions like the dreaded LazyInitializationException which
    + occurs when following a relationship from one persistent object to another,
    + or the NonUniqueObjectException that occurs if you try to <code>merge</code>
    + detached objects back into the persistence session. Most of those problems,
    + if not all, result from the fact that a persistence session is opened and closed
    + for each HTTP request. In this case, the ORM tool has no chance to manage your
    + entities for the duration of a business process - once you close a persistence
    + layer session at the end of the HTTP request, all entities are detached from the
    + persistence layer session.</p>
    + <p>The magic is to keep such a persistence session open as long as required, but
    + as short as possible, contrary to the well-known OpenSessionInView or
    + OpenSessionPerRequest-patterns. In those patterns, the session is closed too early
    + for completing a full business process. Keeping the session alive for exactly the
    + necessary timespan is one of the cool features of Apache MyFaces Orchestra.</p>
    + <p>The demarcation of such a timespan is defined by a conversation in Orchestra. A
    + conversation is completely detached from the pageflow, it doesn't matter if the
    + conversation spans multiple requests on a single page or multiple pages.</p>
    + <p>A conversation scope is (like the request or session scope) a place where you can
    + store your beans. A conversation-scoped bean will have an attached entity manager
    + which is in use for each database access until the application ends the conversation.</p>
    + </section>
    +
    + <section name="Quick review of the Java Persistence API (JPA)">
    + <p>JPA defines the concept of a "PersistenceContext", aka an EntityManager (or in Hibernate
    + terminology, a "Session"). This represents a pool of persistent objects. First the context
    + has to be created. Then data can be loaded from the database, causing objects to be created
    + and placed in the context. Objects in the context can be modified, and new objects can be
    + placed in the context. When entityManager.flush() is called, any modified data in the
    + context is written back out to the database.</p>
    + <p>When an object is read from the database which has a reference to some other persistent
    + object, what happens depends on whether that reference ("relation") is marked as "eager"
    + or "lazy":
    + <ul>
    + <li><p>For eager relations, the associated data is read immediately from the database,
    + and an object created to hold it (which is also added to the persistence context). The
    + relation can then be followed (ie the reference used) even after the associated
    + persistence context is no longer valid, as the object is already in memory.</p></li>
    + <li><p>For lazy relations, the reference in the original object points instead at a
    + JPA-created proxy object, and only if a method is invoked on the proxy is a database
    + operation triggered to load the actual object. Lazy relations are very useful, but mean
    + that the relation can only be followed while the persistence context is still valid; if
    + the proxy is triggered after the persistence context is no longer valid then a
    + LazyInitializationException occurs.</p></li>
    + </ul>
    + </p>
    + <p>A context can be closed (which automatically flushes it). When this happens, all objects in
    + the context become "detached"; code that holds references to them can still access the objects.
    + However because the context no longer exists, they cannot be written back to the database.
    + In addition, any attempt to fetch a related object causes a LazyIntializationException because
    + there is no longer a context into which the related object can be fetched.</p>
    + <p>Contexts are closed when no longer used because they do take up a lot of memory. The art of
    + persistence is to keep contexts around for as long as necessary but no longer. Note that in
    + some ORM implementations it is possible to partially discard contexts, ie to remove from the
    + context objects that are known to no longer be needed, but that is not a general-purpose
    + solution; it is just too hard to manually track exactly what is in use and what is not.</p>
    + <p>An object which has been detached (ie whose context has been closed) can be reattached to a
    + different context. This allows code to load an object, detach it, modify it and later
    + (potentially days later) create a new context, reattach the object then flush the new
    + context causing that object to be written to the database. Of course if the database has
    + been modified in the meantime then the save will fail.</p>
    + <p>The above information about JPA also applies to Hibernate and Toplink, which work in
    + a very similar manner.</p>
    + </section>
    +
    + <section name="Using EJBs (separated web tier and business logic)">
    + <p>When using the full jee framework, the web and logic tiers are strongly separated, and may be
    + on separate physical machines. The logic tier (EJBs) are responsible for performing all
    + database access; they use declarative security and other mechanisms to ensure that external
    + code (including a web tier, native gui applications, etc) can only read data that they have
    + rights to read, and can only modify data via the APIs provided by the EJBs.</p>
    + <p>In this case, the web tier has no database connection, and clearly can only navigate relations
    + that are present in the serialized data returned by EJBs. In the old days (before JPA),
    + fields representing such relationships would simply be null, and accessing them would
    + trigger a NullPointerException or similar. If an EJB uses JPA to load objects, then
    + returns those objects to a remote client, then any attempt to navigate a relationship
    + that is not populated will instead result in a LazyInitializationException; the effect
    + is the same but the difference exists because JPA uses proxy objects to implement lazy
    + loading. These proxy objects get returned along with the "real" data, but as there is
    + no longer a context that the real referenced objects can be loaded into (and no
    + database connection to do it with!) they cannot execute.</p>
    + <p>In practice, this does mean that the EJB tier has to be very aware of the needs of its
    + presentation tier (eg the web tier), but this does seem unavoidable, and is the price
    + of the strong separation between business and presentation.</p>
    + <p>Because an application using this architecture provides no database connection to
    + the web tier, Orchestra <i>can not provide any support for conversation-scoped persistence
    + contexts</i>. Orchestra's persistence support is only for use with applications that have
    + their business logic and presentation logic in the same tier.</p>
    + <p>Note that JBoss Seam provides similar "conversation-scoped" persistence support, but this
    + also only applies when the business logic and the presentation logic are in the same
    + "tier". When remote EJBs are used to implement interactions with the database then
    + there is simply nothing the web tier can do about this.</p>
    + </section>
    +
    + <section name="Single Tier Applications -- Old Style">
    + <p>Much code that does not use EJBs is nevertheless written in the stateless-session-bean
    + style. When displaying a persistent object a backing bean method will open a
    + persistence-context, read the relevant objects into it and then close the context.
    + JSF components then render the object, but must be careful not to access any
    + relations that were not initialised before the context was closed. A later action
    + method which wants to save data will open a new context, reattach the object
    + retrieved earlier, flush the context to the database, then close the context again.</p>
    + <p>An alternative is to allow the object context to exist for the entire http request,
    + closing it only when the request is about to return (after render phase). This is
    + referred to as the "Open Session In View" pattern. In this way, the context is cached
    + (eg in a thread-local variable) for the duration of the request, and any JSF action
    + method that wants to access persistent objects just retrieves that context and uses
    + it. This is an extremely useful pattern, with no known drawbacks.</p>
    + <p>However with "Open Session In View" the context is still tied to just one request.
    + This still exposes the application to potential LazyInitialisationExceptions, as
    + follows:
    + <ul>
    + <li><p>request #1 loads an object from the database and stores it in the http session.
    + The page is nicely rendered, and no LazyInitialisationException can occur. The pool
    + is closed at the end of the request.</p></li>
    + <li><p>request #2 is executed, which tries to display more data from the object that
    + is cached in the session. That data is not currently loaded, however, and the
    + object is no longer in a context. An exception therefore occurs.</p></li>
    + </ul>
    + </p>
    + </section>
    +
    + <section name="Single Tier Applications -- With Conversation Scoped Persistence">
    + <p>The solution to the problems described above is simply to store the PersistenceContext
    + object in the http session, and only close it after the conversation has ended, ie
    + when it has been decided to write to the database or abandon any changes made.</p>
    + <p>Although the default behaviour of JPA is to close the persistence context when a
    + transaction commits or rolls back, this is optional and simply disabling this allows
    + the persistence context to be cached over multiple requests. Instead, the db
    + connection associated with the persistence context is simply removed from the
    + context at the end of each request and returned to the connection pool. At the
    + start of the next request a different connection is retrieved from the db pool
    + and attached to the persistence context again.</p>
    + <p>Note that database transactions still occur; typically a transaction is started
    + on the context's connection at the beginning of each request and committed at the
    + end of each request. However as long as no flush() operation has been invoked on
    + the context, modifications made to objects in the context do not get written to
    + disk. Of course it is not possible for a real database transaction to be kept
    + open across requests, as that would require the database to keep rows in the
    + database locked for as long as the http session lasts (potentially hours), which
    + is simply unacceptable.</p>
    + <p>There are dangers to this approach; a persistence context can become large if
    + many objects have been loaded into it. Care needs to be taken to control the
    + amount of persistent data read/written during a conversation. Manual removal
    + of objects from the context which are no longer needed can be useful, or
    + secondary persistence contexts can be created to perform operations on objects
    + that are not needed to be kept in the conversation scope - particularly reads of
    + objects that will not be modified as part of the conversation.</p>
    + <p>There is also a potential problem when inserting new objects into the context
    + which have a database key that is generated via a database write. In this case,
    + the database write occurs in the request in which the object was added to the
    + context, even though the object's data does not get written until the end of
    + the conversation. If the conversation is "rolled back" then the key operation
    + remains, as that transaction has long since been committed.</p>
    + </section>
    +
    + <section name="Handling Transactions">
    + <p>The scope of a persistence context and database transaction boundaries
    + (begin/commit) are separate issues. Multiple database transactions *can*
    + occur within the lifetime of a single persistence context. It isn't the
    + default - by default, close/rollback will close the associated context.
    + However it is possible to disable this default in which case the
    + persistence-context can last longer.</p>
    + </section>
    +
    + <section name="How to Use Orchestra Conversation Scoped Persistence">
    + <p>When configured appropriately, Spring will automatically scan the beans
    + it loads for the standard persistence annotations, and injects a persistence
    + context where requested by the bean. Orchestra ensures that the persistence
    + context Spring injects is the appropriate one for the current conversation.</p>
    + <p>Your code is therefore simply straightforward:<pre>
    +import javax.persistence.EntityManager;
    +import javax.persistence.PersistenceContext;
    +public class ComponentDAO
    +{
    + @PersistenceContext
    + private EntityManager entityManager;
    + ....
    +}
    + </pre></p>
    + <p>Spring's annotation support does require, however, that the class containing
    + the annotation be declared as a Spring bean, and instantiated via Spring. This
    + means that all code which uses an instance of the above class needs to have it
    + injected, rather than using the new() operator to create the instance. Existing
    + code therefore may need to be restructured to take advantage of persistence
    + annotations with Orchestra. The persistence context object that Spring injects
    + is actually a proxy which looks up the correct EntityManager object to use
    + on each method call, so it is safe to use singleton scope (Spring's default
    + scope). Of course if the class has any other non-static members then the
    + scope should be set to "prototype", to avoid conflicts between different
    + instances of this class in different conversations.</p>
    + </section>
    +
    + <section name="Documentation Still TODO">
    + <p>TODO: document Orchestra's transaction support features</p>
    + <p>TODO: is the persistence-context serializable? Are all persistent objects
    + in the context always serializable?</p>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/persistence.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,35 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>Apache MyFaces Orchestra - TODO</title>
    + </properties>
    +
    + <body>
    + <section name="TODO">
    + <ul>
    + <li>...</li>
    + </ul>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/todo.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,263 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +
    +<document>
    + <properties>
    + <title>Usage</title>
    + </properties>
    +
    + <body>
    + <section name="Usage">
    + <p>
    + Once you have configured the system as described in
    + the installation document you can start using the new scope.
    + </p>
    +
    + <p>
    + One more prerequisite: instead of configuring your beans in the faces-config.xml
    + configuration you have to do this in your spring configuration now. You can
    + take over all your beans into the Spring configuration, Spring also provides
    + a session and a request scope.
    + </p>
    +
    + <p>
    + With this in place, we'll start evaluating the Orchestra-relevant use-cases now - so we'll
    + together look at what you will want to do with Orchestra.
    + </p>
    +
    + <subsection name="Starting a conversation">
    + In the beginning, we'll want to start a conversation. Doing that is a no-brainer in Orchestra - if
    + you've declared the relevant managed beans as in the following example:
    +<code><pre>
    +&lt;bean name="userInfo"
    + class="my.app.pck.backings.UserInfo"
    + scope="conversation.access"
    + autowire="byName"/&gt;
    +&lt;/bean&gt;
    +</pre></code>
    + <p>
    + We've learned about this syntax in the small example in the introduction - a short repetition:
    + <br/>
    + The scope-attribute of the bean-element will be defining the name of the scope; the
    + names can be whatever you like but we recommend "conversation.access" and "conversation.manual".
    + </p>
    + <p>The
    + <code>autowire="byName"</code>
    + Setting this property is fully optional. However, it
    + lowers the amount of configuration required. With this property set, Spring will scan your
    + bean configuration. Whenever it finds a bean with the same name as the property, it
    + will inject an instance of this bean configuration into this property.
    + </p>
    + <p>For example, if you configure a bean named
    + <code>userInfoDao</code>
    + and your bean has a
    + <code>setUserInfoDao()</code>
    + method Spring will inject an instance of this DAO into your bean.
    + </p>
    + <p>
    + Alternatively you could provide a custom conversation name:
    + </p>
    +<code><pre>
    +&lt;bean name="bean1"
    + class="my.app.pck.backings.bean1"
    + scope="conversation.manual"
    + orchestra:conversationName="multibean"
    + autowire="byName"/&gt;
    +
    +&lt;bean name="bean2"
    + class="my.app.pck.backings.bean2"
    + scope="conversation.manual"
    + orchestra:conversationName="multibean"
    + autowire="byName"/&gt;
    +</pre></code>
    + <p>
    + As you can see in the above example we put two beans into the same conversation, which
    + means they share the same persistence context.<br />
    + This opens the possibility to keep the "one class per page" paradigm and still
    + allows you to pass entities between these two pages (e.g. Master/Detail scenarios).
    + </p>
    + </subsection>
    +
    + <subsection name="Closing a conversation">
    + <p>
    + Closing a conversation is straightforward as well. If the bean is in a scope
    + that has been marked with lifetime=access then the conversation terminates
    + when a request is processed without referring to anything in that conversation.
    + If you've using a "manual" conversation instead, then you need to call:
    + <pre>
    + <code>Conversation.getCurrentInstance().invalidate()</code>
    + </pre>
    + from within the conversation-scoped bean. With this call, the conversation will cease to exist
    + and the bean will be cleared from the conversation.
    + </p>
    + </subsection>
    +
    + <subsection name="Restart a conversation">
    + <p>
    + At times, you do not only want to close a conversation, but you also want to restart it
    + immediately. For this, use the following call:
    + <pre>
    +public void invalidateAndRestart()
    +{
    + YouBean bean = (YourBean)
    + ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance());
    + bean.setUser(createdUser.getId());
    +}
    + </pre>
    +
    + With the returned object, you can do configuration and initialization work.
    + </p>
    + </subsection>
    +
    + <subsection name="Ensure a conversation is running">
    + <p>
    + If you have a conversation running over a multitude of pages,
    + you might want to check if the conversation has been initialized before you reach the page.
    + For doing this, you can call the method:
    +
    + <code>ConversationUtils.ensureConversationRedirect(conversationName, redirectToJsp)</code>
    +
    + before the conversation is first accessed on this page, as in an initialization or
    + prerender-method.
    + </p>
    + </subsection>
    +
    + <subsection name="End a conversation by name">
    +<code>ConversationUtils.invalidateIfExists(conversationName)</code>
    + </subsection>
    +
    + <subsection name="JPA Transaction">
    + <b>Note</b>
    + :
    + Once again we would like to stress that Apache MyFaces Orchestra does not rely
    + on annotations, the JPA thing was just the one we build the examples with,
    + thats why we describe it at first.
    + <p>Every method in your conversation
    + bean is able to issue a database request or to call e.g. a DAO which will
    + do it. Its ensured that during the whole lifetime of this conversation
    + bean all database code will see the same entity manager.
    + </p>
    + <p>Methods
    + which change data has to be annotated with the
    + <code>@Transactional</code>
    + annotation.
    + </p>
    + <p>Which means, that every changed/inserted/deleted entity
    + will be flushed to the database and committed.
    + </p>
    + <p>Thats an important
    + thing to understand. You
    + <b>can</b>
    + change an entity whenever you want,
    + but it will only be flushed after such an annotated method has been
    + invoked.
    + </p>
    +
    +
    + </subsection>
    +
    + <subsection name="Access a conversation">
    +
    + <p>
    + From within a conversation scoped bean you can use
    +
    + <code>Conversation.getCurrentInstance()</code>
    +
    + or the ConversationManager API if you are outside of a conversation or would like to access another
    + conversation
    +
    + <code>ConversationManager.getConversation(conversationName)</code>
    + </p>
    +
    + </subsection>
    +
    + <subsection name="Add beans to a conversation">
    + As e.g a http session or the request map, internally the conversation is also just a map
    + of beans.
    + <br/>
    + Using the spring configuration you're able to add just one bean, the conversation scoped
    + bean to the conversation with the same name as the bean.
    + <br/>
    + But there are ways to add other objects using the Conversation API.
    +
    + <p>
    + Once you have access to the conversation object you can do:
    +
    + <ul>
    + <li>conversation.setAttribute(key, value)</li>
    + <li>conversation.hasAttribute(key)</li>
    + <li>conversation.getAttribute(key)</li>
    + <li>conversation.removeAttribute(key)</li>
    + </ul>
    + </p>
    +
    + <p>
    + Any bean implementing the <code>ConversationBindingListener</code> interface
    + will receive the <code>valueBound()/valueUnbound()</code>.
    +
    + <ul>
    + <li>valueBound()<br/>
    + Will be invoked AFTER the bean has been added to the conversation map.
    + </li>
    +
    + <li>valueUnbound()<br/>
    + Will be invoked AFTER the bean has been removed from the conversation map.<br/>
    + This will happen if you call <code>removeAttribute(key)</code> or if the
    + conversation ends, either manually or automatically due to a timeout.
    + </li>
    + </ul>
    +
    + <b>Notice:</b> In <code>valueUnbound()</code> you can't assume that a faces context
    + will be available.
    + </p>
    + </subsection>
    +
    + <subsection name="Using older Orchestra Releases">
    + <p>
    + The documentation above applies to the most recent Orchestra code. When using older
    + releases, the following information is useful.
    + </p>
    + <subsection name="Using aop:scoped-proxy">
    + <p>
    + For Orchestra 1.0, you should add an <code>&lt;aop:scoped-proxy /&gt;</code>
    + within the declaration of each bean that is of conversation scope. This ensures
    + that you will never have a reference to the real instance of your bean, but to
    + a proxy to it. There is no difference in the way how you work with this instance
    + in your code, but if you end a conversation and restart it, you'll appreciate the
    + difference: the proxy will make sure that your application will see the new instance.
    + </p>
    + <p>
    + This is automatically done for you with Orchestra 1.1 and later.
    + </p>
    + </subsection>
    + <subsection name="Flash Scope">
    + In version 1.0, the name "flash scope" was used for what is now called
    + "access scope". The two concepts are the same; when using orchestra 1.1
    + you must simply write "flash" wherever the more modern documentation
    + states "access". Orchestra 1.1 supports the old term for backwards
    + compatibility, so configuration files written for 1.0 should work fine
    + with release 1.1.
    + </subsection>
    + </subsection>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/usage.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

    Added: myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml
    URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml?rev=1326868&view=auto
    ==============================================================================
    --- myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml (added)
    +++ myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml Tue Apr 17 01:29:52 2012
    @@ -0,0 +1,210 @@
    +<?xml version="1.0" encoding="UTF-8"?>
    +<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
    + "http://www.apache.org/dtd/xdoc.dtd">
    +<!--
    + Licensed to the Apache Software Foundation (ASF) under one
    + or more contributor license agreements. See the NOTICE file
    + distributed with this work for additional information
    + regarding copyright ownership. The ASF licenses this file
    + to you 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.
    + -->
    +<document>
    + <properties>
    + <title>ViewController</title>
    + </properties>
    +
    + <body>
    + <section name="View Controller">
    + <p>
    + The ViewController is just a concept which binds a specific bean to a web-page.
    + In JSF this means, you have a managed bean associated with each view.
    + Note however that the ViewController is not limited to JSF; any framework can take
    + advantage of it to cause lifecycle method callbacks to occur for each page.
    + </p>
    + <p>
    + Using the Orchestra ViewController gives some very convenenient facilities.
    + </p>
    + <p>
    + Methods in your code can be invoke when the following events occur:
    + <ul>
    + <li>initView
    + <br />
    + This event will be fired after the JSF <code>RESTORE_VIEW</code> phase.
    + </li>
    + <li>preProcess
    + <br />
    + This event will be fired before the JSF <code>INVOKE_APPLICATION</code> phase.
    + </li>
    + <li>preRenderView
    + <br />
    + This event will be fired before the JSF <code>PRE_RENDER</code> phase.
    + </li>
    + </ul>
    + </p>
    + <p>
    + The ViewController concept is also the base for the core15 annotation
    + <code>@ConversationRequire</code> which allows you to issue a redirect if a
    + conversation times-out during a wizard-style pageflow.
    + </p>
    + <p>
    + Your view controller bean (the object on which callback methods are invoked) must
    + be configured as a managed bean (eg as a Spring bean).
    + </p>
    +
    + <subsection name="Installation">
    + <p>
    + There are several parts to managing ViewControllers; the ViewControllerManager handles
    + the following tasks:
    + <ul>
    + <li>Choosing which object to invoke methods on (ViewControllerNameMapper)</li>
    + <li>Choosing which methods to invoke (ViewControllerExecutor)</li>
    + <li>Choosing when to invoke them</li>
    + </ul>
    + </p>
    + <p>
    + In a JSF environment, the default ViewControllerManager is set up with behaviour that
    + should suit most users. However this can be customised if the defaults do not suit.
    + See the javadoc documentation for the ViewControllerManager and related classes
    + for details on how to customise configuration.
    + </p>
    + </subsection>
    +
    + <subsection name="ViewControllerNameMapper">
    + <p>
    + The default ViewControllerNameMapper maps a viewId to a bean-name as follows:
    + <ul>
    + <li>Convert each character after a "/" to upper-case</li>
    + <li>Remove any occurence of the "/" character</li>
    + <li>Stop at the first "." character and remove the rest</li>
    + <li>Prefix with a "_" character if the result is a reserved word or an invalid bean name</li>
    + </ul>
    + Examples:
    + <table>
    + <tr>
    + <th>View-Id</th>
    + <th>Bean name</th>
    + </tr>
    + <tr>
    + <td>mainform.jsp</td>
    + <td>mainform</td>
    + </tr>
    + <tr>
    + <td>userData/password.jsp</td>
    + <td>userDataPassword</td>
    + </tr>
    + <tr>
    + <td>requestScope.jsp</td>
    + <td>_requestScope</td>
    + </tr>
    + <tr>
    + <td>123set.jsp</td>
    + <td>_123set</td>
    + </tr>
    + </table>
    + </p>
    + <p>
    + If no bean exists with a name that matches the computed bean-name, then no lifecycle
    + events are invoked for that view.
    + </p>
    + <p>
    + When the Orchestra core15 module is in the classpath, then annotations can also
    + be used to specify that a bean is a ViewController for a specific view. See the
    + section on the AnnotationsViewControllerNameMapper for details.
    + </p>
    + </subsection>
    +
    + <subsection name="ViewControllerExecutor">
    + <p>
    + The default ViewControllerExecutor is a CompositeViewControllerExecutor which combines
    + the functionality of the following classes:
    + <ul>
    + <li>ReflectiveViewControllerExecutor (default)
    + <br />
    + The <code>ReflectiveViewControllerExecutor</code> uses reflection to lookup the
    + following public methods: initView, preRenderView, preProcess. <br />
    + All of the methods are optional.
    + </li>
    + <li>InterfaceViewControllerExecutor
    + <br />
    + The <code>InterfaceViewControllerExecutor</code> requires you to implement the
    + <code>org.apache.myfaces.orchestra.viewController.ViewController</code> interface.
    + </li>
    + </ul>
    + </p>
    + <p>
    + When the Orchestra core15 module is in the classpath, then annotations can also
    + be used to specify which methods on a bean should be invoked to handle lifecycle
    + events. See the section on the AnnotationsViewControllerExecutor for details.
    + </p>
    + </subsection>
    +
    + <subsection name="AnnotationsViewControllerNameMapper">
    + <p>
    + To work with the <code>AnnotationsViewController</code> you have to use the core15
    + module. Once you added the jar to your classpath and configured the
    + <a href="installation.html">required import</a> statement
    + in your configuration file you are done.
    + </p>
    + <p>
    + The biggest advantage of <code>AnnotationsViewControllerNameMapper</code> is that you
    + do not have to follow any bean-naming scheme. Just annotate your managed-bean with the
    + <code>@ViewController</code> annotation.
    + </p>
    + <p>
    + Example:
    + <pre>
    +@ViewController(
    + viewIds={"/annotations/Page1.jsp", "/annotations/Page2.jsp", "/annotations/Page3.jsp"})
    +public class MultiViewController
    + </pre>
    + </p>
    + <p>
    + This configuration means that the class <code>MultiViewController</code> is responsible
    + for the three configured pages and will receive the lifecycle method callbacks.
    + </p>
    + </subsection>
    +
    + <subsection name="AnnotationsViewControllerExecutor">
    + <p>
    + The <code>AnnotationsViewControllerExecutor</code> allows the methods to be
    + invoked to be marked via annotations. The methods can then have any name, and
    + the bean on which they exist does not need to implement any specific interface.
    + This is a feature of the core15 module, and is automatically enabled if the
    + Orchestra core15 library is in the classpath.
    + </p>
    + <p>
    + The available annotations are:
    + <ul>
    + <li>@InitView</li>
    + <li>@PreProcess</li>
    + <li>@PreRenderView</li>
    + </ul>
    + </p>
    + </subsection>
    +
    + <subsection name="Comparison with the Apache Shale ViewController">
    + <p>
    + The ViewController concept in Orchestra was inspired by the Apache Shale ViewController,
    + and is very similar. Unfortunately the Shale version could not be used directly in
    + Orchestra; it is hoped that at some time in the future the two implementations can
    + be unified in some manner.
    + </p>
    + <p>
    + The Orchestra implementation currently lacks the ability for f:subview pages to have
    + their own view-controller.
    + </p>
    + </subsection>
    + </section>
    + </body>
    +</document>

    Propchange: myfaces/orchestra/trunk/maven/src/site/xdoc/viewController.xml
    ------------------------------------------------------------------------------
    svn:eol-style = native

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupcommits @
categoriesmyfaces
postedApr 17, '12 at 1:30a
activeApr 17, '12 at 1:30a
posts2
users1
websitemyfaces.apache.org

1 user in discussion

Lu4242: 2 posts

People

Translate

site design / logo © 2019 Grokbase