You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by im...@apache.org on 2007/05/24 18:02:58 UTC
svn commit: r541343 - in /myfaces/orchestra/trunk/core/src/site/xdoc:
about.xml alternative-configuration.xml bestPractice.xml
conversationManagement.xml index.xml usage.xml
Author: imario
Date: Thu May 24 09:02:57 2007
New Revision: 541343
URL: http://svn.apache.org/viewvc?view=rev&rev=541343
Log:
reviewd ... err ... rewritten documentation from martin, more to come tomorrow.
Modified:
myfaces/orchestra/trunk/core/src/site/xdoc/about.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/conversationManagement.xml
myfaces/orchestra/trunk/core/src/site/xdoc/index.xml
myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/about.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/about.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/about.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/about.xml Thu May 24 09:02:57 2007
@@ -1,6 +1,5 @@
<?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">
<document>
<properties>
<title>About Apache MyFaces Orchestra</title>
@@ -10,86 +9,74 @@
<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 have to deal with Object-Relational-Mapping tools
- like JPA or Hibernate.
+ 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>Everyone who ever developed an application
- without a framework like JBoss Seam, but wanted to use such a ORM tool,
- might have seen all those anoying things like LazyInitializationException
- or the problems you have if you try to
+ <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 session. Most of those problems, if not all, result
- from the fact that opening and closing a session for each HTTP request,
- wich means, that the ORM tool has no chance to manage your entities any
- more. Once you closed a session all your entities are detached from it. At
- the next request the ORM tool has no knowledge of these entities and can't
- manage them any more.
- </p>
- <p>So, the magic is to keep such a session open
- as long as required, but as short as possible.
- </p>
- <p>Later a so called
- OpenSessionInView technologie come up which allowed you to use a session
- at least for the same page. This is fine, but didn't help if you have to
- deal with a pageflow or dialogs where more than a single page is required
- to finish a job.
- </p>
- <p>The next buzzword in this context is
- "ApplicationTransaction", now we reached the conversation scope. The
- duration of an ApplicationTransaction is given - what a wonder - from the
- application. It is completely detached from the pageflow. Regardless if it
- spans multiple requests on an single page or multiple pages, the
- application will start and stop the ApplicationTransation.
- </p>
- <p>Apache
- MyFaces Orchestra; inspired from JBoss Seam; introduce the conversation scope
- to deal with this kind of workflow.
+ 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.
+ The ORM tool has then no chance to manage your entities for the duration of a
+ business process - once you close a persistence session at the end of the HTTP request,
+ all entities are detached from the persistence 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 put your beans to. The
- difference between the latter two and the conversation scope is, that it
- will also provide a way how to deal with - so called - long
- sessions.
- </p>
- <p>A bean, put into the conversation scope, will get an
- entity manager attached which will be used for each database access until
+ 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 are tons of buzzwords
- in the area of persistence, so, before we start I'll make some definitions
- so that we surely talk about the same things.
+ <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 things.
</p>
<subsection
name="Definitions">
<ul>
- <li>pojo
+ <li>POJO
<br/>
- Plain-Old-Java-Object, following the Java Bean standard
- this is a class with (mostly) private members and a get and set method
- (also called as getter and setter) for each of them. The original aim
- of the ORM tools was to persist such pojos into the database with the
+ 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 its common to use annotations in the java
- source itself, though, now its hard to speak from pojos again.
+ 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
+ <li>Entity
<br/>
- A pojo with an extended description for the entitiy
- manger to allow it to be persisted into the database. Common
- descriptions are XML files or annotations in the java source. This
+ 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
+ <li>Property
<br/>
- A property is a member variable of your pojo with a
- set and get method defined. You have to follow the Java Bean
- specification. Some examples are:
+ 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>Member</th>
+ <th>property</th>
+
+ <th>member</th>
<th>getter</th>
@@ -97,7 +84,9 @@
</tr>
<tr>
- <th>userId</th>
+ <td>userId</td>
+
+ <td>private String userId</td>
<td>getUserId</td>
@@ -105,18 +94,31 @@
</tr>
<tr>
- <th>_userName</th>
+ <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
+ <li>Entity Manager
<br/>
- The "entity manager" manage all your entities,
+ 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
@@ -124,74 +126,74 @@
afterwards.
</li>
- <li>entity manager factory
+ <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 them.
+ entity manager based on it.
</li>
<li>DAO - Data Access Object
<br/>
Mostly a singleton which contains
- all (or most) of the database requests your application will issue.
- Thus, the DAO is the one which has to get access to an entity
+ all of the database requests your application will issue.
+ Thus, the DAO is injected with an entity
manager.
</li>
- <li>conversation
+ <li>Conversation
<br/>
A conversation is the bracket for all the
- database operations required to finish a job. Aliases are: application
- transaction, unit-of-work
+ database operations required to finish a process.
+ Other names of this principle are: application transaction, unit-of-work
</li>
- <li>session scope
+ <li>Session Scope
<br/>
The session scope of your servlet container.
- Beans put into this scope live until a inactivity timout has been
- reached
+ Beans put into this scope live until the configured inactivity timout
+ for the session has been reached.
</li>
- <li>request scope
+ <li>Request Scope
<br/>
The request scope of your servlet container.
- The lifetime of those beans is only as long as the duration of a
- single HTTP request. Say, once the servlet container finished sending
+ The lifetime of those 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 standardize the way how
- you have to annotate your entities. That way you can change (in
- theory) the ORM tool as long as the ORM tool follows the JPA
- specificatoins.
+ 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, its
+ (jsp, facelet, etc page). While JSF does not require such a bean, it is
good practice to do it that way.
</li>
</ul>
</subsection>
- <subsection name="Structure">As per now, the Apache
- MyFaces Orchestra contains 3 modules.
+ <subsection name="Structure">As of now, the Apache
+ MyFaces Orchestra project contains 3 modules.
<ul>
<li>core
<br/>
- The core is compatible with Java 1.4, means, you are
- able to use all this comfortable stuff without the need to migrate to
+ The core 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, but we couldn't resist, this package will contain
- Java 5.0 enhancements to the core.
+ 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 stuff as well.
</li>
<li>examples</li>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/alternative-configuration.xml Thu May 24 09:02:57 2007
@@ -14,7 +14,7 @@
<subsection name="Prerequisites">
- <ul>
+ <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>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/bestPractice.xml Thu May 24 09:02:57 2007
@@ -9,50 +9,38 @@
<body>
<section name="Best Practice">
- This page should give some guidance to some best practices
- we think should be applied to reach the fastest result.
-
-
- <br/>
- Feel free to adopt them, feel free to ignore them.
-
- <p>
- In various tests and implementations it became clear very early that the best approach
- is, to have a single page controller under one conversation for one page in most cases.
- </p>
- <p>
- The reason for this self imposed limitation is that if you end up with too many conversations
- things become complicated and if you use the conversations on a non page controller level, you will
- lose some functionality the internal view handler mechanisms of orchestra expose to your bean.
- </p>
- <p>
- Note, that all beans under one page controller are under the same conversation, unless they
- already are under a different conversation scope when assigned!
- </p>
-
- <subsection name="Component bindings">
- <p>
- Read something about <a href="component-bindings.html">component binding and the scoping problem</a>.
- </p>
- <p>
- This document is not related to Apache MyFaces Orchestra. It's a good reading for every JSF developer.
- </p>
- </subsection>
+ This page will provide you with guidance to best practices
+ in using Apache MyFaces Orchestra - generally, it's better to
+ adhere to these principles.
<subsection name="Single Page Conversation">
<p>
- Single Page conversations are easy, just put the bean, representing your view controller, into the conversation scope und use
- it in your value-/methodbinding.
+ In many cases, it is the easiest approach to
+ provide a single managed bean per view.
+ Single Page conversations are easy - put the bean representing your view controller
+ into the conversation scope und use it in your value-/methodbinding.
+ Additionally, there is a module in Orchestra which will provide convenient functionality
+ en plus - for that, you need to set the managed-bean name to the page-name.
+ <b>Notice:</b> See the ViewController documentation on how to use other naming strategies and so to adjust the mapping
+ from the view-id to your bean names.
</p>
<p>
- Mostly on save actions end the conversation and maybe restart it to review the data.
+ The conversation will be started when the bean is first accessed,
+ it's your job to end the conversation by calling
+ <code>Conversation.getCurrentInstance().invalidate()</code>. You'll do that mostly in save actions
+ after you have saved data to the database.
+ Eventually, you might want to restart the conversation to provide access to the data again.
+ <code>Object yourBackingBean = ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance())</code>
</p>
<p>
- Maybe also provide a way to cancel the current work, which will simply end the conversation.
- (without commit to the database)
+ Often, the user will also be allowed to cancel the current work,
+ in which case Orchestra will simply close the conversation
+ (without commit to the database). For achieving this, simply call:
+ <code>Conversation.getCurrentInstance().invalidate()</code>
+ without having called any persistence-layer save-methods before.
</p>
</subsection>
@@ -60,46 +48,47 @@
<subsection name="Multi Page Conversation">
<p>
- For multi page conversations you have to break through the first suggestion ;-), means,
- its not possible to have the conversation bean the same name than the pages, a bean
- can just have a single name.
+ For multi page conversations you have to break through the first suggestion ;-) which means
+ that it is not possible to have a conversation bean with the same name as the multitude of pages,
+ a bean can of course have a single name only.
</p>
<p>
- And this is not that bad, the suggestion is to use a simple request scoped bean per page
+ The solution for this is to use a simple request scoped bean per page
and a single conversation scoped controller.<br />
If you have three pages, e.g. startPage.jsp, enterPage.jsp, endPage.jsp you'll end up
- with a structure like (note: the names are suggestions only):
+ with a structure like (note: the bean names are suggestions only):
<ul>
<li>Page:startPage.jsp</li>
<li>Page:enterPage.jsp<br/>Bean name: enterPage</li>
<li>Page:endPage.jsp<br/>Bean name: endPage</li>
- <li>Conversation name: pagesController</li>
+ <li>Conversation bean name: pagesController</li>
</ul>
</p>
<p>
- You see, there is no bean required for the startPage. We also require the enterPage and endPage
+ As you can see, there is no bean required for the startPage. We require the enterPage and endPage beans
to check if the conversation is really running.
</p>
<p>
- We have to ensure that the user starts with the startPage. Reasons why this could be violated are:
+ We have to ensure that the user starts with the startPage. Reasons why this might be violated are:
<ul>
<li>the conversation timed out in the mid of the work</li>
- <li>the user tampered the url</li>
+ <li>the user tampered with the url</li>
</ul>
</p>
<p>
Now that we have a mini backing bean for the enterPage and the endPage we can put in code
- to ensure it. We can ensure a conversation has been started, else issue a redirect
- or JSF navigation.
+ to ensure a running conversation. If the conversation has not been started we issue a redirect
+ or execute the JSF navigation system.
</p>
<p>
- Simply add a method called <code>initView()</code> to the enterPage and endPage bean like the
+ To ensure a running conversation, simply add a method called <code>initView()</code>
+ to the enterPage and endPage bean which looks like the
following:
<pre>
public void initView()
@@ -108,19 +97,28 @@
}
</pre>
- <b>Notice:</b> There is also a <code>JsfConversationUtils</code> class which allows you to invoke a navigation.<br/>
- <b>Notice:</b> See the ViewController documentation how to use other strategies or adjust the mapping
- fo the viewId to your bean names.
+ <b>Notice:</b> There is also a <code>JsfConversationUtils</code>-class which allows you to invoke a navigation.<br/>
+
</p>
<p>
- Once the core code has settled we will work out a method how to make this more
- developer friendly, though, for a nice solution it looks like we can't
- avoid the introduction of an annotation based solution.<br/>
- Fully optional then, available when you add the core15 module.
+ TODO - prepare a method to make this more
+ developer friendly, implement this in Orchestra and document it here.
+ However, for a nice solution it looks like we can't
+ avoid the introduction of an annotation based solution
+ which will optionally be available if you add the core15 module.
</p>
+ </subsection>
+
+ <subsection name="Component bindings">
+ <p>
+ Read something about <a href="component-bindings.html">component binding and the scoping problem</a>.
+ </p>
+ <p>
+ This document is not related to Apache MyFaces Orchestra. It's a good reading for every JSF developer.
+ </p>
</subsection>
</section>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/conversationManagement.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/conversationManagement.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/conversationManagement.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/conversationManagement.xml Thu May 24 09:02:57 2007
@@ -82,7 +82,7 @@
Save actions are mostly a good place to end a conversation, you might have done tons of
database queries to e.g. collect the data required to insert a customer into your
ERP database.
- </p>
+ </p> core/target/site/conversationManagement.html
<p>
But what if you would like to present the already created entity again to the user
so that he/she can start to edit the data.
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/index.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/index.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/index.xml Thu May 24 09:02:57 2007
@@ -8,21 +8,123 @@
<body>
<section name="Apache MyFaces Orchestra">
- <p>The youngest project in the Apache MyFaces umbrella.</p>
- <p>It aims to provide a simple way how to deal with persistence in an conversational way</p>
+ <p>
+ Are you fearing the dreaded LazyInitializationException?
+ <br/>
+ Or the ghastly NonUniqueObjectException?
+ <br/>
+ Read on to finally find a solution to such problems...
+ </p>
+ <p>
+ Apache MyFaces Orchestra aims to provide a simple way to combine a web-framework with a persistence
+ layer. Typically, an Apache MyFaces Orchestra stack might combine JavaServer Faces, Spring and
+ a JPA implementation like Toplink, Hibernate, etc.
+ <br/>
+ The underlying idea is to provide long persistence sessions to the web-developer - this is
+ done by associating these sessions with a conversational context.
+ <br/>
+ The conversational context is opened when the bean configured for this context is first loaded.
+ It can be manually closed by the programmer, plus a time-out can be configured as a global
+ parameter.
+ </p>
+
+ <p>Apache MyFaces Orchestra is the latest addition to the Apache MyFaces project family, but
+ has already been used in several real world projects. Check-out our demo-application if you
+ want to see more on how it works in the wild-life.
+ </p>
+
+ <subsection name="A small example">
+ in three parts.
+
+ First, you need to configure a conversation-scoped bean - do that
+ in standard Spring-syntax. Define the name of the scope by setting
+ the scope-attribute; usually you will want to put "conversation" here.
+ <br/>
+
+ Don't forget to add the child-element scoped-proxy - it makes sure
+ injected instances are re-checked (and if necessary, re-instantiated)
+ on every access to the instance.
+ <pre>
+<bean
+ name="ballotTopic"
+ class="org.apache.myfaces.examples.ballot.backings.BallotTopic"
+ scope="conversation"
+ autowire="byName">
+
+ <aop:scoped-proxy/>
- <p>Some Highlights:
+</bean>
+ </pre>
+ The bean named "ballotTopic" can now be used from the JSF-view.
+ It defines properties, methods and event-listeners as usual
+ managed-beans do.
+ <br/>
+ Then, there is the action-method - you define this method as
+ requiring a transaction with the @Transactional annotation
+ (with this, a commit will be executed at the end of the method).
+ Now do whatever you want to do with your beans - save business objects,
+ update them, play around and have fun.
+ When the conversation needs to be closed again, close it by calling
+ the invalidate method on the current conversational instance (the
+ action-method needs to be defined in the conversational bean itself).
+ <code><pre>
+@Transactional
+public String saveAction()
+{
+ topic.setOwner(getVoterDao().getByKey(getBallotState().getVoterId()));
+ topicDao.save(topic);
+
+ Conversation.getCurrentInstance().invalidate();
+
+ return "success";
+} </pre>
+ </code>
+
+ The developer keeps on defining DAO's as she is used to do
+ - here a simple example using the JPA-syntax with an
+ injected EntityManager.
+ <pre>
+public class VoterDao
+{
+ @PersistenceContext
+ private EntityManager entityManager;
+
+ public Voter getByKey(Long id)
+ {
+ return entityManager.find(Voter.class, id);
+ }
+}
+ </pre>
+
+ </subsection>
+
+ <subsection name="Highlights">
<ul>
- <li>It works starting with Java 1.4</li>
- <li>It utilize the powerful Spring bean configuration mechanism</li>
- <li>Thus it integrates nicely with your DAOs and BOs</li>
- <li>Known to work persistence frameworks are JPA and Hibernate, though, any persistence
- framework should be pluggable</li>
- <li>Adaptable to other web frameworks than JSF</li>
- <li>Easy to use API</li>
+ <li>It works with a Java 1.4-compliant syntax, but you can optionally use annotations
+ (in the persistence layer - in the future, additional annotations for
+ Orchestra itself might be added).</li>
+ <li>It utilizes the powerful Spring bean configuration mechanism instead of JSF's
+ managed-bean facility.
+ Departing from Spring 2.0, it is possible to configure session and request-scoped
+ managed-beans in Spring - and you can easily use them from your JSF application.
+ We recommend doing so if you use Spring in your applications - you gain from having
+ one common syntax for defining the beans of your application, from the AOP-support Spring
+ provides, and from other advanced features Spring has included.
+ </li>
+ <li>A plus for integrating Orchestra into existing applications:
+ If you configure your application to use Orchestra, whenever the
+ conversational context is opened,
+ Spring configured DAOs and BOs automatically use the new context and gain
+ from the conversational features of Orchestra. Minimal effort for maximal results!</li>
+ <li>MyFaces Orchestra is know to be compatible to persistence frameworks
+ such as Toplink and Hibernate (and generally any JPA-implementation).
+ However, any persistence framework can be plugged into Orchestra.</li>
+ <li>The Orchestra API can be adapted to use other web frameworks than JSF.</li>
+ <li>Orchestra sports a very easy to use API - maximum 3 method calls, and you're ready to go.</li>
</ul>
- </p>
+ </subsection>
+
</section>
</body>
</document>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml?view=diff&rev=541343&r1=541342&r2=541343
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/usage.xml Thu May 24 09:02:57 2007
@@ -7,63 +7,109 @@
</properties>
<body>
- <section name="Usage">Once you have configure the system like described in
- the installation document you can start using the new scope.
- <p>First of
- all, instead of configuring your beans in the faces-config.xml
- configuration do this in you spring configuration now, in fact you can
- take over ALL your beans into the spring configuration, it also provides
- e.g. the session or request scopes, you gain enormous flexibility in the
- way how your beans should be created, refer to the spring configuration
- for more details.
- </p>
- <p>Here is an example of a conversation scoped
- bean:
- </p>
- <pre><bean name="userInfo"
- class="my.app.pck.backings.UserInfo"
- scope="conversation"
- autowire="byName">
- <aop:scoped-proxy />
- </bean></pre>
- <p>Beside the fact that you use
- <code>
- <b>scope="conversation</b>
- </code>
- " it is very important to use the
- <b>
- <code><aop:scoped-proxy /></code>
- </b>
- configuration.
- </p>
- <p>The
- <code><aop:scoped-proxy /></code>
- ensures that you will never see
- the real instance of your bean, but a proxy to it. There is no difference
- in the way how you work with this instance in your code, but, there are
- use cases where you will end a conversation and restart it. That way it is
- ensured that your application will see this new instance.
- </p>
- <p>The
- <code>autowire="byName"</code>
- configuration is fully optional, but it
- lowers the number of configuration lines required. Spring will scan your
- bean and inject for each property where it find a bean with the same name
- an instance of it.
- </p>
- <p>For example, if you have a bean named
- <code>userInfoDao</code>
- and your bean has a
- <code>setUserInfoDao()</code>
- method it will receive an instance of this DAO.
- </p>
- <p>Next is the
- transaction handling.
+ <section name="Usage">
+ <p>
+ Once you have configured the system as described in
+ the installation document you can start using the new scope.
+ </p>
+
+ <p>
+ One more prerequisite: instead of configuring your beans in the faces-config.xml
+ configuration do this in your spring configuration now. You can
+ take over all your beans into the Spring configuration, Spring also provides
+ a session and a request scope.
+ </p>
+
+ <p>
+ With this in place, we'll start evaluating the Orchestra-relevant use-cases now - so we'll
+ together look at what you will want to do with Orchestra.
+ </p>
+
+ <subsection name="Starting a conversation">
+ In the beginning, we'll want to start a conversation. Doing that is a no-brainer in Orchestra - if
+ you've declared the relevant managed beans as in the following example:
+ <code><pre><bean name="userInfo"
+ class="my.app.pck.backings.UserInfo"
+ scope="conversation"
+ autowire="byName">
+ <aop:scoped-proxy />
+ </bean></pre></code>
+ <p>
+ We've learned about this syntax in the small example in the introduction - a short repetition:
+ <br/>
+ First, the scope-attribute of the bean-element will be defining the name of the scope -
+ usually "conversation".
+ <br/>
+ Second, it is very important to use the
+ <b>
+ <code><aop:scoped-proxy /></code>
+ </b>
+ child-element. Bear with us - we'll explain to you why that is right now.
+ <br/>
+ Using the <code><aop:scoped-proxy /></code>
+ ensures that you will never have a reference to
+ the real instance of your bean, but to a proxy to it. There is no difference
+ in the way how you work with this instance in your code, but if you
+ end a conversation and restart it, you'll appreciate the difference: the proxy will make
+ sure that your application will see the new instance.
+ </p>
+ <p>The
+ <code>autowire="byName"</code>
+ Setting this property is fully optional. However, it
+ lowers the amount of configuration required. With this property set, Spring will scan your
+ bean configuration. Whenever it finds a bean with the same name as the property, it
+ will inject an instance of this bean configuration into this property.
+ </p>
+ <p>For example, if you configure a bean named
+ <code>userInfoDao</code>
+ and your bean has a
+ <code>setUserInfoDao()</code>
+ method Spring will inject an instance of this DAO into your bean.
+ </p>
+ </subsection>
+
+ <subsection name="Closing a conversation">
+ <p>
+ Closing a conversation is straightforward as well.
+ All that needs to be done is to call:
+ <pre>
+ <code>Conversation.getCurrentInstance().invalidate()</code>
+ </pre>
+ from within the conversation-scoped bean. With this call, the conversation will cease to exist
+ and the bean will be cleared from the conversation.
</p>
+ </subsection>
+
+ <subsection name="Restart a conversation">
+ <p>
+ At times, you do not only want to close a conversation, but you also want to restart it
+ immediately. For this, use the following call:
+ <code>Object yourBackingBean = ConversationUtils.invalidateAndRestart(Conversation.getCurrentInstance())</code>
+ With the returned object, you can do configuration and initialization work.
+ </p>
+ </subsection>
+
+ <subsection name="Ensure a conversation is running">
+ <p>
+ If you have a conversation running over a multitude of pages,
+ you might want to check if the conversation has been initialized before you reach the page.
+ For doing this, you can call the method:
+
+ <code>ConversationUtils.ensureConversationRedirect(conversationName, redirectToJsp)</code>
+
+ before the conversation is first accessed on this page, as in an initialization or
+ prerender-method.
+ </p>
+ </subsection>
+
+ <subsection name="End a conversation by name">
+<code>ConversationUtils.invalidateIfExists(conversationName)</code>
+ </subsection>
+
<subsection name="JPA Transaction">
<b>Note</b>
:
- Once again I would like to stress that Apache MyFaces Orchestra do not rely
+ Once again I would like to stress that Apache MyFaces Orchestra does not rely
on annotations, the JPA thing was just the one we build the examples with,
thats why we describe it at first.
<p>Every method in your conversation
@@ -86,7 +132,11 @@
but it will only be flushed after such an annotated method has been
invoked.
</p>
+
+
</subsection>
+
+
</section>
</body>
</document>