You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/09/06 11:53:42 UTC
svn commit: r573204 - in /myfaces/orchestra/trunk/core/src/site: site.xml
xdoc/conversation.xml xdoc/introduction.xml xdoc/persistence.xml
Author: skitching
Date: Thu Sep 6 02:53:42 2007
New Revision: 573204
URL: http://svn.apache.org/viewvc?rev=573204&view=rev
Log:
Improve docs
Added:
myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml
myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml
Modified:
myfaces/orchestra/trunk/core/src/site/site.xml
myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
Modified: myfaces/orchestra/trunk/core/src/site/site.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/site.xml?rev=573204&r1=573203&r2=573204&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/site.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/site.xml Thu Sep 6 02:53:42 2007
@@ -60,7 +60,7 @@
</menu>
<menu name="MyFaces Orchestra - Core">
- <item name="Introduction and Glossary" href="introduction.html"/>
+ <item name="Introduction" href="introduction.html"/>
<item name="Glossary" href="glossary.html"/>
<item name="Installation" href="installation.html"/>
<item name="Conversation API Usage" href="usage.html"/>
Added: myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml?rev=573204&view=auto
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml (added)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/conversation.xml Thu Sep 6 02:53:42 2007
@@ -0,0 +1,164 @@
+<?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 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" or a "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>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 stored in request scope to be passed
+ through to a subsequent request. 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 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.
+ This solution does require that the Spring Framework be used to declare
+ conversation-scoped managed beans rather than the standard JSF facility. However
+ there are many other good reasons to use Spring...
+ </p>
+
+ <p>
+ Various other projects (JBoss Seam, Apache Shale Dialogs) provide
+ conversation/dialog support that is similar to Orchestra. See
+ the Orchestra wiki pages for up-to-date comparisons of Orchestra with other projects.
+ </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 a scope of "conversation" 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 "session" scope for these beans.
+ However a conversation acts as a "container" 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>a JSF endConversation component is provided that can be inserted into a page;</p></li>
+ <li><p>a direct call can be made from a backing bean, eg after performing a "save" or "cancel" operation;</p></li>
+ <li><p>flash conversations end when a request occurs that does not access any bean in that conversation;</p></li>
+ <li><p>a conversation timeout can be configured to automatically expire conversations after a specified time limit.</p></li>
+ </ul>
+ And as conversations have names, multiple conversations (bean groupings) can exist concurrently.
+ </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 "policy" of "manual" or "flash".
+ A "flash" conversation is automatically ended (ie deleted) if a request is executed
+ which does not reference any bean in that conversation's scope. This is
+ very convenient when a sequence of pages all have at least one reference
+ 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>
+ </body>
+</document>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml?rev=573204&r1=573203&r2=573204&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml Thu Sep 6 02:53:42 2007
@@ -22,205 +22,21 @@
<document>
<properties>
- <title>About Apache MyFaces Orchestra</title>
+ <title>The Apache MyFaces Orchestra Core Module</title>
</properties>
<body>
- <section name="Apache MyFaces Orchestra">
- <p>Apache MyFaces Orchestra aims to
- simplify developers life when it comes to build web based applications,
- especially when they build on a persistence layer including object-relational-mapping tools
- such as a JPA implementation (e.g. Toplink or Hibernate).
+ <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>Whoever has web-application development experience with an ORM layer
- has run into exceptions like the dreaded LazyInitializationException
- or the NonUniqueObjectException that occurs if you try to
- <code>merge</code>
- your 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> So, the magic is to keep such a persistence session open
- as long as required, but as short as possible; contrary to the often
- propagated 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>
- <p>There is a lot of ambiguous wording in the area of persistence; before we start we'll provide some definitions
- so that we talk about the same concepts in the same words.
- </p>
-
-
- <subsection 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" or a "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>Application scope</li>
- <li>Session scope</li>
- <li> Request scope</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>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.</li>
- <li>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.
- </li>
- </ul>
- </p>
-
- <p>
- The Tomahawk library provides a partial solution to this conversation problem with
- the t:saveState tag, which allows data stored in request scope to be passed
- through to a subsequent request. 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 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.
- This solution does require that the Spring Framework be used to declare
- conversation-scoped managed beans rather than the standard JSF facility. However
- there are many other good reasons to use Spring...
- </p>
-
- <p>
- Various other projects (JBoss Seam, Apache Shale Dialogs) provide
- conversation/dialog support that is similar to Orchestra. See
- the Orchestra wiki pages for up-to-date comparisons of Orchestra with other projects.
- </p>
- </subsection>
-
- <subsection 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,
- including "conversation". 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 "session" scope for these beans.
- However a conversation acts as a "container" 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>a JSF endConversation component is provided that can be inserted into a page;</li>
- <li>a direct call can be made from a backing bean, eg after performing a "save" or "cancel" operation;</li>
- <li>flash conversations end when a request occurs that does not access any bean in that conversation;</li>
- <li>a conversation timeout can be configured to automatically expire conversations after a specified time limit.</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 "policy" of "manual" or "flash".
- A "flash" conversation is automatically ended (ie deleted) if a request is executed
- which does not reference any bean in that conversation's scope. This is
- very convenient when a sequence of pages all have at least one reference
- 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>
- </subsection>
-
- <subsection name="Structure">As of now, the Apache
- MyFaces Orchestra project contains 3 modules.
- <ul>
- <li>core
- <br/>
- The core module is compatible with Java 1.4 - which means that you are
- able to use all this convenient stuff without the need to migrate to
- Java 5.0
- </li>
-
- <li>core15
- <br/>
- Ok, we admit, we couldn't resist, this package will contain
- Java 5.0 enhancements to the core, so that you get some of the cool new annotation based
- stuff as well.
- </li>
-
- <li>examples
- <br/>
- The examples module includes a demo app (one currently) showing off many of Orchestra's
- features.
- </li>
- </ul>
- </subsection>
+ <p>Orchestra Core requires only Java 1.4 and JSF 1.1.</p>.
</section>
</body>
</document>
Added: myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml?rev=573204&view=auto
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml (added)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml Thu Sep 6 02:53:42 2007
@@ -0,0 +1,56 @@
+<?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="Apache MyFaces Orchestra Core">
+ <p>Apache MyFaces Orchestra aims to simplify developers life when it comes
+ to build web based applications, especially when they build on a persistence
+ layer including object-relational-mapping tools such as a JPA implementation
+ (e.g. Toplink or Hibernate).</p>
+ <p>Whoever has web-application development experience with an ORM layer
+ has run into exceptions like the dreaded LazyInitializationException
+ or the NonUniqueObjectException that occurs if you try to <code>merge</code>
+ your 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>So, the magic is to keep such a persistence session open as long as required, but
+ as short as possible; contrary to the often propagated 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>
+ </body>
+</document>