myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lu4...@apache.org
Subject svn commit: r1326868 [1/2] - in /myfaces/orchestra/trunk: core/src/site/ core/src/site/xdoc/ maven/src/site/ maven/src/site/xdoc/
Date Tue, 17 Apr 2012 01:29:53 GMT
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



Mime
View raw message