myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r512962 - in /myfaces/fusion/trunk/core/src/site/xdoc: ./ about.xml installation.xml
Date Wed, 28 Feb 2007 20:53:55 GMT
Author: imario
Date: Wed Feb 28 12:53:54 2007
New Revision: 512962

start of documentation


Added: myfaces/fusion/trunk/core/src/site/xdoc/about.xml
--- myfaces/fusion/trunk/core/src/site/xdoc/about.xml (added)
+++ myfaces/fusion/trunk/core/src/site/xdoc/about.xml Wed Feb 28 12:53:54 2007
@@ -0,0 +1,126 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+  <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>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>
+      </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>
\ No newline at end of file

Added: myfaces/fusion/trunk/core/src/site/xdoc/installation.xml
--- myfaces/fusion/trunk/core/src/site/xdoc/installation.xml (added)
+++ myfaces/fusion/trunk/core/src/site/xdoc/installation.xml Wed Feb 28 12:53:54 2007
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE document PUBLIC "-//Apache Software Foundation//DTD XDOC 1.0//EN"
+  <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
+    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=""
+       xmlns:xsi=""
+       xmlns:tx=""
+       xmlns:aop=""
+       xsi:schemaLocation="
+  "&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=""/&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=""&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
+        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>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
+    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
+    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
+    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>
\ No newline at end of file

View raw message