svn commit: r513637 - in /myfaces/fusion/trunk/core/src/site/xdoc: about.xml convUseCases.xml installation.xml usage.xml

[im...@apache.org]

Author: imario
Date: Thu Mar  1 22:56:16 2007
New Revision: 513637

URL: http://svn.apache.org/viewvc?view=rev&rev=513637
Log:
reformat

Modified:
    myfaces/fusion/trunk/core/src/site/xdoc/about.xml
    myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml
    myfaces/fusion/trunk/core/src/site/xdoc/installation.xml
    myfaces/fusion/trunk/core/src/site/xdoc/usage.xml

Modified: myfaces/fusion/trunk/core/src/site/xdoc/about.xml
URL: http://svn.apache.org/viewvc/myfaces/fusion/trunk/core/src/site/xdoc/about.xml?view=diff&rev=513637&r1=513636&r2=513637
==============================================================================
--- myfaces/fusion/trunk/core/src/site/xdoc/about.xml (original)
+++ myfaces/fusion/trunk/core/src/site/xdoc/about.xml Thu Mar  1 22:56:16 2007
@@ -1,135 +1,202 @@
 <?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">
+	"http://www.apache.org/dtd/xdoc.dtd">
 <document>
-  <properties>
-    <title>new documen</title>
-  </properties>
-
-  <body>
-    <section name="Apache MyFaces Fusion"><p>Apache MyFaces Fusion 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.</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 <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 Fusion; inspired from JBoss Seam; introduce the conversation scope
-    to deal with this kind of workflow.</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
-    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><subsection
-    name="Definitions"><ul>
-        <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
-        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.</li>
-
-        <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
-        data is called metadata.</li>
-
-        <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:<table width="40%">
-            <tr>
-              <th>Member</th>
-
-              <th>getter</th>
-
-              <th>setter</th>
-            </tr>
-
-            <tr>
-              <th>userId</th>
-
-              <td>getUserId</td>
-
-              <td>setUserId</td>
-            </tr>
-
-            <tr>
-              <th>_userName</th>
-
-              <td>getUserName</td>
-
-              <td>setUserName</td>
-            </tr>
-          </table></li>
-
-        <li>entity manager<br />The "entity manager" manage 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 object"
-        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 them.</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
-        manager.</li>
-
-        <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</li>
-
-        <li>session scope<br />The session scope of your servlet container.
-        Beans put into this scope live until a inactivity timout has been
-        reached</li>
-
-        <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 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.</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
-        good practice to do it that way.</li>
-      </ul></subsection><subsection name="Structure">As pre now, the Apache
-    MyFaces Fusion 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
-        Java 5.0</li>
-
-        <li>core15<br />Ok, but we couldn't resist, this package will contain
-        Java 5.0 enhancements to the core.</li>
-
-        <li>examples</li>
-      </ul></subsection></section>
-  </body>
+	<properties>
+		<title>About Apache MyFaces Fusion</title>
+	</properties>
+
+	<body>
+		<section name="Apache MyFaces Fusion">
+			<p>Apache MyFaces Fusion 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.
+			</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
+				<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 Fusion; inspired from JBoss Seam; introduce the conversation scope
+				to deal with this kind of workflow.
+			</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
+				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>
+			<subsection
+				name="Definitions">
+				<ul>
+					<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
+						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.
+					</li>
+
+					<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
+						data is called metadata.
+					</li>
+
+					<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:
+						<table width="40%">
+							<tr>
+								<th>Member</th>
+
+								<th>getter</th>
+
+								<th>setter</th>
+							</tr>
+
+							<tr>
+								<th>userId</th>
+
+								<td>getUserId</td>
+
+								<td>setUserId</td>
+							</tr>
+
+							<tr>
+								<th>_userName</th>
+
+								<td>getUserName</td>
+
+								<td>setUserName</td>
+							</tr>
+						</table>
+					</li>
+
+					<li>entity manager
+						<br/>
+						The "entity manager" manage 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 object"
+						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 them.
+					</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
+						manager.
+					</li>
+
+					<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
+					</li>
+
+					<li>session scope
+						<br/>
+						The session scope of your servlet container.
+						Beans put into this scope live until a inactivity timout has been
+						reached
+					</li>
+
+					<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 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.
+					</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
+						good practice to do it that way.
+					</li>
+				</ul>
+			</subsection>
+			<subsection name="Structure">As pre now, the Apache
+				MyFaces Fusion 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
+						Java 5.0
+					</li>
+
+					<li>core15
+						<br/>
+						Ok, but we couldn't resist, this package will contain
+						Java 5.0 enhancements to the core.
+					</li>
+
+					<li>examples</li>
+				</ul>
+			</subsection>
+		</section>
+	</body>
 </document>

Modified: myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml
URL: http://svn.apache.org/viewvc/myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml?view=diff&rev=513637&r1=513636&r2=513637
==============================================================================
--- myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml (original)
+++ myfaces/fusion/trunk/core/src/site/xdoc/convUseCases.xml Thu Mar  1 22:56:16 2007
@@ -1,19 +1,22 @@
 <?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">
+	"http://www.apache.org/dtd/xdoc.dtd">
 <document>
-  <properties>
-    <title>new document</title>
-  </properties>
+	<properties>
+		<title>Conversation Use Cases</title>
+	</properties>
 
-  <body>
-    <section name="Conversation Use Cases">There are some use cases a
-    conversation has:<ul>
-        <li>start a conversation</li>
+	<body>
+		<section name="Conversation Use Cases">There are some use cases a
+			conversation has:
+			<ul>
+				<li>start a conversation</li>
 
-        <li>end a conversation</li>
+				<li>end a conversation</li>
 
-        <li>end and restart a conversation</li>
-      </ul><subsection name="Start a conversation"></subsection></section>
-  </body>
+				<li>end and restart a conversation</li>
+			</ul>
+			<subsection name="Start a conversation"></subsection>
+		</section>
+	</body>
 </document>

Modified: myfaces/fusion/trunk/core/src/site/xdoc/installation.xml
URL: http://svn.apache.org/viewvc/myfaces/fusion/trunk/core/src/site/xdoc/installation.xml?view=diff&rev=513637&r1=513636&r2=513637
==============================================================================
--- myfaces/fusion/trunk/core/src/site/xdoc/installation.xml (original)
+++ myfaces/fusion/trunk/core/src/site/xdoc/installation.xml Thu Mar  1 22:56:16 2007
@@ -1,172 +1,226 @@
 <?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">
+	"http://www.apache.org/dtd/xdoc.dtd">
 <document>
-  <properties>
-    <title>new document</title>
-  </properties>
-
-  <body>
-    <section name="Installation">Its assumed that you know how to setup <ul>
-        <li>a servlet container (Tomcat, Jetty, etc)</li>
-
-        <li>your ORM tool (OpenJPA, Toplink.essentials, Hibernate, etc)</li>
-
-        <li>your JSF implementation (MyFaces, JSF-RI, etc)</li>
-      </ul><p>For a beginner these are serious assumptions, though, anything
-    else would have blast this guide.</p>The installation guide will show how
-    to setup a JPA entity manager, alter a chapter for Hibernate will be
-    added.<subsection name="Prerequisites"><ul>
-        <li>Apache MyFaces Fusion core</li>
-
-        <li>Apache MyFaces Fusion core15</li>
-
-        <li>Spring 2.x</li>
-
-        <li>a JSF implementation (e.g. JSF-RI, MyFaces)</li>
-
-        <li>a JPA implementation (e.g. OpenJPA, toplink.essentials (formerly
-        Oracle Toplink)</li>
-
-        <li>and all their dependencies<br />I admit this is somehow vague, but
-        it depends on the JSF and JPA implementation. If you have to setup
-        this kind of thing from scratch it might be best to have a look at our
-        examples package.</li>
-      </ul></subsection><subsection name="Spring configuration">Apache MyFaces
-    Fusion uses the powerful Spring configuration to provide its conversation
-    scope. In contrast to the JSF faces-config managed bean facility Spring
-    offers tremendous features, e.g. it allows us to create a new
-    scope.<p>Lets start with the Spring configuration for the conversation
-    scope and the JPA entity manager factory. This configuration file has to
-    be placed into the WEB-INF directory of your web application using the
-    name applicationContext.xml. This can be configured, just have a look at
-    the Spring documentation.</p><pre>&lt;?xml version="1.0" encoding="UTF-8"?&lt;
-
-&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"
-       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;!-- 1. the conversation scope --&gt;
-    &lt;bean class="org.springframework.beans.factory.config.CustomScopeConfigurer"&gt;
-        &lt;property name="scopes"&gt;
-            &lt;map&gt;
-                &lt;entry key="conversation"&gt;
-                    &lt;bean class="org.apache.myfaces.fusion.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;!-- 2. the "entitiy manager" manager --&gt;
-    &lt;bean id="persistentContextConversationInterceptor"
-          class="org.apache.myfaces.fusion.conversation.spring.PersistenceContextConversationInterceptor"&gt;
-        &lt;property name="persistenceContextFactory" ref="persistentContextFactory"/&gt;
-    &lt;/bean&gt;
-
-    &lt;!-- 3. conversation - persistence adapter --&gt;
-    &lt;bean id="persistentContextFactory"
-          class="org.apache.myfaces.fusion.conversation.persistenceContexts.JpaPersistenceContextFactory"&gt;
-        &lt;property name="entityManagerFactory" ref="entityManagerFactory"/&gt;
-    &lt;/bean&gt;
-
-    &lt;!-- 4. persistence --&gt;
-    &lt;bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/&gt;
-
-    &lt;tx:annotation-driven /&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="entityManagerFactory"
-          class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean"&gt;
-        &lt;property name="jpaProperties"&gt;
-            &lt;props&gt;
-                &lt;prop key="toplink.logging.level"&lt;FINE&lt;/prop&gt;
-                &lt;prop key="toplink.jdbc.driver"&lt;org.apache.derby.jdbc.EmbeddedDriver&lt;/prop&gt;
-                &lt;prop key="toplink.jdbc.url"&lt;jdbc:derby:myfacesFusionDB;create=true&lt;/prop&gt;
-                &lt;prop key="toplink.jdbc.user"&lt;sa&lt;/prop&gt;
-                &lt;prop key="toplink.jdbc.password"&lt;foobar&lt;/prop&gt;
-                &lt;prop key="toplink.target-database"&lt;oracle.toplink.essentials.platform.database.DerbyPlatform&lt;/prop&gt;
-                &lt;prop key="toplink.ddl-generation"&lt;create-tables&lt;/prop&gt;
-            &lt;/props&gt;
-        &lt;/property&gt;
-        &lt;property name="persistenceUnitName" value="default"/&gt;
-    &lt;/bean&gt;
-
-&lt;/beans&gt;</pre><p>Ok, this might look a little bit much for the start of
-    an installation guide, though, its not that complicated. So, head up, lets
-    go through this configuration step by step.</p><ul>
-        <li>1. the conversation scope<br />There we configure the conversation
-        scope as a Spring custom scope. This configuration allows us to use
-        scope="conversation" with our beans. This scope implementation also
-        allows you to configure a number of advices. Advices intercept each
-        method call to your bean. We build on this mechanism to configure the
-        entity manager appropriate.<br />If your application do not have to
-        deal with persistence, but you would like to use the conversation
-        scope you can delete the advices from this configuration.</li>
-
-        <li>2. the "entity manager" manager<br />This is the interceptor which
-        ensures that the correct entity manager has been set before any method
-        of your conversation bean will be called.</li>
-
-        <li>3. conversation - persistence adapter<br />Depending on the ORM
-        tool you use you have to configure a persistenceContextFactory. Apache
-        MyFaces Fusion will provide a JPA implementation in its core15
-        package. Its under discussion that these adapter classes will be moved
-        into Spring.</li>
-
-        <li>4.persistence<br />This is one of the ways how to configure a
-        entity manager factory and the persistence framework in Spring. You
-        can adapt this part as you like, just have a look at the Spring
-        documentation. For example, we use
-        <code>&lt;tx:annotation-driven/&gt;</code>, if you have to stay with
-        Java 1.4 you can choose any other Spring configuration. Apache MyFaces
-        Fusion DO NOT RELY on annotations. The above configuration is just the
-        one I used for our examples.</li>
-      </ul><p><b>Notice</b>: You'll be able to configure multiple conversation
-    scopes (with different names for sure) using different persistence
-    strategies or without persistence at all.</p><p>Thats all for Spring,
-    following the JPA specifiacation and the way we configured JPA above, you
-    have to provide a META-INF/persistence.xml too. But that is not related to
-    Apache MyFaces Fusion.</p></subsection><subsection
-    name="JSF configuration">Next you have to add two things to your web.xml
-    configuration. They are:<ul>
-        <li>The Spring listeners</li>
-
-        <li>The Apache MyFaces Fusion RequestParameterServletFilter</li>
-      </ul><p>So this looks like:</p><pre>    &lt;listener&gt;
-        &lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
-    &lt;/listener&gt;
-    &lt;listener&gt;
-        &lt;listener-class&gt;org.springframework.web.context.request.RequestContextListener&lt;/listener-class&gt;
-    &lt;/listener&gt;</pre><p>and</p><pre>    &lt;filter&gt;
-        &lt;filter-name&gt;requestParameterFilter&lt;/filter-name&gt;
-        &lt;filter-class&gt;org.apache.myfaces.fusion.requestParameterProvider.RequestParameterServletFilter&lt;/filter-class&gt;
-    &lt;/filter&gt;
-
-    &lt;filter-mapping&gt;
-        &lt;filter-name&gt;requestParameterFilter&lt;/filter-name&gt;
-        &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
-    &lt;/filter-mapping&gt;</pre><p>The RequestParameterServletFilter is
-    responsible to ensure the addition of a conversation related parameter to
-    the url. It does this by wrapping the ServletResponse and override the
-    encodeURL methods.</p></subsection><subsection name="Conclusion">Thats all
-    for the basic configuration of Apache MyFaces Fusion, now you should have
-    a working conversation scope. In fact there is nothing special in creating
-    the database access objects (dao) or your business objects (bo). Also your
-    JSF page backing bean will look the same, just that you put it into the
-    conversation scope now.</subsection></section>
-  </body>
+	<properties>
+		<title>Installation</title>
+	</properties>
+
+	<body>
+		<section name="Installation">Its assumed that you know how to setup
+			<ul>
+				<li>a servlet container (Tomcat, Jetty, etc)</li>
+
+				<li>your ORM tool (OpenJPA, Toplink.essentials, Hibernate, etc)</li>
+
+				<li>your JSF implementation (MyFaces, JSF-RI, etc)</li>
+			</ul>
+			<p>For a beginner these are serious assumptions, though, anything
+				else would have blast this guide.
+			</p>
+			The installation guide will show how
+			to setup a JPA entity manager, alter a chapter for Hibernate will be
+			added.
+			<subsection name="Prerequisites">
+				<ul>
+					<li>Apache MyFaces Fusion core</li>
+
+					<li>Apache MyFaces Fusion core15</li>
+
+					<li>Spring 2.x</li>
+
+					<li>a JSF implementation (e.g. JSF-RI, MyFaces)</li>
+
+					<li>a JPA implementation (e.g. OpenJPA, toplink.essentials (formerly
+						Oracle Toplink)
+					</li>
+
+					<li>and all their dependencies
+						<br/>
+						I admit this is somehow vague, but
+						it depends on the JSF and JPA implementation. If you have to setup
+						this kind of thing from scratch it might be best to have a look at our
+						examples package.
+					</li>
+				</ul>
+			</subsection>
+			<subsection name="Spring configuration">Apache MyFaces
+				Fusion uses the powerful Spring configuration to provide its conversation
+				scope. In contrast to the JSF faces-config managed bean facility Spring
+				offers tremendous features, e.g. it allows us to create a new
+				scope.
+				<p>Lets start with the Spring configuration for the conversation
+					scope and the JPA entity manager factory. This configuration file has to
+					be placed into the WEB-INF directory of your web application using the
+					name applicationContext.xml. This can be configured, just have a look at
+					the Spring documentation.
+				</p>
+				<pre>&lt;?xml version="1.0" encoding="UTF-8"?&lt;
+
+					&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"
+					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;!-- 1. the conversation scope --&gt;
+					&lt;bean class="org.springframework.beans.factory.config.CustomScopeConfigurer"&gt;
+					&lt;property name="scopes"&gt;
+					&lt;map&gt;
+					&lt;entry key="conversation"&gt;
+					&lt;bean class="org.apache.myfaces.fusion.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;!-- 2. the "entitiy manager" manager --&gt;
+					&lt;bean id="persistentContextConversationInterceptor"
+					class="org.apache.myfaces.fusion.conversation.spring.PersistenceContextConversationInterceptor"&gt;
+					&lt;property name="persistenceContextFactory" ref="persistentContextFactory"/&gt;
+					&lt;/bean&gt;
+
+					&lt;!-- 3. conversation - persistence adapter --&gt;
+					&lt;bean id="persistentContextFactory"
+					class="org.apache.myfaces.fusion.conversation.persistenceContexts.JpaPersistenceContextFactory"&gt;
+					&lt;property name="entityManagerFactory" ref="entityManagerFactory"/&gt;
+					&lt;/bean&gt;
+
+					&lt;!-- 4. persistence --&gt;
+					&lt;bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/&gt;
+
+					&lt;tx:annotation-driven /&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="entityManagerFactory"
+					class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean"&gt;
+					&lt;property name="jpaProperties"&gt;
+					&lt;props&gt;
+					&lt;prop key="toplink.logging.level"&lt;FINE&lt;/prop&gt;
+					&lt;prop key="toplink.jdbc.driver"&lt;org.apache.derby.jdbc.EmbeddedDriver&lt;/prop&gt;
+					&lt;prop key="toplink.jdbc.url"&lt;jdbc:derby:myfacesFusionDB;create=true&lt;/prop&gt;
+					&lt;prop key="toplink.jdbc.user"&lt;sa&lt;/prop&gt;
+					&lt;prop key="toplink.jdbc.password"&lt;foobar&lt;/prop&gt;
+					&lt;prop key="toplink.target-database"&lt;oracle.toplink.essentials.platform.database.DerbyPlatform&lt;/prop&gt;
+					&lt;prop key="toplink.ddl-generation"&lt;create-tables&lt;/prop&gt;
+					&lt;/props&gt;
+					&lt;/property&gt;
+					&lt;property name="persistenceUnitName" value="default"/&gt;
+					&lt;/bean&gt;
+
+					&lt;/beans&gt;</pre>
+				<p>Ok, this might look a little bit much for the start of
+					an installation guide, though, its not that complicated. So, head up, lets
+					go through this configuration step by step.
+				</p>
+				<ul>
+					<li>1. the conversation scope
+						<br/>
+						There we configure the conversation
+						scope as a Spring custom scope. This configuration allows us to use
+						scope="conversation" with our beans. This scope implementation also
+						allows you to configure a number of advices. Advices intercept each
+						method call to your bean. We build on this mechanism to configure the
+						entity manager appropriate.
+						<br/>
+						If your application do not have to
+						deal with persistence, but you would like to use the conversation
+						scope you can delete the advices from this configuration.
+					</li>
+
+					<li>2. the "entity manager" manager
+						<br/>
+						This is the interceptor which
+						ensures that the correct entity manager has been set before any method
+						of your conversation bean will be called.
+					</li>
+
+					<li>3. conversation - persistence adapter
+						<br/>
+						Depending on the ORM
+						tool you use you have to configure a persistenceContextFactory. Apache
+						MyFaces Fusion will provide a JPA implementation in its core15
+						package. Its under discussion that these adapter classes will be moved
+						into Spring.
+					</li>
+
+					<li>4.persistence
+						<br/>
+						This is one of the ways how to configure a
+						entity manager factory and the persistence framework in Spring. You
+						can adapt this part as you like, just have a look at the Spring
+						documentation. For example, we use
+						<code>&lt;tx:annotation-driven/&gt;</code>
+						, if you have to stay with
+						Java 1.4 you can choose any other Spring configuration. Apache MyFaces
+						Fusion DO NOT RELY on annotations. The above configuration is just the
+						one I used for our examples.
+					</li>
+				</ul>
+				<p>
+					<b>Notice</b>
+					: You'll be able to configure multiple conversation
+					scopes (with different names for sure) using different persistence
+					strategies or without persistence at all.
+				</p>
+				<p>Thats all for Spring,
+					following the JPA specifiacation and the way we configured JPA above, you
+					have to provide a META-INF/persistence.xml too. But that is not related to
+					Apache MyFaces Fusion.
+				</p>
+			</subsection>
+			<subsection
+				name="JSF configuration">Next you have to add two things to your web.xml
+				configuration. They are:
+				<ul>
+					<li>The Spring listeners</li>
+
+					<li>The Apache MyFaces Fusion RequestParameterServletFilter</li>
+				</ul>
+				<p>So this looks like:</p>
+				<pre>	&lt;listener&gt;
+					&lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
+					&lt;/listener&gt;
+					&lt;listener&gt;
+					&lt;listener-class&gt;org.springframework.web.context.request.RequestContextListener&lt;/listener-class&gt;
+					&lt;/listener&gt;</pre>
+				<p>and</p>
+				<pre>	&lt;filter&gt;
+					&lt;filter-name&gt;requestParameterFilter&lt;/filter-name&gt;
+					&lt;filter-class&gt;org.apache.myfaces.fusion.requestParameterProvider.RequestParameterServletFilter&lt;/filter-class&gt;
+					&lt;/filter&gt;
+
+					&lt;filter-mapping&gt;
+					&lt;filter-name&gt;requestParameterFilter&lt;/filter-name&gt;
+					&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+					&lt;/filter-mapping&gt;</pre>
+				<p>The RequestParameterServletFilter is
+					responsible to ensure the addition of a conversation related parameter to
+					the url. It does this by wrapping the ServletResponse and override the
+					encodeURL methods.
+				</p>
+			</subsection>
+			<subsection name="Conclusion">Thats all
+				for the basic configuration of Apache MyFaces Fusion, now you should have
+				a working conversation scope. In fact there is nothing special in creating
+				the database access objects (dao) or your business objects (bo). Also your
+				JSF page backing bean will look the same, just that you put it into the
+				conversation scope now.
+			</subsection>
+		</section>
+	</body>
 </document>

Modified: myfaces/fusion/trunk/core/src/site/xdoc/usage.xml
URL: http://svn.apache.org/viewvc/myfaces/fusion/trunk/core/src/site/xdoc/usage.xml?view=diff&rev=513637&r1=513636&r2=513637
==============================================================================
--- myfaces/fusion/trunk/core/src/site/xdoc/usage.xml (original)
+++ myfaces/fusion/trunk/core/src/site/xdoc/usage.xml Thu Mar  1 22:56:16 2007
@@ -1,51 +1,92 @@
 <?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">
+	"http://www.apache.org/dtd/xdoc.dtd">
 <document>
-  <properties>
-    <title>new document</title>
-  </properties>
+	<properties>
+		<title>Usage</title>
+	</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>&lt;bean name="userInfo"
-      class="my.app.pck.backings.UserInfo"
-      scope="conversation"
-      autowire="byName"&gt;
-    &lt;aop:scoped-proxy /&gt;
-&lt;/bean&gt;</pre><p>Beside the fact that you use
-    <code><b>scope="conversation</b></code>" it is very important to use the
-    <b><code>&lt;aop:scoped-proxy /&gt;</code></b> configuration.</p><p>The
-    <code>&lt;aop:scoped-proxy /&gt;</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 s<code>etUserInfoDao()</code>
-    method it will receive an instance of this DAO.</p><p>Next is the
-    transaction handling.</p><subsection name="JPA Transaction"><b>Note</b>:
-    Once again I would like to stress that Apache MyFaces Fusion do not rely
-    on annotations, the JPA thing was just the one we build the examples with,
-    thats why we describe it at first.<p>Every method in your conversation
-    bean is able to issue a database request or to call e.g. a DAO which will
-    do it. Its ensured that during the whole lifetime of this conversation
-    bean all database code will see the same entity manager.</p><p>Methods
-    which change data has to be annotated with the <code>@Transactional</code>
-    annotation.</p><p>Which means, that every changed/inserted/deleted entity
-    will be flushed to the database and committed.</p><p>Thats an important
-    thing to understand. You <b>can</b> change an entity whenever you want,
-    but it will only be flushed after such an annotated method has been
-    invoked.</p></subsection></section>
-  </body>
+	<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>&lt;bean name="userInfo"
+				class="my.app.pck.backings.UserInfo"
+				scope="conversation"
+				autowire="byName"&gt;
+				&lt;aop:scoped-proxy /&gt;
+				&lt;/bean&gt;</pre>
+			<p>Beside the fact that you use
+				<code>
+					<b>scope="conversation</b>
+				</code>
+				" it is very important to use the
+				<b>
+					<code>&lt;aop:scoped-proxy /&gt;</code>
+				</b>
+				configuration.
+			</p>
+			<p>The
+				<code>&lt;aop:scoped-proxy /&gt;</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 s
+				<code>etUserInfoDao()</code>
+				method it will receive an instance of this DAO.
+			</p>
+			<p>Next is the
+				transaction handling.
+			</p>
+			<subsection name="JPA Transaction">
+				<b>Note</b>
+				:
+				Once again I would like to stress that Apache MyFaces Fusion do not rely
+				on annotations, the JPA thing was just the one we build the examples with,
+				thats why we describe it at first.
+				<p>Every method in your conversation
+					bean is able to issue a database request or to call e.g. a DAO which will
+					do it. Its ensured that during the whole lifetime of this conversation
+					bean all database code will see the same entity manager.
+				</p>
+				<p>Methods
+					which change data has to be annotated with the
+					<code>@Transactional</code>
+					annotation.
+				</p>
+				<p>Which means, that every changed/inserted/deleted entity
+					will be flushed to the database and committed.
+				</p>
+				<p>Thats an important
+					thing to understand. You
+					<b>can</b>
+					change an entity whenever you want,
+					but it will only be flushed after such an annotated method has been
+					invoked.
+				</p>
+			</subsection>
+		</section>
+	</body>
 </document>